Setting the file. One moment.
Subchapter 2.1
references/FRESH_MIGRATION.mdMarkdown3 KBView on GitHub
Read deno.json imports before changing anything. Three situations look similar
and need different handling:
deno.json says | Situation |
|---|---|
jsr:@fresh/core@^2 | Stable 2.x — see FRESH.md |
jsr:@fresh/core@2.0.0-alpha.* | Alpha 2.x — not 1.x, see below |
$fresh/ import paths | Fresh 1.x — migrate |
Grep for $fresh/ to find 1.x imports; every one of them becomes fresh or
fresh/runtime.
Run the migration tool:
deno run -Ar jsr:@fresh/updateIt converts import paths to the fresh package, updates handler signatures to
the single (ctx) parameter, removes the generated manifest and legacy config
and dev entry points, creates vite.config.ts and client.ts, switches
deno.json tasks to Vite, merges the separate error pages into a unified
_error.tsx, and updates deprecated context methods.
If it misses anything, check by hand:
fresh or fresh/runtime.(ctx) parameter, request via ctx.req.vite, vite build, deno serve -A _fresh/server.js._error.tsx replaces the separate _404.tsx and
_500.tsx.@tailwindcss/vite, not the old Fresh Tailwind plugin.| 1.x | 2.x |
|---|---|
renderNotFound() | throw new HttpError(404) |
bare render() with no JSX | ctx.render(<MyComponent />) |
basePath | ctx.config.basePath |
data passed through ctx.render() | handler returns { data: {...} } |
The last one is the most common error. ctx.render() takes JSX, never a data
object — a handler passes data by returning { data: {...} }, and the page
picks it up with define.page<typeof handler>. See FRESH.md.
Alpha projects are 2.x, but predate the Vite setup. A dev.ts in an alpha
project is correct, not a 1.x leftover — do not “fix” it.
| Alpha | Stable 2.x |
|---|---|
dev.ts entry point | vite.config.ts |
deno run -A --watch dev.ts | vite |
deno run -A dev.ts build | vite build |
@fresh/plugin-tailwind | @tailwindcss/vite |
| dev server on port 8000 | port 5173 |
no client.ts | client.ts required |
The handler pattern is already the same as stable:
define.handlers({ GET(ctx) { ... } }) returning { data: {...} }.