@alxia/react-router 0.3.0 → 0.5.0

package/docs/guide.md

@@ -16,7 +16,7 @@ deploying.
 - [The app's own context keys](#the-apps-own-context-keys)
 - [A CSP nonce](#a-csp-nonce)
 - [Escape hatches](#escape-hatches)
-- [Hooks around the pages](#hooks-around-the-pages)
+- [Middlewares around the pages](#middlewares-around-the-pages)
 - [Routes beside the pages](#routes-beside-the-pages)
 - [WebSockets](#websockets)
 - [The client's files](#the-clients-files)
@@ -26,7 +26,35 @@ deploying.
 
 ## Setup
 
-Start from React Router's official template:
+### A new app: `bun create @alxia`
+
+```sh
+bun create @alxia my-app --template react-router
+cd my-app
+bun dev
+```
+
+[`@alxia/create`](https://www.npmjs.com/package/@alxia/create) copies React
+Router's official template with alxia's layer already applied: the steps
+of the next section, done.
+
+- `@alxia/core` and `@alxia/react-router` installed, and every dependency
+  moved to the newest release alxia accepts (see
+  [`@alxia/create`'s Versions](https://github.com/softistx/alxia/blob/develop/packages/create/docs/guide.md#versions));
+- `alxia()` in `vite.config.ts`, the `bunfig.toml`, and `start` running
+  `bun build/server/index.js`;
+- Biome, with `lint`, `format`, `check`, `check:ci` and `verify` scripts;
+- a `Dockerfile` that builds on `oven/bun:1` and runs `build/` alone on
+  `oven/bun:1-alpine`, as [Deploying](#deploying) describes.
+
+`bun run verify` checks, typechecks and builds it.
+[`@alxia/create`'s guide](https://github.com/softistx/alxia/blob/develop/packages/create/docs/guide.md#running-it)
+lists the command's options. The template keeps `@react-router/serve` in its
+dependencies, unused: remove it if you like.
+
+### An existing React Router app
+
+Start from React Router's official template, or your own app:
 
 ```sh
 bunx create-react-router@latest my-app
@@ -96,9 +124,10 @@ What the template keeps:
 - `@react-router/node`, which React Router's default `entry.server`
   renders with: it streams under Bun.
 - Vite 7 or 8 (the template ships 8).
-- Its `typescript` 5.9. This package's peer asks for 6 or 7, so `bun add`
-  warns, but the template's code typechecks with 5.9.
-  `bun add -d typescript@^6` silences the warning.
+- With `bunx create-react-router`, its `typescript` 5.9. This package's
+  peer asks for 6 or 7, so `bun add` warns, but the template's code
+  typechecks with 5.9. `bun add -d typescript@^6` silences the warning;
+  `bun create @alxia` writes 6 or 7 already.
 
 React Router 8 is required: its loaders receive a `RouterContextProvider`,
 and alxia's context is set on it.
@@ -154,6 +183,10 @@ server build inside it, into one file:
 - **The client folder is resolved against the built file**: `../client`,
   from React Router's `buildDirectory`, so it is found wherever the
   process starts.
+- **It is self-contained**: every package the server imports, React,
+  React Router and alxia included, is bundled into it
+  ([Self-contained](#self-contained)), so `build/` runs with no
+  `node_modules`.
 
 ```sh
 bun run build
@@ -184,7 +217,7 @@ The plugin loads `build/server/index.js` on the first request and hands
 every request to its default export, the alxia app, before Vite's own
 files. So the preview answers as `bun run start` does: the pages and their
 data, `/api`, `build/client` with the cache headers of
-[the client's files](#the-clients-files), and every hook of `beforeAll`
+[the client's files](#the-clients-files), and every middleware of `beforeAll`
 and `configure`. Requests, their bodies and every `Set-Cookie` pass
 through whole, and pages stream.
 
@@ -208,20 +241,22 @@ React Router prerenders the `prerender` paths of `react-router.config.ts`
 through the same preview server, during `react-router build`. A
 prerendered page is therefore rendered by the built server too: its loader
 reads `alxiaOf(context)` and `getLoadContext`'s keys, and `beforeAll`'s
-and `configure`'s hooks run around it.
+and `configure`'s middlewares run around it.
 
 ## Built for Bun
 
 `build/server/index.js` runs on Bun, and the plugin builds it for Bun,
 with nothing to configure. It adds to Vite's `ssr` environment, under
-`react-router dev` and `react-router build` alike:
+`react-router dev` and `react-router build` alike but for the last row,
+the build's alone:
 
 | option | what the plugin adds | why |
 | --- | --- | --- |
 | `resolve.conditions` | `bun` | a package bundled into the server whose `exports` has a `bun` condition is bundled as its Bun variant |
-| `resolve.externalConditions` | `bun` | a dependency left external is loaded as its Bun variant in dev too, as Bun loads it from the build |
+| `resolve.externalConditions` | `bun` | a dependency left external, as every one is in dev and one the app names in `ssr.external` is in the build, is loaded as its Bun variant, as Bun loads it |
 | `resolve.builtins` | `bun`, and `bun:*` (`bun:sqlite`, `bun:ffi`, …) | Bun's own modules stay imports of the build, whichever runtime runs Vite. Vite knows `bun:*`, and bare `bun` only when it runs on Bun |
 | `build.target` | `esnext` | the newest syntax is left as written: Bun runs it, and Vite's default targets browsers |
+| `resolve.noExternal` | `true`, under `react-router build` only | every package is bundled into `build/server/index.js`, so `build/` runs with no `node_modules` ([Self-contained](#self-contained)) |
 
 A package written for Bun, then, gives the build the variant Bun would
 load, and Bun's own modules are used as they are:
@@ -293,6 +328,60 @@ export default defineConfig({
 `ssr.resolve.conditions` at the top level is the same option, and is kept
 the same way.
 
+### Self-contained
+
+Under `react-router build`, the plugin sets `resolve.noExternal: true` on
+the `ssr` environment: Vite bundles every package the server imports into
+`build/server/index.js`, where it would otherwise leave each one under
+`node_modules` as an `import`. What the file still imports is Node's and
+Bun's own modules:
+
+```js
+// build/server/index.js, its imports
+import { createRequire } from "node:module";
+import { PassThrough } from "node:stream";
+// … and no "react", "react-router" or "@alxia/core"
+```
+
+So `build/` is all a server needs, beside Bun: a Docker image's last
+stage copies it alone ([Docker](#docker)). React and `react-dom/server`,
+React Router, alxia and its plugins bundle as they are, CommonJS included;
+the `bun` condition above picks each package's Bun variant. One copy of
+each package is in the file, so `alxiaContext` and the app's own keys are
+one object for the server and the routes. React Router's prerendering and
+`vite preview` load the same file.
+
+`react-router dev` is left as it was: Vite's SSR runner loads the
+packages from `node_modules`.
+
+What the app sets wins. Vite reads `external` before `noExternal`:
+
+- **`ssr.external: ['sharp']`**, or the same on
+  `environments.ssr.resolve.external`, keeps those packages external,
+  imported from `node_modules` at runtime. Use it for a package that
+  cannot be bundled: a native addon (a `.node` file), or one that reads
+  files of its own folder at runtime. The image must then hold that
+  package ([Docker](#docker)).
+- **`ssr.external: true`** keeps every package external, Vite's own
+  behaviour: the plugin adds no `noExternal` then, and the server needs
+  the production `node_modules` beside `build/`.
+- **`ssr.noExternal`**, a list, changes nothing: everything is bundled
+  already.
+
+```ts
+// vite.config.ts
+export default defineConfig({
+	// Bundled but for sharp, a native addon.
+	ssr: { external: ['sharp'] },
+	plugins: [reactRouter(), alxia()],
+});
+```
+
+A package the build could not bundle and was not told to leave external
+fails at runtime, from `build/` alone, with Bun's
+`Cannot find package '…'`: see
+[the troubleshooting entry](troubleshooting.md#error-cannot-find-package--from-appbuildserverindexjs).
+
 ## Customising the server
 
 Write `app/server.ts`, with `createServer()` as its default export, or let
@@ -308,7 +397,7 @@ bunx alxia-react-router reveal
 
 ```text
 alxia-react-router: wrote app/server.ts, the server alxia() runs by default.
-Next: uncomment configure in app/server.ts to add the app's hooks and /api; bun run dev picks it up.
+Next: uncomment configure in app/server.ts to add the app's middlewares and /api; bun run dev picks it up.
 ```
 
 The file is the server the plugin runs without one, `createServer()`, so
@@ -367,7 +456,7 @@ React Router's own rendering entries, `app/entry.server.tsx` and
 ### By hand
 
 The example uses `@alxia/logger` and `@alxia/compress`
-(`bun add @alxia/logger @alxia/compress`); any plugin works the same way.
+(`bun add @alxia/logger @alxia/compress`); any middleware works the same way.
 
 ```ts
 // app/server.ts
@@ -400,7 +489,7 @@ Every option is optional:
 
 | option | what it does |
 | --- | --- |
-| `configure(app)` | the app the pages run behind: its plugins, hooks and `/api`. It returns the app, and what it builds is what the loaders read |
+| `configure(app)` | the app the pages run behind: its middlewares and `/api`. It returns the app, and what it builds is what the loaders read |
 | `beforeAll(app)` | runs first, on a new app. What it declares applies to the client's files too: a rate limit, a guard on everything, a logger that should see every asset. It returns the app, which `configure` then receives |
 | `getLoadContext(ctx, context)` | sets the app's own keys on React Router's provider, `ctx` typed by `configure`'s app |
 | `build`, `mode`, `client` | override what the plugin wires; see [Escape hatches](#escape-hatches) |
@@ -414,11 +503,16 @@ A request goes through four layers, in order:
 3. what `configure` declared;
 4. the pages: `GET`, `POST`, `PUT`, `PATCH` and `DELETE` at `/*`.
 
-Hooks apply to the routes declared after them, so a session or a guard in
-`configure` runs around every page and its data, but not around the
-JavaScript of the login page. Global hooks (`onRequest`, `@alxia/cors`,
-`@alxia/compress`, `@alxia/secure-headers`) apply everywhere, wherever
-they are declared.
+A middleware given to `use` runs on every route declared after it, and on a
+request no route matches. So a session or a guard in `configure` runs around
+every page and its data, and not around what is declared before it: the
+client's files, which sit between `beforeAll` and `configure`. What must see
+every request, the client's files included, goes in `beforeAll`: the logger,
+`@alxia/cors`, `@alxia/compress`, `@alxia/secure-headers`. A guard on the app
+answers a request no route matches too: an anonymous request to a missing path
+gets the 401, not the 404. Scope it with a path, `use('/app', guard)`
+(a guard that adds nothing to the context: `bearer` and `session` add `user`),
+to guard only some pages.
 
 ```ts
 // app/server.ts: a guard on everything, the assets included
@@ -435,13 +529,13 @@ export default createServer({
 ```
 
 `configure` and `beforeAll` must return the app; one that returns nothing
-is a compile error. A plugin that needs something an earlier one
+is a compile error. A middleware that needs something an earlier one
 derived is typed by the app it is given, as anywhere in alxia.
 
 ## Typing the loaders
 
 Every request through the catch-all sets `alxiaContext`, this package's
-key, on React Router's context provider, to what alxia's hooks built for
+key, on React Router's context provider, to what alxia's middlewares built for
 that request. `alxiaOf(context)` reads it.
 
 ### With `Register`: no type argument
@@ -486,7 +580,7 @@ shows. The checks it gives:
 
 ```ts
 const ctx = alxiaOf(context);
-ctx.tenant;     // error: no hook derives `tenant`
+ctx.tenant;     // error: no middleware derives `tenant`
 ctx.user.name;  // error: `user` may be null
 ```
 
@@ -517,19 +611,57 @@ export function loader({ context }: Route.LoaderArgs) {
 
 The type argument may also be an alxia app, the app *before* the
 catch-all, for a server of your own. Anything else is a compile error.
-With neither `Register` nor a type argument, `alxiaOf(context)` is
-`BaseContext`: the request, its URL, `reply` and the rest of what every
-hook reads.
+
+### With `@alxia/core`'s `Register`
+
+`@alxia/core` has a `Register` of its own, which names the chain that
+builds an app's context, for its route files
+([The app's type](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/types.md#register-and-appcontext)).
+`alxiaOf(context)` reads it when this package's `Register` names no
+server:
+
+```ts
+// app/context.ts
+import { alxia } from '@alxia/core';
+
+export const base = alxia().derive(({ request }) => ({ user: request.headers.get('x-user') }));
+
+declare module '@alxia/core' {
+	interface Register {
+		context: typeof base;
+	}
+}
+
+// app/server.ts
+const server = createServer({ configure: (app) => app.plugin(base) });
+export default server;
+```
+
+`alxiaOf(context).user` is then typed with no declaration in
+`@alxia/react-router`. Which one is read, in order:
+
+1. a type argument, `alxiaOf<typeof server>(context)`;
+2. this package's `Register`, `server: typeof server`: the whole app the
+   pages run behind, `base` and everything `configure` adds after it;
+3. `@alxia/core`'s `Register`, `context: typeof base`: only what `base`
+   builds;
+4. neither: `BaseContext`, the request, its URL, `reply` and the rest of
+   what every middleware reads.
+
+Declare this package's `Register` when `configure` adds to the context
+after the base, and the loaders read it.
 
 ### Why a global augmentation is right here
 
-alxia's core refuses global augmentation of its context: a plugin that
-added `user` to every route, declared before it or after, would type
-`user` on routes that run before the plugin. That is the lie "order is
-meaning" forbids. `Register` here does something else: it names the
-**one** server of the React Router build, at the point of its catch-all,
-which is exactly what every loader runs behind. One build has one server
-entry, so there is no second app for a module to be confused with.
+alxia's core refuses a global augmentation of a context key: a plugin
+that added `user` to every route, declared before it or after, would
+type `user` on routes that run before the plugin. That is the lie "order
+is meaning" forbids. Core's own `Register` names the base that builds
+the context instead, and what reads it requires it. `Register` here does
+something else: it names the **one** server of the React Router build,
+at the point of its catch-all, which is exactly what every loader runs
+behind. One build has one server entry, so there is no second app for a
+module to be confused with.
 
 If two React Router apps share one TypeScript program (one tsconfig over
 both folders of a monorepo), their two declarations conflict, and `tsc`
@@ -579,7 +711,7 @@ export function loader({ context }: Route.LoaderArgs) {
 
 `getLoadContext` runs before React Router, on every request, with
 `alxiaContext` already set. Its `ctx` is typed by `configure`'s app:
-reading something no hook derives is a compile error. Keep the keys in a
+reading something no middleware derives is a compile error. Keep the keys in a
 module of their own, such as `app/context.ts`, rather than in
 `app/server.ts`: a route imports them, and the server file then stays out
 of the client's module graph.
@@ -669,7 +801,7 @@ scripts included.
 ### How it stays loose
 
 `nonceOf` reads `nonce` from alxia's context if it is a string, and
-returns `undefined` otherwise: no hook set one, or the request did not come
+returns `undefined` otherwise: no middleware set one, or the request did not come
 through alxia at all. `ServerRouter` and React then render no `nonce`
 attribute. So:
 
@@ -756,7 +888,7 @@ export const base = alxia()
 /** What the loaders read: alxiaOf<Base>(context). */
 export type Base = typeof base;
 
-const app = base.use((app) =>
+const app = base.plugin((app) =>
 	reactRouter(app, {
 		build: () =>
 			import(new URL('./build/server/index.js', import.meta.url).href) as Promise<ServerBuild>,
@@ -778,7 +910,7 @@ bun run build && bun server.ts
 | `getLoadContext(ctx, context)` | as `createServer`'s |
 | `client` | the client build's folder, a path or a `file:` URL, served before the catch-all in `production` |
 
-`reactRouter()` goes through `use`, as `@alxia/graphql`'s `graphql(app, …)`
+`reactRouter()` goes through `app.plugin`, as `@alxia/graphql`'s `graphql(app, …)`
 does: that is how it knows the app's context type. A `HEAD` is handed to
 React Router as a `GET`, since React Router answers a `HEAD` of its own
 with no headers at all; the core then drops the body. In a monorepo where
@@ -786,14 +918,15 @@ this package is linked rather than installed, add
 `ssr: { external: ['@alxia/react-router'] }` to `vite.config.ts`: see
 [the troubleshooting entry](troubleshooting.md#alxiaof-this-request-has-no-alxia-context-).
 
-## Hooks around the pages
+## Middlewares around the pages
 
-Every hook declared before the catch-all runs around each page, as around
-any route:
+Every middleware declared before the catch-all runs around each page, as around
+any route, and `use` observers go first so they wrap everything:
 
 - **`@alxia/logger`** writes one entry per request and sets
   `x-request-id`. It times a streamed page by its first byte, since
-  `onResponse` runs when the headers leave.
+  the response is settled when its headers leave. Every request is logged,
+  404s and errors included.
 - **`@alxia/compress`** compresses documents and data, and flushes a
   streamed page as React writes it: the shell and its `<Suspense>`
   fallback still arrive first, in zstd, Brotli or gzip. See [the troubleshooting entry](troubleshooting.md#a-streamed-page-arrives-in-one-piece).
@@ -805,7 +938,8 @@ any route:
   [A CSP nonce](#a-csp-nonce).
 - **A guard** — `@alxia/jwt`'s `bearer`, `@alxia/janus`' session — in
   `configure` guards every page and its data alike; in `beforeAll`, the
-  client's files too.
+  client's files too. On the app, a guard also answers a request no route
+  matches with its 401.
 
 ## Routes beside the pages
 
@@ -823,7 +957,7 @@ export default createServer({
 });
 ```
 
-Each answers with its own schemas, replies and typed client. The core ranks
+Each answers with its own middlewares and replies. The core ranks
 paths as `Bun.serve` does, through `listen`, `app.fetch` and
 `app.request` alike: segment by segment, a literal beats a parameter,
 which beats the catch-all's wildcard. Two consequences:
@@ -834,10 +968,10 @@ which beats the catch-all's wildcard. Two consequences:
   every one-segment path, `/about` included, before React Router sees it.
   Put alxia's routes under a prefix of their own, `/api`.
 
-The catch-all adds nothing to the app's route table: `RoutesOf` and the
-typed client never show `/*`. Pages and single-fetch data are not
-something a typed client calls; what it does call, your `/api`, is typed
-as always.
+Pages and single-fetch data are not something a generated client calls:
+leave the catch-all out of `matchesSpec`'s check with `isReactRouterRoute`
+([OpenAPI](#openapi)); what a client does call, your `/api`, is what the
+OpenAPI document declares.
 
 What React Router answers comes back as it sent it: documents,
 single-fetch data (`/_.data`, `/login.data`), lazy route discovery
@@ -883,10 +1017,10 @@ export default createServer({
 });
 ```
 
-The upgrade runs the hooks declared before the route, and the route's
-validation, as any request does. A hook's reply refuses it: the client
+The upgrade runs the middlewares declared before the route, and the route's
+validation, as any request does. A middleware's reply refuses it: the client
 gets the 401 and its body, and no socket opens. `socket.data` holds the
-validated request and what each hook derived, typed. See
+validated request and what each middleware derived, typed. See
 [`@alxia/core`'s WebSockets](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/websockets.md)
 for the schemas and the rest of the socket.
 
@@ -906,7 +1040,7 @@ byte for byte, to a `Bun.serve` of the app on a loopback port of its
 own, started on the first upgrade and given
 `app.fetch` and `app.websocket`, as `listen` gives them. So in dev:
 
-- **The same hooks, refusals and handlers run** as from the build:
+- **The same middlewares, refusals and handlers run** as from the build:
   `open`, `message`, `close`, `drain`, the `message` and `send` schemas,
   `subscribe` and `publish`.
 - **An edit to `app/server.ts`, or to a module it imports, is used from
@@ -956,25 +1090,49 @@ refused when the server starts: see
 
 ## OpenAPI
 
-`@alxia/openapi` documents every route of `app.routes`, and the catch-all
-and the client's files are routes. Leave them out with
+alxia is OpenAPI spec first: the document is written by hand, the API's
+routes are bound to the operations generated from it, and
+[`@alxia/openapi`](https://www.npmjs.com/package/@alxia/openapi)'s
+`matchesSpec` checks, in a test, that `app.routes` and the operations
+match both ways. The catch-all and the client's files are routes of
+`app.routes`, and no operation of the document. Leave them out with
 `isReactRouterRoute`, which is true for each route this package declared:
 
 ```ts
 // app/server.ts
-import { docs } from '@alxia/openapi';
-import { createServer, isReactRouterRoute } from '@alxia/react-router';
+import { createServer } from '@alxia/react-router';
+import { operations } from './generated/alxia';
 
 export default createServer({
 	configure: (app) =>
 		app
 			.get('/api/health', ({ reply }) => reply.ok({ ok: true }))
-			.use(docs(app, { info: { title: 'Shop', version: '1.0.0' }, exclude: isReactRouterRoute })),
+			.route(operations.listOrders, ({ reply }) => reply.ok([])),
 });
 ```
 
-Combine it with your own: `exclude: (route) => isReactRouterRoute(route) ||
-route.path === '/api/health'`.
+```ts
+// app/server.test.ts
+import { test } from 'bun:test';
+import { matchesSpec } from '@alxia/openapi';
+import { isReactRouterRoute } from '@alxia/react-router';
+import type { ServerBuild } from 'react-router';
+import { operations } from './generated/alxia';
+import server from './server';
+
+test('the API routes every operation of openapi.yaml, and nothing else', async () => {
+	const build: ServerBuild = await import(new URL('../build/server/index.js', import.meta.url).href);
+	const app = server.create({ build });
+	matchesSpec(app, operations, {
+		exclude: (route) => isReactRouterRoute(route) || route.path === '/api/health',
+	});
+});
+```
+
+When the app puts the operations under a prefix the document's paths
+leave out, `app.group('/api', (api) => api.route(…))`, give `matchesSpec`
+the same `prefix: '/api'`. See
+[`@alxia/openapi`'s checks](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/guide/checks.md).
 
 ## Testing
 
@@ -1013,28 +1171,26 @@ is `POST /?index`, not `POST /`.
 
 ## Deploying
 
-Run `bun run build`, then `bun build/server/index.js` beside the project's
-production `node_modules`: the build imports `react`, `react-router` and
-alxia from them, as any React Router server build does.
+Run `bun run build`, then `bun build/server/index.js`. The build is
+[self-contained](#self-contained): `build/` is all the server needs, with
+no `node_modules`, unless the app keeps a package external with
+`ssr.external`.
 
 ### Docker
 
 The `react-router` template of
 [`@alxia/create`](https://github.com/softistx/alxia/tree/develop/packages/create)
 and the [example](https://github.com/softistx/alxia/tree/develop/examples/react-router)
-ship this `Dockerfile`, on Bun's official image. For an app started from
+ship this `Dockerfile`, on Bun's official images: built on `oven/bun:1`,
+Debian's, and run on `oven/bun:1-alpine`, about 130 MB. For an app started from
 `create-react-router`, it replaces the template's, which builds and runs
 on Node:
 
 ```dockerfile
-# Bun builds the app and runs it: build/server/index.js is alxia's server,
-# which runs on Bun. Pinned to Bun 1, the major alxia supports.
-
-# The production dependencies alone, for the final image.
-FROM oven/bun:1 AS production-dependencies
-WORKDIR /app
-COPY package.json bun.lock* bunfig.toml* ./
-RUN bun install --frozen-lockfile --production
+# Bun builds the app, and the image holds build/ alone: alxia's plugin
+# bundles every dependency into build/server/index.js, alxia's server, which
+# runs on Bun with no node_modules. Pinned to Bun 1, the major alxia
+# supports.
 
 # Every dependency, then react-router build: build/client and
 # build/server/index.js.
@@ -1045,17 +1201,20 @@ RUN bun install --frozen-lockfile
 COPY . .
 RUN bun run build
 
-# The build and the production dependencies, run as Bun's own non-root
-# user. The server listens on PORT (3000) and HOST (0.0.0.0).
-FROM oven/bun:1
+# The build, run as Bun's own non-root user with the start script's
+# command, and --no-install: with no node_modules, Bun would otherwise
+# fetch a package the build left out from the registry at startup,
+# where this fails.
+# The server listens on PORT (3000) and HOST (0.0.0.0). On Alpine, about
+# 200 MB lighter: build/ is JavaScript, which runs the same on musl. A
+# native addon built for glibc alone needs oven/bun:1 here.
+FROM oven/bun:1-alpine
 WORKDIR /app
 ENV NODE_ENV=production
-COPY package.json ./
-COPY --from=production-dependencies /app/node_modules ./node_modules
 COPY --from=build /app/build ./build
 USER bun
 EXPOSE 3000
-CMD ["bun", "build/server/index.js"]
+CMD ["bun", "--no-install", "build/server/index.js"]
 ```
 
 ```sh
@@ -1067,15 +1226,41 @@ Keep the template's `.dockerignore` beside it: `node_modules`, `build` and
 `.react-router` stay out of the context, so the image installs and builds
 its own. The `bunfig.toml` goes in, and `bun run build` runs React
 Router's CLI on Bun, as it does outside Docker. The image's command is
-`start`'s, run directly, so the platform's `SIGTERM` reaches the server.
+`start`'s, run directly, so the platform's `SIGTERM` reaches the server,
+with `--no-install`: a package missing from `build/` then fails at
+startup, where Bun would otherwise fetch it from npm.
 
 - **Commit `bun.lock`.** The installs are `--frozen-lockfile`: the image
   gets the versions you tested, and a `package.json` changed without a
   `bun install` fails the build
   ([troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/troubleshooting.md#error-lockfile-had-changes-but-lockfile-is-frozen)).
+- **The final stage is Alpine's**, musl where the build stage has glibc.
+  `build/` is JavaScript, which runs the same on both. A native addon
+  kept external and built for glibc alone does not load there: put the
+  final stage back on `oven/bun:1`
+  ([`@alxia/create`'s troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/create/docs/troubleshooting.md#error--is-linked-against-glibc-dt_needed-libmso6-but-this-bun-build-uses-musl)).
 - **The server runs as `bun`**, a user with no write access to `/app`.
   Write files to a volume the user owns
   ([troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/troubleshooting.md#eacces-permission-denied-open-app)).
+- **The image holds `build/` alone**, no `node_modules`: the build is
+  [self-contained](#self-contained). An app that keeps a package external
+  with `ssr.external` copies the production dependencies too, from a
+  stage of their own:
+
+  ```dockerfile
+  # Before the build stage: the production dependencies alone.
+  FROM oven/bun:1 AS production-dependencies
+  WORKDIR /app
+  COPY package.json bun.lock* bunfig.toml* ./
+  RUN bun install --frozen-lockfile --production
+
+  # In the final stage, beside build/.
+  COPY --from=production-dependencies /app/node_modules ./node_modules
+  ```
+
+  Without it, the container stops at startup with
+  `Cannot find package '…'`
+  ([troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/troubleshooting.md#error-cannot-find-package--from-appbuildserverindexjs)).
 
 `PORT` and `HOST` set where the server listens. The platform's `SIGTERM`
 stops it once the requests in flight are answered, and runs the app's

package/docs/roadmap.md

@@ -7,7 +7,15 @@ number on it. Every release, with each change it made, is in
 
 ## Now
 
-Nothing scheduled yet.
+- **Middlewares around the pages.** `beforeAll` and `configure` take
+  `use(logger())`, `use(secureHeaders())` and the other middlewares of
+  alxia 0.4, which run on the pages, the client's files declared after
+  them, and every request no route matches; the hooks they replace still
+  work, deprecated.
+- **Loaders typed by core's `Register`.** `alxiaOf(context)` reads the base
+  `@alxia/core`'s `Register` names when this package's names no server, so
+  an app that registers its context once types its loaders too. This
+  package's `Register` still wins when both are declared.
 
 ## Next
 
@@ -29,9 +37,9 @@ Nothing scheduled yet.
   only behind `future.v8_middleware`, and the line is in maintenance.
 - **Node or Cloudflare.** alxia is a Bun framework; React Router's own
   adapters serve those runtimes.
-- **The pages in the route table.** Documents and single-fetch data are not
-  something the typed client calls, so the catch-all stays out of
-  `RoutesOf`.
+- **The pages in the OpenAPI document.** Documents and single-fetch data
+  are not something a generated client calls, so `isReactRouterRoute`
+  leaves the catch-all out of `matchesSpec`'s check.
 - **A runtime dependency.** The package declares none: `@alxia/core` and
   `react-router` are peers.
 - **A `react-router-serve` of its own.** `bun build/server/index.js` is the
@@ -45,7 +53,15 @@ Nothing scheduled yet.
 
 ## Shipped
 
-### Next release
+### 0.4.0
+
+- **A self-contained build.** `react-router build` bundles every package
+  into `build/server/index.js`, React, React Router and alxia included,
+  so `build/` runs with no `node_modules` and a Docker image copies it
+  alone. Never in dev; `ssr.external` keeps a package external, and
+  `ssr.external: true` every package.
+
+### 0.3.0
 
 - **The server is built for Bun.** `alxia()` adds the `bun` export
   condition to the `ssr` environment's conditions and external
@@ -53,9 +69,12 @@ Nothing scheduled yet.
   Vite, and targets `esnext`, in dev and in the build, with nothing to
   configure. A package's `bun` variant is the one bundled, and what the
   app sets is kept.
-- **A Docker image on Bun.** The guide's Deploying has the multi-stage
-  `Dockerfile` on `oven/bun:1` that `@alxia/create`'s template and the
-  example ship, running `bun build/server/index.js` as a non-root user.
+- **A Docker image on Bun.** The guide's Deploying has a multi-stage
+  `Dockerfile` on `oven/bun:1`, running `bun build/server/index.js` as a
+  non-root user.
+
+### 0.2.0
+
 - **A per-request CSP nonce.** `nonceOf(loadContext)` reads the nonce that
   `@alxia/secure-headers`' `nonce: true`, or a `derive` of the app's own,
   put on the context, so `entry.server.tsx` hands it to `<ServerRouter
@@ -79,7 +98,8 @@ Nothing scheduled yet.
 - **`HEAD` with headers.** A `HEAD` is answered as its `GET`, less the
   body.
 - **OpenAPI.** `isReactRouterRoute` leaves the catch-all and the client's
-  files out of `@alxia/openapi`'s document.
+  files out of a check of `app.routes` against the document, such as
+  `@alxia/openapi`'s `matchesSpec`.
 - **Zero config, with Vite.** `@alxia/react-router/vite`'s `alxia()`,
   anywhere in `plugins`, is all an app from the official template needs.
   Without `app/server.ts` a default server serves the pages; with it,