Bendik Aagaard LynghaugandClaude Fable 5
ce1ec9e4a9
Packages renamed to the @uhhm scope (@uhhm/buuh, @uhhm/buuh-html, @uhhm/buuh-component, @uhhm/buuh-devtools, @uhhm/buuh-migrate, @uhhm/bankai). Scoping is load-bearing twice over: npm routes registries per scope so @uhhm/* resolves against project.uhhm.no while everything else stays on npmjs, and it means this fork never squats upstream's names anywhere. The codemod now migrates choo v7 apps to the @uhhm names. README rewritten with the fork framing and full upstream credit; the choojs RFC moves to docs/upstream-rfc-draft.md, in the drawer for if this work ever goes home. API unchanged — choo() is still choo(). Also: Gitea Actions CI + release workflows (npm publish to the uhhm registry on tag push, CDN bundle uploaded as a generic package), npm run bundle producing dist-cdn/buuh.js (the whole framework as one minified ES module for import-map use), docs/publishing.md explaining what Gitea Packages is (a real npm registry) and is not (a CDN — serve the bundle from a static host with module-safe MIME instead), and onload.js constructing window.MutationObserver to match its own guard (surfaced by smoke-testing the bundle outside a full browser). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014NgfSjHE11oFpoSnLVKLXd
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 @uhhm/buuh-migrate . # rewrite in place
|
|
$ npx @uhhm/buuh-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 `@uhhm/buuh`, `@uhhm/buuh-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` | `@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` |
|
|
| `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.
|