@alxia/react-router 0.8.1 → 0.10.0

package/docs/roadmap.md

@@ -11,10 +11,15 @@ Nothing in progress.
 
 ## Next
 
-Nothing scheduled yet.
+Nothing planned.
 
 ## Later
 
+- **`service-worker.js` served revalidated with no setup.** Today the app
+  adds `noCache` for `SERVICE_WORKER_URL` itself.
+- **A check of an offline page's policy.** The offline page declares its
+  Content-Security-Policy in a `<meta>`; a check would read the page and
+  confirm that each inline script and style is allowed by its hash.
 - **`context.alxia` typed under `Route.LoaderArgs`.** Once react-router's
   `./internal` types and its main entry share one `RouterContextProvider`
   declaration, the generated route types see the shorthand too; today
@@ -48,6 +53,39 @@ Nothing scheduled yet.
 
 ## Shipped
 
+### 0.10.0
+
+- **`@alxia/react-router/pwa/worker`.** `startWorker({ contract })` is the
+  whole service worker on Workbox: the precache, a page load always from the
+  network with the offline page when it fails, hashed bundles cache-first,
+  other static files stale-while-revalidate, and the update applied on
+  request. An app's `app/service-worker.ts` is a few lines; the `workbox-*`
+  packages are optional peers ([guide](guide/pwa.md)).
+- **`@alxia/react-router/pwa/build`.** `buildWorker({ file })` bundles the
+  worker after `react-router build`, with the precache list written in: the
+  offline page, every route's code and the fonts you name.
+- **`alxia({ worker })`.** With `app/service-worker.ts` in the app,
+  `react-router build` writes `build/client/service-worker.js` itself, with
+  no script to add; `worker` names another file, tunes the build or turns
+  it off.
+
+### 0.9.0
+
+- **`@alxia/react-router/pwa`.** The code with no UI an installable app
+  shares, importing nothing: the service worker's contract and cache names
+  (`defineWorkerContract`), which requests the worker caches and which
+  responses it may store (`cachingFor`, `isStorable`), the precache list read
+  from the build, registering the worker and the update notice's store, the
+  web app manifest with its language in `?lang=`, and `clearAppCaches` for
+  sign-out. Every app-specific name is an option, so two apps never share a
+  default ([guide](guide/pwa.md)).
+- **`@alxia/react-router/pwa/react`.** `useOnline`, `useServiceWorker({
+  enabled })` and `useUpdateNotice`, with the page's one `updateNotice`;
+  `react` is an optional peer.
+- **`@alxia/react-router/pwa/server`.** `noCache` serves the worker's
+  script revalidated on every update check, with the worker's own policy
+  (`revalidated` and `WORKER_POLICY` beneath it).
+
 ### 0.8.0
 
 - **`withAlxia(fn)`.** A loader, an action or a middleware given `alxia`,

package/docs/troubleshooting.md

