@alxia/react-router 0.3.0 → 0.5.0

package/docs/troubleshooting.md

@@ -36,6 +36,7 @@ a loader, a message React Router or the browser prints, or an error from
 - [`Module "…" has been externalized for browser compatibility, imported by "…"`](#module--has-been-externalized-for-browser-compatibility-imported-by-)
 - [`error: lockfile had changes, but lockfile is frozen`](#error-lockfile-had-changes-but-lockfile-is-frozen)
 - [`EACCES: permission denied, open '/app/…'`](#eacces-permission-denied-open-app)
+- [`error: Cannot find package '…' from '/app/build/server/index.js'`](#error-cannot-find-package--from-appbuildserverindexjs)
 
 **Types**
 
@@ -54,6 +55,8 @@ a loader, a message React Router or the browser prints, or an error from
 - [A page answers alxia's JSON 404 or 405 instead of rendering](#a-page-answers-alxias-json-404-or-405-instead-of-rendering)
 - [A streamed page arrives in one piece](#a-streamed-page-arrives-in-one-piece)
 - [The logger times a streamed page at a few milliseconds](#the-logger-times-a-streamed-page-at-a-few-milliseconds)
+- [A page, or a missing path, answers 401 behind a guard](#a-page-or-a-missing-path-answers-401-behind-a-guard)
+- [The logger, CORS or secure headers miss the client's files](#the-logger-cors-or-secure-headers-miss-the-clients-files)
 - [`ctx.server` is `undefined` under `react-router dev`](#ctxserver-is-undefined-under-react-router-dev)
 - [A `publish` under `react-router dev` misses the sockets opened before an edit](#a-publish-under-react-router-dev-misses-the-sockets-opened-before-an-edit)
 - [The build has a package's Node variant, not its `bun` one](#the-build-has-a-packages-node-variant-not-its-bun-one)
@@ -675,6 +678,63 @@ VOLUME /data
 const db = new Database('/data/app.sqlite');
 ```
 
+### `error: Cannot find package '…' from '/app/build/server/index.js'`
+
+`bun build/server/index.js`, in the container or from a copy of `build/`
+alone, stops at startup. For a package loaded with `require`, the message
+can read `Cannot find module '…'`. Or it starts, and a request fails with
+`ENOENT: no such file or directory, open '/app/build/…'`.
+
+**When:** the image holds `build/` alone, as the template's `Dockerfile`
+copies it, and the server imports a package that is not inside
+`build/server/index.js`:
+
+- the app keeps it external with `ssr.external`, and the image has no
+  `node_modules`;
+- or the build bundled it, but it reads a file of its own folder at
+  runtime (`new URL('./data.json', import.meta.url)`), or loads a native
+  addon (a `.node` file), neither of which bundling carries along.
+
+The image runs `bun --no-install`: without the flag, Bun finds no
+`node_modules` and fetches the missing package from npm at startup, at
+whatever version npm has, instead of failing.
+
+**Why:** under `react-router build` the plugin bundles every package into
+`build/server/index.js` ([Self-contained](guide.md#self-contained)), so
+the image needs no `node_modules`. What stays outside the file must be
+installed beside it.
+
+**Fix:** keep the package external, and give the image the production
+dependencies:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+	ssr: { external: ['sharp'] },
+	plugins: [reactRouter(), alxia()],
+});
+```
+
+```dockerfile
+# Dockerfile, before the build stage
+FROM oven/bun:1 AS production-dependencies
+WORKDIR /app
+COPY package.json bun.lock* bunfig.toml* ./
+RUN bun install --frozen-lockfile --production
+
+# Dockerfile, in the final stage, beside build/
+COPY --from=production-dependencies /app/node_modules ./node_modules
+```
+
+`grep '^import' build/server/index.js` lists what the build still
+imports: `node:*`, `bun`, `bun:*` and the packages `ssr.external` names.
+
+The image runs on `oven/bun:1-alpine`, whose C library is musl. A native
+addon built for glibc alone then stops it with
+`… is linked against glibc (DT_NEEDED …), but this Bun build uses musl.`:
+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)).
+
 ## Types
 
 ### `Property '…' does not exist on type 'BaseContext & …'`
@@ -684,10 +744,12 @@ error TS2339: Property 'tenant' does not exist on type 'BaseContext & Empty & {
 ```
 
 **When:** a loader reads, through `alxiaOf`, or `getLoadContext`
-destructures, something no hook of the server derives. With the type
+destructures, something no middleware of the server derives. With the type
 `'BaseContext & Empty'` alone, `alxiaOf(context)` has no server to read:
 `app/server.ts` has no `Register` declaration, or there is no
-`app/server.ts`.
+`app/server.ts`, and `@alxia/core`'s `Register` names no base either.
+With core's `Register` alone, `alxiaOf` reads that base: a key
+`configure` adds after it is missing.
 
 **Why:** the type is the app's context at the point of the catch-all, as
 for any route: "order is meaning".
@@ -810,7 +872,7 @@ argument, `alxiaOf<Server>(context)`.
 error TS2375: Type '{ context: EntryContext; url: string; nonce: string | undefined; }' is not assignable to type 'ServerRouterProps' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
 ```
 
-**Why:** `nonceOf` returns `undefined` when no hook set a nonce, and
+**Why:** `nonceOf` returns `undefined` when no middleware set a nonce, and
 `ServerRouterProps.nonce` is optional without `undefined`. React's
 `nonce` option takes `undefined`, so only the prop complains.
 
@@ -935,9 +997,45 @@ deferred value later. If the whole page comes at once:
 page that streams for 800 ms is logged at its first byte. The duration is
 the server's time to first byte, not the page's.
 
+### A page, or a missing path, answers 401 behind a guard
+
+A guard given to `use` in `configure` or `beforeAll` runs on every request
+it is in front of, a request no route matches included, and answers before
+the 404. An anonymous request to `/nope` gets the 401, not the 404, and so
+does the login page the guard sits in front of. Scope the guard to what it
+guards, with a path. A path-scoped `use` takes a middleware that adds nothing
+to the context, so `bearer`, which adds `user`, does not compile there: write
+the guard as a middleware that only refuses. The pages are a catch-all outside
+any `group`, so a `group` would not reach them.
+
+```ts
+import { defineMiddleware } from '@alxia/core';
+
+const account = defineMiddleware(async ({ request, reply }, next) => {
+	const token = request.headers.get('authorization')?.slice('Bearer '.length) ?? '';
+	return (await jwt.verify(token)).ok ? next() : reply(401, { error: 'unauthorized' as const });
+});
+
+createServer({
+	configure: (app) => app.use('/account', account), // the pages under /account only
+});
+```
+
+### The logger, CORS or secure headers miss the client's files
+
+A middleware in `configure` runs for the routes declared after it. The
+client's files are declared before `configure`, after `beforeAll`: what must
+see them too goes in `beforeAll`.
+
+```ts
+createServer({
+	beforeAll: (app) => app.use(logger()).use(secureHeaders()),
+});
+```
+
 ### `ctx.server` is `undefined` under `react-router dev`
 
-A hook or a route reads `ctx.server`, or the app declares a `page()`,
+A middleware or a route reads `ctx.server`, or the app declares a `page()`,
 under `react-router dev` or `vite preview`; the same code works from
 `bun build/server/index.js`.
 
@@ -946,7 +1044,7 @@ the preview server under `vite preview`. An HTTP request reaches the app
 through `app.fetch`, as in a test, not through `listen`: there is no
 `Bun.serve` behind it, so `ctx.server` is `undefined`, the default
 `ctx.ip` too, and a `page()` (Bun's HTML bundle) is not served. A socket's upgrade is the exception: the plugin relays it
-to a `Bun.serve` of the app, so its hooks read a server
+to a `Bun.serve` of the app, so its middlewares read a server
 ([WebSockets](guide.md#under-react-router-dev)).
 
 **Fix:** read `ctx.server` as optional, and publish to sockets from the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alxia/react-router",
-	"version": "0.3.0",
+	"version": "0.5.0",
 	"description": "alxia as the server of a React Router framework app: server rendering behind the app's hooks, loaders reading its typed context, the client's assets served",
 	"license": "MIT",
 	"type": "module",
@@ -51,9 +51,9 @@
 		]
 	},
 	"devDependencies": {
-		"@alxia/compress": "^0.1.2",
-		"@alxia/core": "^0.3.1",
-		"@alxia/openapi": "^0.3.0",
+		"@alxia/compress": "^0.2.0",
+		"@alxia/core": "^0.4.0",
+		"@alxia/openapi": "^0.4.0",
 		"@react-router/dev": "^8.4.0",
 		"@types/bun": "^1.4.2",
 		"@types/react": "^19.3.0",
@@ -65,7 +65,7 @@
 		"vite": "^7.0.0"
 	},
 	"peerDependencies": {
-		"@alxia/core": "^0.3.1",
+		"@alxia/core": "^0.4.0",
 		"react-router": "^8.0.0",
 		"typescript": "^6.0.3 || ^7.0.0",
 		"vite": "^7.0.0 || ^8.0.0"