2026-09-08 19:41:22 +02:00
|
|
|
# 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
|
2026-09-08 19:55:20 +02:00
|
|
|
$ npx @uhhm/buuh-migrate . # rewrite in place
|
|
|
|
|
$ npx @uhhm/buuh-migrate --dry . # or report only
|
2026-09-08 19:41:22 +02:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
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.
|
2026-09-08 19:55:20 +02:00
|
|
|
2. Swap dependencies for `@uhhm/buuh`, `@uhhm/buuh-html`, and friends.
|
2026-09-08 19:41:22 +02:00
|
|
|
3. Run your app. Read the console: hydration now *tells you* when server
|
|
|
|
|
and client markup disagree.
|
|
|
|
|
|
|
|
|
|
## Specifier map
|
|
|
|
|
|
|
|
|
|
| v7 | v8 |
|
|
|
|
|
|---|---|
|
2026-09-08 19:55:20 +02:00
|
|
|
| `choo` | `@uhhm/buuh` |
|
|
|
|
|
| `choo/html`, `nanohtml` | `@uhhm/buuh-html` |
|
|
|
|
|
| `nanohtml/raw` | `@uhhm/buuh-html/raw` |
|
|
|
|
|
| `nanomorph` | `@uhhm/buuh-html/morph` |
|
|
|
|
|
| `nanocomponent`, `choo/component` | `@uhhm/buuh-component` |
|
|
|
|
|
| `choo-devtools` | `@uhhm/buuh-devtools` |
|
|
|
|
|
| `choo-lazy-route` | `lazy()` from `@uhhm/buuh` |
|
|
|
|
|
| `nanobus`, `nanorouter`, `nanohref`, `nanotiming` | built into `@uhhm/buuh` |
|
2026-09-08 19:41:22 +02:00
|
|
|
| `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.
|