@@ -8,12 +8,14 @@ a loader, a message React Router or the browser prints, or an error from
 **Thrown or printed**
 
 - [`alxia-react-router: … is running on Node, and alxia's server runs on Bun. …`](#alxia-react-router--is-running-on-node-and-alxias-server-runs-on-bun-)
+- [`alxia-react-router: react-router build with a service worker is running on Node, and the worker is bundled by Bun.build`](#alxia-react-router-react-router-build-with-a-service-worker-is-running-on-node-and-the-worker-is-bundled-by-bunbuild)
 - [`ReferenceError: Bun is not defined`](#referenceerror-bun-is-not-defined)
 - [`alxiaOf(): this request has no alxia context. …`](#alxiaof-this-request-has-no-alxia-context-)
 - [`TypeError: undefined is not an object (evaluating 'context.alxia.user')`](#typeerror-undefined-is-not-an-object-evaluating-contextalxiauser)
 - [`Error: No value found for context`](#error-no-value-found-for-context)
 - [`alxia-react-router: … must export createServer() from @alxia/react-router as its default export: …`](#alxia-react-router--must-export-createserver-from-alxiareact-router-as-its-default-export-)
 - [`alxia-react-router: the entry … does not exist. …`](#alxia-react-router-the-entry--does-not-exist-)
+- [`alxia-react-router: the worker … does not exist. …`](#alxia-react-router-the-worker--does-not-exist-)
 - [`alxia-react-router: React Router's Vite plugin is not in this config. …`](#alxia-react-router-react-routers-vite-plugin-is-not-in-this-config-)
 - [`alxia-react-router: serverBundles splits React Router's server build in several, and alxia serves one. …`](#alxia-react-router-serverbundles-splits-react-routers-server-build-in-several-and-alxia-serves-one-)
 - [`alxia-react-router: Vite's ssr environment does not run modules in this process, so the server cannot be loaded.`](#alxia-react-router-vites-ssr-environment-does-not-run-modules-in-this-process-so-the-server-cannot-be-loaded)
@@ -38,6 +40,19 @@ a loader, a message React Router or the browser prints, or an error from
 - [`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)
+- [`TypeError: defineWorkerContract(): cachePrefix must be a non-empty name, …`](#typeerror-defineworkercontract-cacheprefix-must-be-a-non-empty-name-)
+- [`TypeError: defineWorkerContract(): cacheVersion must be a non-empty name without '-', …`](#typeerror-defineworkercontract-cacheversion-must-be-a-non-empty-name-without---)
+- [`parseBrowserManifest(): not React Router's browser manifest …`](#parsebrowsermanifest-not-react-routers-browser-manifest-)
+- [`error: Cannot find package 'react' from '…/@alxia/react-router/dist/pwa/react/index.js'`](#error-cannot-find-package-react-from-alxiareact-routerdistpwareactindexjs)
+- [`startWorker(): no precache list. …`](#startworker-no-precache-list-)
+- [`TypeError: startWorker(): contract is required: …`](#typeerror-startworker-contract-is-required-)
+- [`error: Could not resolve: "workbox-core". Maybe you need to "bun install"?`](#error-could-not-resolve-workbox-core-maybe-you-need-to-bun-install)
+- [`buildWorker() runs on Bun: it is running on Node`](#buildworker-runs-on-bun-it-is-running-on-node)
+- [`buildWorker(): app/service-worker.ts does not exist.`](#buildworker-appservice-workerts-does-not-exist)
+- [`buildWorker(): expected one React Router browser manifest`](#buildworker-expected-one-react-router-browser-manifest)
+- [`buildWorker(): build/client/offline.html does not exist`](#buildworker-buildclientofflinehtml-does-not-exist)
+- [`buildWorker(): … is outside ….`](#buildworker--is-outside-)
+- [`buildWorker(): Bun.build failed:`](#buildworker-bunbuild-failed)
 
 **Types**
 
@@ -63,14 +78,23 @@ a loader, a message React Router or the browser prints, or an error from
 - [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)
 - [`request.url` in a loader is `http://` and the internal host behind a proxy](#requesturl-in-a-loader-is-http-and-the-internal-host-behind-a-proxy)
+- [An unhashed file under `public/assets/` is cached for a year](#an-unhashed-file-under-publicassets-is-cached-for-a-year)
+- [A cache the contract did not make is swept](#a-cache-the-contract-did-not-make-is-swept)
+- [The update notice never shows](#the-update-notice-never-shows)
+- [The worker registers under `react-router dev`](#the-worker-registers-under-react-router-dev)
+- [The service worker is not built](#the-service-worker-is-not-built)
+- [Offline, a client navigation to a route never visited shows the offline page](#offline-a-client-navigation-to-a-route-never-visited-shows-the-offline-page)
+- [An update waits an hour](#an-update-waits-an-hour)
+- [The worker cannot fetch another origin](#the-worker-cannot-fetch-another-origin)
+- [The manifest is in the wrong language](#the-manifest-is-in-the-wrong-language)
 
 ## Thrown or printed
 
 ### `alxia-react-router: … is running on Node, and alxia's server runs on Bun. …`
 
 **When:** `bun run dev`, `vite preview`, or a `react-router build` that
-prerenders, on a machine where a node is installed. The full message under
-`react-router dev`:
+prerenders or builds a service worker (`app/service-worker.ts`), on a machine
+where a node is installed. The full message under `react-router dev`:
 
 ```
 alxia-react-router: react-router dev is running on Node, and alxia's server runs on Bun. Add a bunfig.toml beside package.json with "[run]" and "bun = true", so bun run starts it on Bun, or run it as bun --bun react-router dev.
@@ -92,7 +116,18 @@ bun = true
 Or run the one command on Bun: `bun --bun react-router dev`. Under
 `vite preview` or a prerendering build, the message begins
 `alxia-react-router: vite preview, or a react-router build that prerenders, is running on Node`
-and names `bun --bun vite preview` and `bun --bun react-router build`.
+and names `bun --bun vite preview` and `bun --bun react-router build`. A
+build that has a service worker reads
+`alxia-react-router: react-router build with a service worker is running on Node, and the worker is bundled by Bun.build`
+and names the same `bun --bun react-router build`.
+
+### `alxia-react-router: react-router build with a service worker is running on Node, and the worker is bundled by Bun.build`
+
+The same cause as
+[the entry above](#alxia-react-router--is-running-on-node-and-alxias-server-runs-on-bun-):
+the build runs on Node, and the worker is bundled with `Bun.build`. Run it as
+`bun --bun react-router build`, or add a `bunfig.toml` beside `package.json`
+with `[run]` and `bun = true`.
 
 ### `ReferenceError: Bun is not defined`
 
@@ -133,7 +168,7 @@ key: one copy is the fix for both.
   sets.
 
 **Fix:** add `alxia()` to `vite.config.ts`, as in the
-[setup](guide.md#setup). With a server of your own in a monorepo, tell
+[setup](guide/getting-started.md). With a server of your own in a monorepo, tell
 Vite to leave the package external:
 
 ```ts
@@ -210,7 +245,7 @@ reactRouter(app, { build, getLoadContext: ({ user }, context) => context.set(use
 **Fix:** serve the app with the plugin, `alxia()` in `vite.config.ts`: the
 server is then built with the routes, and `app/context.ts` is one module
 for both, in dev and in the build. See
-[the app's own context keys](guide.md#the-apps-own-context-keys).
+[the app's own context keys](guide/typing-the-loaders.md#the-apps-own-context-keys).
 
 Without the plugin, read alxia's context with `alxiaOf`: its key,
 `alxiaContext`, lives in this package under `node_modules`, which Vite
@@ -245,7 +280,7 @@ export default server;
 ```
 
 An alxia app of your own, with `reactRouter()` on it, is served without the
-plugin: see [a server of your own](guide.md#a-server-of-your-own-without-the-plugin).
+plugin: see [a server of your own](guide/customising-the-server.md#a-server-of-your-own-without-the-plugin).
 
 ### `alxia-react-router: the entry … does not exist. …`
 
@@ -262,6 +297,20 @@ Vite's root. Under `react-router dev` each request is a 500 saying so;
 
 **Fix:** correct the path, or leave `entry` out.
 
+### `alxia-react-router: the worker … does not exist. …`
+
+```text
+Error: alxia-react-router: the worker app/pwa/worker.ts does not exist. Create it, or leave worker out to build app/service-worker.ts when it exists.
+```
+
+**When:** `alxia({ worker })` names a file that is not there, relative to
+Vite's root, and `react-router build` fails.
+
+**Why:** a missing `app/service-worker.ts` just means no worker, but a
+`worker` you named is taken as meant.
+
+**Fix:** correct the path, or leave `worker` out.
+
 ### `alxia-react-router: React Router's Vite plugin is not in this config. …`
 
 ```text
@@ -465,7 +514,7 @@ export default createServer({
 
 or `contentSecurityPolicy: false`. Better than `'unsafe-inline'`: a nonce
 per request, with `nonce: true` and `nonceOf(loadContext)` in
-`entry.server.tsx` ([guide](guide.md#a-csp-nonce)).
+`entry.server.tsx` ([guide](guide/csp-nonce.md#a-csp-nonce)).
 
 ### `alxia-react-router: … already exists, and reveal leaves it as it is. Run alxia-react-router reveal --force to overwrite it.`
 
@@ -651,7 +700,7 @@ bun add -d typescript@^6
 and uses it outside its `loader` and `action`, in the component or at the
 module's top level. React Router keeps that code in the client build, for
 the browser, which has no such module. The server build leaves Bun's
-modules external ([Built for Bun](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide.md#built-for-bun));
+modules external ([Built for Bun](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/how-it-works.md#built-for-bun));
 the client build cannot.
 
 **Fix:** use them only in the server's code: in `loader` and `action`, or
@@ -735,7 +784,7 @@ The image runs `bun --no-install`: without the flag, Bun finds no
 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
+`build/server/index.js` ([Self-contained](guide/how-it-works.md#self-contained)), so
 the image needs no `node_modules`. What stays outside the file must be
 installed beside it.
 
@@ -770,6 +819,219 @@ addon built for glibc alone then stops it with
 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)).
 
+### `TypeError: defineWorkerContract(): cachePrefix must be a non-empty name, …`
+
+The full message is `defineWorkerContract(): cachePrefix must be a non-empty
+name, such as 'my-app'; got ''.`, or `… must not end with '-', which the
+contract adds; got 'my-app-'. Use 'my-app'.`
+
+**Why:** every cache name is `<prefix>-<kind>-<version>`, and the worker
+deletes the caches shaped `<prefix>-<kind>-<version>`. An empty prefix would own
+every cache of the origin, and a trailing dash would be doubled.
+
+**Fix:** pass the app's own name, without the dash:
+
+```ts
+import { defineWorkerContract } from '@alxia/react-router/pwa';
+
+export const workerContract = defineWorkerContract({ cachePrefix: 'my-app' });
+```
+
+### `TypeError: defineWorkerContract(): cacheVersion must be a non-empty name without '-', …`
+
+The full message is `defineWorkerContract(): cacheVersion must be a
+non-empty name without '-', such as 'v2'; got 'v1-beta'.`
+
+**Why:** every cache name is `<prefix>-<kind>-<version>`, and the contract
+tells a version from the rest of the name by its dashes. A version with a `-`
+(or an empty one) would make the name ambiguous.
+
+**Fix:** use a name with no dash, such as `'v2'` or `'2026'`:
+
+```ts
+import { defineWorkerContract } from '@alxia/react-router/pwa';
+
+export const workerContract = defineWorkerContract({
+	cachePrefix: 'my-app',
+	cacheVersion: 'v2',
+});
+```
+
+### `parseBrowserManifest(): not React Router's browser manifest …`
+
+The full message ends with `(build/client/assets/manifest-*.js).`
+
+**Why:** the source holds no `{ … }` object. The build script read another
+file, an empty one, or the build has not run.
+
+**Fix:** run `react-router build` first, then read the file named
+`manifest-<hash>.js` in `build/client/assets`, not the server's manifest:
+
+```ts
+import { readdirSync, readFileSync } from 'node:fs';
+import { parseBrowserManifest } from '@alxia/react-router/pwa';
+
+const assets = 'build/client/assets';
+const file = readdirSync(assets).find((name) => /^manifest-.*\.js$/.test(name));
+if (!file) throw new Error('Run react-router build first.');
+export const manifest = parseBrowserManifest(readFileSync(`${assets}/${file}`, 'utf8'));
+```
+
+### `error: Cannot find package 'react' from '…/@alxia/react-router/dist/pwa/react/index.js'`
+
+**Why:** `@alxia/react-router/pwa/react` imports `react`, an optional peer of
+the package, so nothing installs it for you. An app with no `react` does not
+need the subpath; a build script or the worker importing it by mistake meets
+this message too.
+
+**Fix:** add `react` where the page is built (`bun add react`), and import
+`/pwa/react` from the page alone. The worker and a build script import
+`@alxia/react-router/pwa`, which imports nothing.
+
+### `startWorker(): no precache list. …`
+
+**Why:** the full message ends "Build this worker with `alxia()` from
+`@alxia/react-router/vite` (`app/service-worker.ts`) or `buildWorker()` from
+`@alxia/react-router/pwa/build`, which write it in." `startWorker` precaches
+the list the build defines in the bundle (`globalThis.__ALXIA_PRECACHE__`);
+a worker bundled by anything else has none, and the page would install a
+worker that precaches nothing.
+
+**Fix:** either build the worker with the build that writes the list
+(`alxia()` or `buildWorker()`), or pass the list yourself, which works for a
+worker bundled any other way:
+
+```ts
+startWorker({
+	contract,
+	precache: [{ url: '/offline.html', revision: 'v1' }],
+});
+```
+
+`precache` wins over the list the build wrote. A bundle of your own may
+instead define `globalThis.__ALXIA_PRECACHE__`.
+
+### `TypeError: startWorker(): contract is required: …`
+
+**Why:** the full message continues "pass `defineWorkerContract({ cachePrefix })`
+from `@alxia/react-router/pwa`." The worker's cache names, its offline page
+and its URL come from the contract the page shares, so there is no default.
+
+**Fix:**
+
+```ts
+// file: app/service-worker.ts
+import { defineWorkerContract } from '@alxia/react-router/pwa';
+import { startWorker } from '@alxia/react-router/pwa/worker';
+
+startWorker({ contract: defineWorkerContract({ cachePrefix: 'my-app' }) });
+```
+
+### `error: Could not resolve: "workbox-core". Maybe you need to "bun install"?`
+
+**Why:** `@alxia/react-router/pwa/worker` imports six `workbox-*` packages,
+optional peers of the package, so nothing installs them for you. They are
+bundled into the worker, never loaded at run time.
+
+**Fix:** add them as development dependencies:
+
+```sh
+bun add -d workbox-core workbox-expiration workbox-navigation-preload \
+  workbox-precaching workbox-routing workbox-strategies
+```
+
+The `buildWorker()` messages below are the ones a script of your own sees.
+Under `alxia()` each of them begins with `alxia-react-router: `.
+
+### `buildWorker() runs on Bun: it is running on Node`
+
+```text
+buildWorker() runs on Bun: it is running on Node. Run it with bun, or run react-router build with bun --bun.
+```
+
+**When:** a script of your own calls `buildWorker()` and runs on Node. Under
+`alxia()` the check comes first and reads
+[`… is running on Node, and the worker is bundled by Bun.build`](#alxia-react-router--is-running-on-node-and-alxias-server-runs-on-bun-).
+
+**Why:** the worker is bundled with `Bun.build`, which Node does not have.
+
+**Fix:** run the script with `bun scripts/build-worker.ts`, or
+`react-router build` as `bun --bun react-router build`.
+
+### `buildWorker(): app/service-worker.ts does not exist.`
+
+```text
+buildWorker(): app/service-worker.ts does not exist.
+```
+
+**Why:** `file` is read from `root` (`process.cwd()` by default), not from the
+script's folder. Under `alxia()` the message begins
+`alxia-react-router: buildWorker(): …`.
+
+**Fix:** pass the path relative to the project root, or pass `root`.
+
+### `buildWorker(): expected one React Router browser manifest`
+
+```text
+buildWorker(): expected one React Router browser manifest, build/client/assets/manifest-*.js, found 0. Run react-router build first.
+```
+
+The message ends `found 2` when two are left.
+
+**Why:** the precache list is read from React Router's browser manifest,
+which `react-router build` writes. None means the build did not run, or
+`client` is wrong. Two mean a stale build folder.
+
+**Fix:** run `react-router build` first, check `client`, and delete `build/`
+when two manifests are left.
+
+### `buildWorker(): build/client/offline.html does not exist`
+
+```text
+buildWorker(): build/client/offline.html does not exist. Add public/offline.html, or pass offline: false (`worker: { offline: false }` in alxia()), or pass the app's contract (`worker: { contract }` in alxia()).
+```
+
+**Why:** the offline page is precached by default and is read from the client
+build, where `public/offline.html` is copied. The build reads the contract's
+`offlineUrl` from the `contract` option, and the worker from the contract it
+is given: two objects can disagree.
+
+**Fix:** add the page to `public/`, or pass `offline: false` for a worker with
+no offline page. If the contract's `offlineUrl` is another path, pass the same
+contract object to the build (`alxia({ worker: { contract } })`, or
+`buildWorker({ contract })`).
+
+### `buildWorker(): … is outside ….`
+
+```text
+buildWorker(): /../service-worker.js is outside /app/build/client.
+```
+
+**Why:** the contract's `serviceWorkerUrl` or `offlineUrl` is joined onto the
+client build, and the result leaves it, or is the client build itself (`/`).
+The build refuses to write or read a file there. It also refuses an absolute
+URL (`https://example.com/sw.js`), a protocol-relative one (`//host/sw.js`) and
+one that does not start with `/`, since none names a file of the build.
+
+**Fix:** use a root-relative URL inside the site, such as
+`/service-worker.js`, in the contract.
+
+### `buildWorker(): Bun.build failed:`
+
+```text
+buildWorker(): Bun.build failed:
+```
+
+Bun's logs follow the message.
+
+**Why:** the worker's source or one of its imports did not bundle: a missing
+`workbox-*` package, a wrong import path.
+
+**Fix:** read the first log line. The six `workbox-*` packages are optional
+peers, installed as
+[`Could not resolve: "workbox-core"`](#error-could-not-resolve-workbox-core-maybe-you-need-to-bun-install)
+shows.
+
 ## Types
 
 ### `Property 'alxia' does not exist on type 'Readonly<RouterContextProvider>'`
@@ -989,7 +1251,7 @@ following Content Security Policy directive: "script-src 'self'
   attribute.
 
 **Fix:** reveal the entry and pass `nonceOf(loadContext)` to both
-([guide](guide.md#a-csp-nonce)). A script of your own reads the nonce
+([guide](guide/csp-nonce.md#a-csp-nonce)). A script of your own reads the nonce
 through a loader, where `nonceOf(context)` works as well:
 
 ```tsx
@@ -1119,7 +1381,7 @@ plugin relays the app's sockets to. So `ctx.server` is that side server: its
 and its `requestIP` and `timeout` know nothing of a request Vite took, so
 the default `ctx.ip` is `undefined`. A `page()` (Bun's HTML bundle) is not
 served: Vite answers the HTML
-([The server](guide.md#the-server-server)).
+([The server](guide/typing-the-loaders.md#the-server-server)).
 
 **Fix:** read `ctx.server` as optional, which also covers `app.request` in
 a test, and take nothing from its `url` or `requestIP` in dev:
@@ -1188,3 +1450,132 @@ export default createServer({ proxy: trustProxy({ trusted: ['10.0.0.0/8'] }) });
 
 React Router then gets its request at `originalUrl(ctx)`
 ([Behind a proxy](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/serving.md#behind-a-proxy-proxy)).
+
+### An unhashed file under `public/assets/` is cached for a year
+
+A file you put in `public/assets/` (a sprite, an icon) changes on a deploy,
+and visitors keep the old one.
+
+**Why:** Vite copies `public/` into `build/client/`, and the client's files
+under `build/client/assets/` are served `public, max-age=31536000,
+immutable`, hashed or not. The worker's `cachingFor` agrees by default:
+everything under `/assets/` is `immutable`, cache-first.
+
+**Fix:** keep unhashed files out of `assets/`: `public/icons/` is served for
+an hour and is `static` for the worker. If they must stay there, give
+`cachingFor` an `immutable` option that leaves their folder out, so the worker
+revalidates them ([the option](guide/pwa.md#what-the-worker-caches)),
+and expect the HTTP cache to hold them for a year until the file's name
+changes.
+
+### A cache the contract did not make is swept
+
+Signing out, or a new worker activating, deletes a cache the app made itself.
+
+**Why:** a contract owns every cache named exactly
+`<prefix>-<kind>-<version>`, kind being lowercase letters and digits and
+version having no `-`. That includes a kind the app retired (`my-app-pages-v0` is swept once
+it is not current). It is also why `app` and `app-admin` can share an origin:
+`app-admin-assets-v1` has one segment too many to be `app`'s. Contracts never
+take each other's caches; only a cache made by other code, such as
+`my-app-runtime-v1`, matches the shape and is swept.
+
+**Fix:** name your own caches outside the shape. A name is outside it when it
+has more than `<kind>-<version>` after `<prefix>-`, with the prefix `my-app`:
+`my-app-runtime-v1-x`. A kind with an uppercase letter, `_` or `.`
+(`my-app-Runtime-v1`, `my-app-run_time-v1`), or a different prefix, is outside
+too.
+
+### The update notice never shows
+
+A new version is deployed and the page offers no "Reload".
+
+**Why:** the notice is offered only when a worker finished installing while
+an older one controls the page. A first install controls nothing, so it
+offers nothing; the next visit, with the first worker in control, does. And
+nothing is registered at all where the app does not call
+`registerServiceWorker` (for example while `useServiceWorker({ enabled })`
+is given `false`, as `import.meta.env.PROD` is under `react-router dev`). A
+tab that chose "Later" stays quiet until the next session.
+
+**Fix:** build, serve and load the page twice, then deploy a change and load
+it again. In the console, `navigator.serviceWorker.controller` must not be
+`null` and `(await navigator.serviceWorker.getRegistration()).waiting` must
+hold the new worker.
+
+### The worker registers under `react-router dev`
+
+The dev server serves stale code after an edit, or a page keeps an old
+version of itself, and `navigator.serviceWorker.controller` is not `null`.
+
+**Why:** `useServiceWorker` registers whenever `enabled` is `true`, and the
+package does not know the mode: it never reads `import.meta.env`. A worker
+under a dev server caches the code you are editing.
+
+**Fix:** pass the mode from the app, `useServiceWorker({ enabled:
+import.meta.env.PROD })` ([the hook](guide/pwa.md#in-react)). Then unregister
+the worker the dev server already took (DevTools, Application, Service
+Workers, Unregister) and clear its site data.
+
+### The service worker is not built
+
+`react-router build` ends and there is no `build/client/service-worker.js`.
+
+**Why:** `alxia()` builds no worker when the file is not at
+`app/service-worker.ts` (the `appDirectory` of `react-router.config.ts` may
+hold another) and no `worker` option names it, when `worker: false` is set,
+or when the version of `@alxia/react-router` is older than 0.10.
+
+**Fix:** put the file at `app/service-worker.ts`, or name it with
+`alxia({ worker: 'app/pwa/worker.ts' })`, and update the package.
+
+### Offline, a client navigation to a route never visited shows the offline page
+
+The page opens offline, but a link to a route the user never opened leads to
+`/offline.html`.
+
+**Why:** React Router asks `/__manifest` for the routes a link needs, and the
+worker never caches that request.
+
+**Fix:** set `routeDiscovery: { mode: 'initial' }` in `react-router.config.ts`,
+so the client has every route from its first load.
+
+### An update waits an hour
+
+A new worker is deployed and tabs still run the old one for up to an hour.
+
+**Why:** the worker's script was served with the client's hour of
+`Cache-Control`, so the browser's update check found the cached script.
+Either `noCache` is not declared, or it is declared in `configure`, which
+runs after the client's files: they answer first and the middleware never
+sees the request.
+
+**Fix:** declare it in `beforeAll`
+([serving the worker's script](guide/pwa.md#serving-the-workers-script)), and
+check with `curl -I https://your.app/service-worker.js` that `cache-control` is
+`no-cache`.
+
+### The worker cannot fetch another origin
+
+The console reports `Refused to connect to 'https://api.example.com/…' because it violates the following Content Security Policy directive: "connect-src 'self'"` from the worker.
+
+**Why:** `noCache` gives the worker's script `WORKER_POLICY`,
+`default-src 'none'; connect-src 'self'`: the worker fetches this site only.
+
+**Fix:** if the worker really must reach another origin, serve the script
+with a wider policy through `revalidated(response, policy)` in a middleware of
+your own ([serving the worker's script](guide/pwa.md#serving-the-workers-script)),
+rather than loosening the pages' policy.
+
+### The manifest is in the wrong language
+
+The installed app's name and description are in the default language,
+whatever the user chose.
+
+**Why:** the browser fetches the manifest without cookies, so the `language`
+cookie never reaches the server. Only the link's query does.
+
+**Fix:** link `manifestHref(language)` (`/manifest.webmanifest?lang=fr`), and
+read it with `manifestLanguage(url, supported, fallback)`; the fallback is a
+supported language the app resolves from the request's `Accept-Language`, not
+from the cookie ([the manifest route](guide/pwa.md#the-web-app-manifest-and-why-the-language-travels-in-lang)).