@alxia/react-router 0.8.1 → 0.10.0

package/docs/guide/beside-the-pages.md

@@ -0,0 +1,178 @@
+# Beside the pages
+
+This page covers what runs around and beside the pages: the middlewares
+before the catch-all, routes of the app's own, WebSockets in dev, in preview
+and in the build, and the client's files.
+
+## Middlewares around the pages
+
+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
+  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).
+- **`@alxia/secure-headers`**' default policy, `default-src 'none'`, blocks
+  every script of the page, React Router's inline ones included, and its
+  `form-action 'none'` blocks a `<Form>`'s post. Give the pages a policy of
+  their own: see [the troubleshooting entry](../troubleshooting.md#refused-to-execute-inline-script-because-it-violates-the-following-content-security-policy-directive-default-src-none).
+  With `nonce: true`, the scripts need no `'unsafe-inline'`:
+  [A CSP nonce](csp-nonce.md#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. On the app, a guard also answers a request no route
+  matches with its 401.
+
+## Routes beside the pages
+
+alxia's own routes answer their paths wherever they are declared:
+
+```ts
+// app/server.ts
+import { createServer } from '@alxia/react-router';
+
+export default createServer({
+	configure: (app) =>
+		app
+			.get('/api/health', ({ reply }) => reply.ok({ ok: true }))
+			.get('/api/orders/:id', ({ params, reply }) => reply.ok({ id: params.id })),
+});
+```
+
+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:
+
+- **The path is chosen before the method.** With only `POST /api/orders`,
+  a `GET /api/orders` is alxia's 405, not a page.
+- **A route whose path covers pages takes them.** `GET /:slug` answers
+  every one-segment path, `/about` included, before React Router sees it.
+  Put alxia's routes under a prefix of their own, `/api`.
+
+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.md#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
+(`/__manifest`), redirects with every `Set-Cookie` they carry, and the
+error pages, a 404 or a 500 rendered by the app's `ErrorBoundary`.
+
+## WebSockets
+
+A `ws` route declared in `configure` (or `beforeAll`) is a socket under
+`react-router dev`, under `vite preview` and from
+`bun build/server/index.js` alike. There is
+nothing to add: no option, no package, no second server to start.
+
+```ts
+// app/server.ts
+import { createServer } from '@alxia/react-router';
+
+export default createServer({
+	configure: (app) =>
+		app
+			.derive(({ request }) => {
+				const name = request.headers.get('x-user');
+				return { user: name === null ? null : { name } };
+			})
+			.ws('/api/echo', {}, {
+				open: (socket) => socket.send({ hello: socket.data.user?.name ?? 'anonymous' }),
+				message: (socket, message) => socket.send({ echo: String(message) }),
+			})
+			.group((guarded) =>
+				guarded
+					.derive(({ user, reply }) =>
+						user === null ? reply(401, { error: 'unauthenticated' as const }) : { user },
+					)
+					.ws('/api/rooms/:room', {}, {
+						open: (socket) => socket.subscribe(socket.data.params.room),
+						message: (socket, message) =>
+							socket.publish(socket.data.params.room, {
+								from: socket.data.user.name,
+								text: String(message),
+							}),
+					}),
+			),
+});
+```
+
+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 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.
+
+The guard sits in a `group` so it refuses the sockets alone: declared on
+`app` itself, it would apply to every route after it, the pages'
+catch-all included.
+
+### Under `react-router dev`
+
+Vite's dev server is a `node:http` server, and an alxia socket is
+`Bun.serve`'s upgrade. The plugin listens for Vite's `upgrade` event and
+leaves Vite's own socket alone: an upgrade asking for the `vite-hmr` or
+`vite-ping` subprotocol is Vite's, and HMR works as before. Any other
+upgrade, except one Vite's `server.proxy` relays itself (an entry with
+`ws: true` or a `ws:` target, matched as Vite matches it), is relayed,
+byte for byte, to a `Bun.serve` of the app on a loopback port of its
+own, started on the first upgrade or the first request and given
+`app.fetch` and `app.websocket`, as `listen` gives them. So in dev:
+
+- **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
+  the next connection.** The edit makes a new app, and the next upgrade
+  starts a new `Bun.serve` for it. A socket opened before the edit keeps
+  the handlers it opened with until it closes.
+- **A `publish` reaches the sockets opened since the same edit**: the
+  sockets opened before it are on the previous server. Reload the pages
+  after an edit to reconnect them.
+- **A loader's or an action's `alxiaOf(context).server` is that loopback
+  server**, the one the sockets are on, so its `publish` reaches them as
+  from the build: see [The server](typing-the-loaders.md#the-server-server).
+- **A socket's `ctx.ip` is the loopback address**, the relay's. The
+  browser is local in dev, so that is usually its address anyway.
+- **An upgrade to a path with no `ws` route** gets what the build answers
+  it too, never a socket: alxia's 404 where nothing matches, the page
+  where the catch-all does.
+- **Another plugin that listens for upgrades** competes with the relay
+  on the paths it shares with it: give its socket a path under a
+  `server.proxy` entry with `ws: true` or a `ws:` target, or outside the
+  app's.
+- **With Vite in middleware mode**, there is no `node:http` server of
+  Vite's to listen on: serve the app yourself, as in
+  [A server of your own](customising-the-server.md#a-server-of-your-own-without-the-plugin).
+
+Under `vite preview` the same relay runs, to a `Bun.serve` of the built
+app, loaded once. Under `bun build/server/index.js`, nothing of this runs:
+`listen` serves the sockets itself, as any alxia app's.
+
+## The client's files
+
+In a build, each top-level entry of `build/client` becomes a route, after
+`beforeAll` and before `configure`:
+
+| entry | route | `Cache-Control` |
+| --- | --- | --- |
+| `assets/`, the hashed bundles | `static('/assets', …)` | `public, max-age=31536000, immutable` |
+| another folder, such as `images/` from `public/images/` | `static('/images', …)` | `public, max-age=3600` |
+| a file, such as `robots.txt` or `favicon.ico` | `file('/robots.txt', …)` | `public, max-age=3600` |
+
+They are the core's `static` and `file` routes, so ETags,
+`Last-Modified`, 304s and ranges are included. A missing file under one
+of those folders gets alxia's JSON 404, `{ "error": "not_found" }`, not a
+page, so a folder of `public/` shadows any page path under the same name.
+Dotfiles are skipped. In dev, Vite serves them.
+
+A folder that is not one, or a file whose name no route can carry, is
+refused when the server starts: see
+[the troubleshooting entries](../troubleshooting.md#typeerror-reactrouter-client-is--which-is-not-a-directory-).

package/docs/guide/csp-nonce.md

@@ -0,0 +1,100 @@
+# A CSP nonce
+
+This page covers a Content-Security-Policy without `'unsafe-inline'`: the
+policy in `app/server.ts`, the nonce passed on in `app/entry.server.tsx`, and
+why the nonce can stay loose.
+
+React Router renders inline scripts: the hydration data, the module
+loader, the scroll restoration, and with streaming one more per resolved
+`<Await>`. A policy without `'unsafe-inline'` allows them only when each
+carries the nonce the policy names. React Router writes it on every one of
+them, and on its `modulepreload` links, when `entry.server.tsx` passes it
+to `<ServerRouter nonce>` and to React's renderer
+([React Router's security guide](https://reactrouter.com/how-to/security)).
+
+`@alxia/secure-headers` makes the nonce: `secureHeaders({ nonce: true })`
+draws a fresh one per request, adds it to the policy's `script-src`, and
+puts it on the context of the routes after it, the catch-all included.
+`nonceOf(loadContext)` reads it in the entry.
+
+## 1. The policy, in `app/server.ts`
+
+```ts
+import { createServer } from '@alxia/react-router';
+import { secureHeaders } from '@alxia/secure-headers';
+
+export default createServer({
+	configure: (app) =>
+		app.use(
+			secureHeaders({
+				nonce: true,
+				contentSecurityPolicy: [
+					"default-src 'self'",
+					"script-src 'self'",
+					"style-src 'self' 'unsafe-inline'",
+					"img-src 'self' data:",
+					"connect-src 'self'",
+					"form-action 'self'",
+					"base-uri 'self'",
+					"frame-ancestors 'none'",
+				].join('; '),
+			}),
+		),
+});
+```
+
+`script-src 'self'` goes out as `script-src 'self' 'nonce-…'`, a new
+value on every response. `'self'` still allows the bundles under
+`/assets`, and `connect-src 'self'` the single-fetch data requests.
+
+## 2. The nonce, in `app/entry.server.tsx`
+
+React Router's template has no entry; reveal the default one, then add an
+import and the nonce in two places:
+
+```sh
+bunx react-router reveal entry.server
+```
+
+```diff
+ // app/entry.server.tsx, as reveal writes it
+ import { PassThrough } from "node:stream";
+
++import { nonceOf } from "@alxia/react-router";
+ import type { EntryContext, RouterContextProvider } from "react-router";
+ …
+     const { pipe, abort } = renderToPipeableStream(
+-      <ServerRouter context={routerContext} url={request.url} />,
++      <ServerRouter context={routerContext} url={request.url} nonce={nonceOf(loadContext)} />,
+       {
++        nonce: nonceOf(loadContext),
+         [readyOption]() {
+```
+
+`loadContext` is the entry's fifth parameter, the `RouterContextProvider`
+alxia hands React Router; the revealed file already declares it. With
+`renderToReadableStream`, the web entry, the option is the same: `{ nonce:
+nonceOf(loadContext), … }`.
+
+That is all: under `react-router dev` and from the build, every `<script>`
+of a page carries the nonce of its own response's policy, Vite's dev
+scripts included.
+
+## How it stays loose
+
+`nonceOf` reads `nonce` from alxia's context if it is a string, and
+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:
+
+- this package does not depend on `@alxia/secure-headers`, nor the reverse;
+- the same `entry.server.tsx` serves an app with or without the policy;
+- a nonce of your own works too, from any `derive` in `configure` that
+  returns `{ nonce: string }`; the policy is then yours to write with it.
+
+```ts
+configure: (app) => app.derive(() => ({ nonce: myNonce() })),
+```
+
+Under `exactOptionalPropertyTypes`, spread it in only when there is one:
+see [the troubleshooting entry](../troubleshooting.md#type---nonce-string--undefined--is-not-assignable-to-type-serverrouterprops-with-exactoptionalpropertytypes-true).

package/docs/guide/customising-the-server.md

@@ -0,0 +1,292 @@
+# Customising the server
+
+This page covers changing the default server with `createServer()`, and the
+escape hatches for leaving it: another entry, overriding the wiring, or a
+server of your own.
+
+Write `app/server.ts`, with `createServer()` as its default export, or let
+the package's bin write it for you.
+
+## Revealing the default server
+
+From the app's root, once `@alxia/react-router` is installed:
+
+```sh
+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 middlewares and /api; bun run dev picks it up.
+```
+
+The file is the server the plugin runs without one, `createServer()`, so
+the app answers as before. It holds `beforeAll`, `configure` and
+`getLoadContext`, commented, each of which compiles once uncommented
+(`getLoadContext`'s key is yours to make, below), and the `Register`
+declaration that types the loaders:
+
+```ts
+// app/server.ts, as reveal writes it, less its comments
+import { createServer } from '@alxia/react-router';
+// import { userAgentContext } from './context';
+
+const server = createServer({
+	// beforeAll: (app) => app,
+	// configure: (app) => app.get('/api/health', ({ reply }) => reply.ok({ ok: true })),
+	// getLoadContext: (ctx, context) => {
+	// 	context.set(userAgentContext, ctx.request.headers.get('user-agent'));
+	// },
+});
+
+export default server;
+
+declare module '@alxia/react-router' {
+	interface Register {
+		server: typeof server;
+	}
+}
+```
+
+`getLoadContext`'s example sets a key of the app's own, imported from
+`app/context.ts`. Make it there before uncommenting both lines:
+
+```ts
+// app/context.ts
+import { createContext } from 'react-router';
+
+export const userAgentContext = createContext<string | null>(null);
+```
+
+- **Where it writes**: the `entry` that `alxia({ entry: '…' })` names in
+  `vite.config.ts`, or `server.ts` in React Router's `appDirectory`
+  (`app/` unless `react-router.config.ts` names another). It reads both as
+  string literals, past comments. A computed one is refused, since
+  reveal would write a file the plugin does not load: give it as a
+  literal.
+- **It never overwrites**: a file already there is left as it is, and the
+  command exits 1. `bunx alxia-react-router reveal --force` overwrites it.
+- **Bun only**: the bin starts with `#!/usr/bin/env bun`, so no Node is
+  needed.
+
+React Router's own rendering entries, `app/entry.server.tsx` and
+`app/entry.client.tsx`, are revealed by React Router:
+`bunx react-router reveal`.
+
+## By hand
+
+The example uses `@alxia/logger` and `@alxia/compress`
+(`bun add @alxia/logger @alxia/compress`); any middleware works the same way.
+
+```ts
+// app/server.ts
+import { compress } from '@alxia/compress';
+import { logger } from '@alxia/logger';
+import { createServer } from '@alxia/react-router';
+
+const server = createServer({
+	configure: (app) =>
+		app
+			.use(logger())
+			.use(compress())
+			.get('/api/health', ({ reply }) => reply.ok({ ok: true }))
+			.derive(({ request }) => {
+				const name = request.headers.get('x-user');
+				return { user: name === null ? null : { name } };
+			}),
+});
+
+export default server;
+
+declare module '@alxia/react-router' {
+	interface Register {
+		server: typeof server;
+	}
+}
+```
+
+Every option is optional:
+
+| option | what it does |
+| --- | --- |
+| `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) |
+| `listen` | `listen`'s options for `bun build/server/index.js`: `port`, `hostname`, `idleTimeout`, `maxRequestBodySize`, `tls`, `onListen`. A `port` or `hostname` given here wins over `PORT` and `HOST`; an `onListen` here, told `@alxia/core`'s `ListenInfo` — `url`, `routes`, `table`, `dev` — wins over the option below |
+| `onListen(server)` | called once the built server listens and its `SIGINT` and `SIGTERM` handlers are in place, in place of the `alxia listening on …` line (and, in dev, of the route table); a signal sent from then on runs the `onStop` hooks |
+
+A request goes through four layers, in order:
+
+1. what `beforeAll` declared;
+2. the client's files, `build/client`, in a build;
+3. what `configure` declared;
+4. the pages: `GET`, `POST`, `PUT`, `PATCH` and `DELETE` at `/*`.
+
+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
+import { createServer } from '@alxia/react-router';
+
+export default createServer({
+	beforeAll: (app) =>
+		app.derive(({ request, reply }) =>
+			request.headers.get('authorization') === `Bearer ${process.env['TOKEN']}`
+				? {}
+				: reply(401, { error: 'unauthorized' }),
+		),
+});
+```
+
+`configure` and `beforeAll` must return the app; one that returns nothing
+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.
+
+## Behind a proxy
+
+A proxy or a load balancer that terminates TLS asks the server over plain
+HTTP, at an address of its own, so React Router's `request.url` reads
+`http://10.0.0.5:3000/…`. Name the proxies with `proxy`, `@alxia/core`'s
+`trustProxy`:
+
+```ts
+// app/server.ts
+import { trustProxy } from '@alxia/core';
+import { createServer } from '@alxia/react-router';
+
+export default createServer({
+	proxy: trustProxy({ trusted: ['10.0.0.0/8'], untrusted: 'refuse' }),
+});
+```
+
+```tsx
+// app/routes/login.tsx
+import type { LoaderFunctionArgs } from 'react-router';
+
+export function loader({ request }: LoaderFunctionArgs) {
+	// https://example.com/auth/callback behind the proxy
+	return { callback: new URL('/auth/callback', request.url).href };
+}
+```
+
+Every request through the catch-all is handed to React Router at
+`originalUrl(ctx)`: the scheme and host the trusted proxy wrote in
+`X-Forwarded-Proto` and `X-Forwarded-Host` (or `Forwarded`, with
+`header: 'forwarded'`), each checked, and the request's own for any it did
+not. A direct client's forwarded headers are ignored, or, with
+`untrusted: 'refuse'`, answered 403 before the pages. `ctx.url` and what
+alxia's middlewares read stay the request as it reached the server. With a
+server of your own, give `alxia({ proxy })` the same option. See
+[Behind a proxy](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/serving.md#behind-a-proxy-proxy)
+for what is believed and what is valid.
+
+## Escape hatches
+
+### Another server file
+
+`alxia({ entry })` names the server file, relative to Vite's root, in
+place of `app/server.ts`:
+
+```ts
+// vite.config.ts
+import { alxia } from '@alxia/react-router/vite';
+import { reactRouter } from '@react-router/dev/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+	plugins: [reactRouter(), alxia({ entry: 'server/main.ts' })],
+});
+```
+
+A missing `entry` is an error, where a missing `app/server.ts` falls back
+to the default server.
+
+### Overriding the wiring
+
+`build`, `mode` and `client` override what the plugin passes:
+
+```ts
+// app/server.ts: the client's files with headers of your own
+import { createServer } from '@alxia/react-router';
+
+export default createServer({
+	client: false,
+	beforeAll: (app) =>
+		app.static('/assets', 'build/client/assets', {
+			cacheControl: 'public, max-age=31536000, immutable',
+			precompressed: ['br'],
+		}),
+});
+```
+
+- **`client: false`** serves none of `build/client`: declare the files
+  yourself, in `beforeAll` or `configure`. A relative path there is
+  resolved against the process's working directory, the project's when it
+  runs `bun run start`.
+- **`client`**, a path or a `file:` URL, serves another folder in its
+  place.
+- **`mode`** forces React Router's server mode. `development` makes React
+  Router send its errors' stacks, and asks `build` for the build on every
+  request.
+- **`build`**, a `ServerBuild` or a function returning one, replaces React
+  Router's build: rarely wanted.
+
+### A server of your own, without the plugin
+
+`reactRouter(app, options)` is the catch-all itself, for a server that
+imports the build. Without the plugin, the dev server is React Router's
+own, and the loaders get no alxia context in dev.
+
+```ts
+// server.ts, beside build/
+import { alxia } from '@alxia/core';
+import { logger } from '@alxia/logger';
+import { reactRouter } from '@alxia/react-router';
+import type { ServerBuild } from 'react-router';
+
+export const base = alxia()
+	.use(logger())
+	.get('/api/health', ({ reply }) => reply.ok({ ok: true }));
+
+/** What the loaders read: alxiaOf<Base>(context). */
+export type Base = typeof base;
+
+const app = base.plugin((app) =>
+	reactRouter(app, {
+		build: () =>
+			import(new URL('./build/server/index.js', import.meta.url).href) as Promise<ServerBuild>,
+		client: new URL('./build/client', import.meta.url),
+	}),
+);
+
+app.listen({ port: Number(process.env['PORT'] ?? 3000) });
+```
+
+```sh
+bun run build && bun server.ts
+```
+
+| option | |
+| --- | --- |
+| `build` | a `ServerBuild`, loaded at startup; or a function returning one, called on the first request in `production`, again after a failed load, and on **every** request in `development` |
+| `mode` | React Router's server mode, `production` by default |
+| `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 `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
+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-).

package/docs/guide/deploying.md

@@ -0,0 +1,99 @@
+# Deploying
+
+This page covers running the build with Bun, and the Docker image.
+
+Run `bun run build`, then `bun build/server/index.js`. The build is
+[self-contained](how-it-works.md#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 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 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.
+FROM oven/bun:1 AS build
+WORKDIR /app
+COPY package.json bun.lock* bunfig.toml* ./
+RUN bun install --frozen-lockfile
+COPY . .
+RUN bun run build
+
+# 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 --from=build /app/build ./build
+USER bun
+EXPOSE 3000
+CMD ["bun", "--no-install", "build/server/index.js"]
+```
+
+```sh
+docker build -t my-app .
+docker run -p 3000:3000 my-app
+```
+
+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,
+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](how-it-works.md#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, within
+`shutdownTimeout`, and runs the app's `onStop` hooks. Give the platform a
+readiness probe with `@alxia/core`'s `health()`, mounted in `beforeAll`.