@alxia/react-router 0.4.0 → 0.6.0

package/docs/troubleshooting.md

@@ -55,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)
@@ -727,6 +729,12 @@ 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 & …'`
@@ -736,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".
@@ -862,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.
 
@@ -987,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`.
 
@@ -998,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.4.0",
+	"version": "0.6.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.3.0",
+		"@alxia/core": "^0.5.0",
+		"@alxia/openapi": "^0.5.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.5.0",
 		"react-router": "^8.0.0",
 		"typescript": "^6.0.3 || ^7.0.0",
 		"vite": "^7.0.0 || ^8.0.0"