Bendik Aagaard LynghaugandClaude Fable 5
b957b02410
README rewritten for the v8 branch: honest size claim (7.97 kB min+gzip for the whole framework, with the v7 '4kb' context), the zero-build story up front, bankai v10, package map, credits to yoshuawuyts, the choojs contributors and the pirxpilot fork line. docs/migrating-v7-to-v8.md: the codemod path, the specifier map, and every deliberate behavior change spelled out. docs/deploy.md: plain Node, Docker, proxy/CDN — including the HTTP/3 answer (h3 is infrastructure's job; bankai's contract is the 103 + Link headers that any hints-aware edge, h3 included, propagates; server push is dead everywhere and never existed in h3) — and web-standard runtimes. docs/rfc.md: the draft announcement for choojs/choo — continuation framing, pings to yoshuawuyts and pirxpilot, the npm-rights ask, API feedback questions, and a three-week comment window with a silence-is-consent close. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014NgfSjHE11oFpoSnLVKLXd
84 lines
2.7 KiB
Markdown
84 lines
2.7 KiB
Markdown
# Deploying a choo v8 + bankai v10 app
|
|
|
|
The server side of a v8 app is plain ESM — there is no server bundle.
|
|
Deploy is: ship the source + `dist/`, run a server.
|
|
|
|
## Plain Node (the blessed path)
|
|
|
|
```console
|
|
$ bankai build app.js --title "my app" --prerender /
|
|
$ bankai serve --h2 --port 443
|
|
```
|
|
|
|
`bankai serve` does static assets (immutable + precompressed), 103 Early
|
|
Hints, streaming SSR, and `window.initialState`. `--h2` matters:
|
|
browsers only act on Early Hints over HTTP/2 or HTTP/3. For a public
|
|
deployment use a real certificate (the built-in one is a generated
|
|
localhost cert) or front it with a TLS-terminating proxy.
|
|
|
|
## Docker
|
|
|
|
```dockerfile
|
|
FROM node:24-slim
|
|
WORKDIR /app
|
|
COPY package*.json ./
|
|
RUN npm ci --omit=dev
|
|
COPY . .
|
|
RUN npx bankai build app.js
|
|
EXPOSE 8080
|
|
CMD ["npx", "bankai", "serve"]
|
|
```
|
|
|
|
## Behind a proxy / CDN (and the HTTP/3 answer)
|
|
|
|
Node has no production HTTP/3 server yet (QUIC support in core is still
|
|
experimental and not exposed as an h3 listener), and that's fine: h3 is
|
|
infrastructure's job. Run `bankai serve` on h1 or h2 behind:
|
|
|
|
- **Caddy** — serves h2 + h3 by default, forwards to bankai:
|
|
```
|
|
example.com {
|
|
reverse_proxy localhost:8080
|
|
}
|
|
```
|
|
- **nginx ≥ 1.29** — `listen 443 quic;` for h3 plus
|
|
`early_hints on;`-era support for forwarding the 103.
|
|
- **Cloudflare / Fastly** — h3 at the edge automatically; both
|
|
understand and propagate Early Hints (Cloudflare has since 2021).
|
|
|
|
bankai's contract with these layers is just headers: it emits the 103
|
|
interim response and repeats the `Link` header on the final response, so
|
|
any hints-aware edge can act on them — including over h3/QUIC, where
|
|
Early Hints work exactly as on h2. What you should *not* expect is
|
|
HTTP/2-style server push: it's removed from Chrome and Firefox and was
|
|
never in HTTP/3. Hints + preload is the whole story now.
|
|
|
|
## Web-standard runtimes (Deno, Bun, edge)
|
|
|
|
`toStream()` returns a WHATWG `ReadableStream`, so the render half needs
|
|
no adapter at all:
|
|
|
|
```js
|
|
import createApp from './app.js'
|
|
import { documentHead, documentTail, resolveApp } from 'bankai'
|
|
|
|
export default {
|
|
async fetch (req) {
|
|
const app = createApp()
|
|
const state = {}
|
|
const url = new URL(req.url)
|
|
const body = app.toStream(url.pathname + url.search, state)
|
|
// stream the body through a TransformStream that wraps head + tail,
|
|
// or buffer if the route is small — your call, it's a web stream
|
|
return new Response(body, {
|
|
headers: { 'content-type': 'text/html; charset=utf-8' }
|
|
})
|
|
}
|
|
}
|
|
```
|
|
|
|
Serve `dist/` via the platform's static hosting and reuse
|
|
`dist/bankai.json` for the asset links. A first-class edge adapter
|
|
(head/tail wrapping + Early Hints via the platform APIs) is on the v8
|
|
roadmap; the primitives are deliberately already web-standard.
|