66 lines
2.9 KiB
Markdown
66 lines
2.9 KiB
Markdown
|
# Migrating a choo v7 app to v8
|
||
|
|
|
||
|
|
The API you know is intact: `choo()`, `app.use`, `app.route`,
|
||
|
|
`app.mount`, `app.toString`, `emit`, stores, `state.events`. What changed
|
||
|
|
is the plumbing: ESM everywhere, new package names, no compile step, and
|
||
|
|
a platform baseline of Node ≥ 24 + Baseline Widely Available browsers.
|
||
|
|
|
||
|
|
## The fast path
|
||
|
|
|
||
|
|
```console
|
||
|
|
$ npx @choojs/migrate . # rewrite in place
|
||
|
|
$ npx @choojs/migrate --dry . # or report only
|
||
|
|
```
|
||
|
|
|
||
|
|
The codemod converts simple top-level CJS to ESM, remaps specifiers, and
|
||
|
|
prints a note for everything it won't guess at. Then:
|
||
|
|
|
||
|
|
1. Add `"type": "module"` to package.json.
|
||
|
|
2. Swap dependencies for `@choojs/core`, `@choojs/html`, and friends.
|
||
|
|
3. Run your app. Read the console: hydration now *tells you* when server
|
||
|
|
and client markup disagree.
|
||
|
|
|
||
|
|
## Specifier map
|
||
|
|
|
||
|
|
| v7 | v8 |
|
||
|
|
|---|---|
|
||
|
|
| `choo` | `@choojs/core` |
|
||
|
|
| `choo/html`, `nanohtml` | `@choojs/html` |
|
||
|
|
| `nanohtml/raw` | `@choojs/html/raw` |
|
||
|
|
| `nanomorph` | `@choojs/html/morph` |
|
||
|
|
| `nanocomponent`, `choo/component` | `@choojs/component` |
|
||
|
|
| `choo-devtools` | `@choojs/devtools` |
|
||
|
|
| `choo-lazy-route` | `lazy()` from `@choojs/core` |
|
||
|
|
| `nanobus`, `nanorouter`, `nanohref`, `nanotiming` | built into `@choojs/core` |
|
||
|
|
| `nanoquery` | built in (`state.query`); use `URLSearchParams` elsewhere |
|
||
|
|
| `nanoraf`, `nanoassert`, `nanolru` | retired — platform/built-in |
|
||
|
|
|
||
|
|
## Behavior changes to know about
|
||
|
|
|
||
|
|
- **URLs decode once, and never crash.** A literal `%` in a path routed
|
||
|
|
v7 into a `URIError`; v8 keeps the raw segment. Params are no longer
|
||
|
|
double-decoded (`%2540` → `%40`, not `@`). Routes and locations are
|
||
|
|
NFC-normalized, so `café` matches however the é was composed.
|
||
|
|
`state.href` is decoded for reading.
|
||
|
|
- **Event handlers never serialize.** v7's server renderer emitted
|
||
|
|
`onclick=""`; v8 emits nothing — handlers are behavior, not markup.
|
||
|
|
- **Whitespace is preserved as authored** in browser renders (v7's
|
||
|
|
browser transform collapsed it). Server and browser output are now
|
||
|
|
byte-identical, which is what makes hydration adoption work.
|
||
|
|
- **`mount()` hydrates.** First render adopts server DOM in place and
|
||
|
|
warns on real mismatches; `<script>` tags and whitespace are ignored.
|
||
|
|
- **`toString()` got stricter, `toStream()` got capable.** Sync renders
|
||
|
|
behave exactly as v7. Async content — `state.prefetch` promises, lazy
|
||
|
|
routes, promise-valued template holes — requires `toStream()`, and
|
||
|
|
`toString()` says so instead of misrendering.
|
||
|
|
- **Views can't return arrays** (unchanged from v7) and document-level
|
||
|
|
roots (`html\`<body>…\``) work in the browser renderer too.
|
||
|
|
|
||
|
|
## Things that moved to bankai
|
||
|
|
|
||
|
|
sheetify → put a `style.css` next to your entry (client-only by
|
||
|
|
construction). `split-require` → native `import()` + `lazy()`.
|
||
|
|
`bankai start/build/serve/inspect` replace the v9 pipeline; HTTP/2 push
|
||
|
|
never shipped and is dead in browsers — bankai v10 sends 103 Early Hints
|
||
|
|
instead.
|