diff --git a/deno.json b/deno.json index 062b8d1..f366d5b 100644 --- a/deno.json +++ b/deno.json @@ -2,7 +2,7 @@ "tasks": { "test": "deno test -A && deno check --config=www/deno.json www/main.ts www/dev.ts && deno check init.ts", "fixture": "deno run -A --watch=static/,routes/ tests/fixture/dev.ts", - "www": "deno run -A --watch=static/,routes/ www/dev.ts", + "www": "deno run -A --watch=www/static/,www/routes/,docs/ www/dev.ts", "screenshot": "deno run -A www/utils/screenshot.ts" }, "importMap": "./.vscode/import_map.json", diff --git a/docs/concepts/updating.md b/docs/concepts/updating.md new file mode 100644 index 0000000..3792a3e --- /dev/null +++ b/docs/concepts/updating.md @@ -0,0 +1,122 @@ +--- +description: | + Fresh regularly releases new versions of the framework. This page explains how to update your project. +--- + +Fresh constists of multiple pieces which are independently versioned and +released. + +- Fresh (https://deno.land/x/fresh) +- Preact (https://esm.sh/preact) +- preact-render-to-string (https://esm.sh/preact-render-to-string) + +Some plugins also have their own dependencies that can be updated independently. + +- Twind (https://esm.sh/twind) (for the twind plugin) + +For the most part these pieces can be updated independently. Certain versions of +Fresh may require a minimum version of a given dependency. This is documented +below. + +| Fresh version | Preact | preact-render-to-string | Deno | +| ------------- | ---------------- | ----------------------- | --------- | +| 1.0.0-1.0.2 | >=10.8.1 <11.0.0 | >=5.2.0 <6.0.0 | >= 1.23.0 | +| 1.1.0 | >=10.8.1 <11.0.0 | >=5.2.0 <6.0.0 | >= 1.25.0 | + +## Updating dependencies + +To update your dependencies, you have two options: + +- Run the fresh updater to update your project dependencies. +- Manually update the dependency versions in your `import_map.json` file. + +### Auto updater + +The auto updater is a command line tool that will update your project's +`import_map.json` file to the latest versions of Fresh and its dependencies. It +may also contain code mods for your project that will update your code to the +latest recommended patterns for Fresh projects. + +To run the auto updater, run the following command from the root of your +project: + +```bash +$ deno run -A https://fresh.deno.dev/update . +``` + +You will be prompted to confirm the changes that will be made to your project. + +### Manual update + +To manually update your project's dependencies, you can edit the +`import_map.json` file in the root of your projects directory. Dependency +versions are encoded into the URLs in this file. For example, here is how to +update a project from Fresh 1.0.2 to 1.1.0, and update Preact to the latest +version: + +```diff + { + "imports": { +- "$fresh/": "https://deno.land/x/fresh@1.0.2/", ++ "$fresh/": "https://deno.land/x/fresh@1.1.0/", + +- "preact": "https://esm.sh/preact@10.8.1", +- "preact/": "https://esm.sh/preact@10.8.1/", ++ "preact": "https://esm.sh/preact@10.10.6", ++ "preact/": "https://esm.sh/preact@10.10.6/", + +- "preact-render-to-string": "https://esm.sh/*preact-render-to-string@5.2.0", ++ "preact-render-to-string": "https://esm.sh/*preact-render-to-string@5.2.2", + + "twind": "https://esm.sh/twind@0.16.17", + "twind/": "https://esm.sh/twind@0.16.17/" + } + } +``` + +## Code mods + +Code mods are small scripts that can be run to update your project's code to +match the latest recommended patterns for Fresh projects. Code mods can be run +through the auto updater. Sometimes the code mod can not cover all cases, so you +may need to manually update some code. This section explains the code mods +currently available. + +### Classical JSX -> Automatic JSX + +> This code mod is only available in Fresh 1.1.0 and above. + +The classical JSX transform that relies on a `/** @jsx h */` pragma is no longer +the recommended way to use JSX in Fresh projects. Instead, starting with version +1.1.0, Fresh projects should use the automatic JSX transform that requires no +JSX pragma or preact import. + +```diff +- /** @jsx h */ +- import { h } from "preact"; + + export default function Page() { + return
Hello world!
; + } +``` + +This code mod will update your deno.json file to include the relevant compiler +options to enable the automatic JSX transform. It will then go through your +project and remove any `/** @jsx h */` pragmas and `import { h } from "preact"` +statements. + +### Classic twind -> Twind plugin + +> This code mod is only available in Fresh 1.1.0 and above. + +Fresh version 1.1.0 introduced a new plugin for using twind with Fresh. This +plugin is much nicer to use than the raw twind integration that was previously +available. + +This code mod will update your project to use the new twind plugin. It will +update your `main.ts` file to import the twind plugin and add it to the plugins +array. It will also update your files to remove many unnecessary uses of the +`tw` function, and remove unnecessary twind imports. While the code mod can +handle most cases, you may need to manually update some code. Additionally you +will need to manually update your `twind.config.ts` if you use a custom +configuration. diff --git a/docs/toc.json b/docs/toc.json index 31e8884..e916edb 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -27,7 +27,8 @@ ["error-pages", "Error pages"], ["routing", "Routing"], ["data-fetching", "Data fetching"], - ["deployment", "Deployment"] + ["deployment", "Deployment"], + ["updating", "Updating Fresh"] ] } } diff --git a/www/utils/markdown.ts b/www/utils/markdown.ts index 6e6ae9e..b880e64 100644 --- a/www/utils/markdown.ts +++ b/www/utils/markdown.ts @@ -2,5 +2,6 @@ export * as gfm from "https://deno.land/x/gfm@0.1.23/mod.ts"; import "https://esm.sh/prismjs@1.27.0/components/prism-jsx.js?no-check"; import "https://esm.sh/prismjs@1.27.0/components/prism-typescript.js?no-check"; import "https://esm.sh/prismjs@1.27.0/components/prism-tsx.js?no-check"; +import "https://esm.sh/prismjs@1.27.0/components/prism-diff.js?no-check"; export { extract as frontMatter } from "$std/encoding/front_matter.ts";