react-cheminfo 0.60.0 → 0.61.0

package/README.md

@@ -36,6 +36,7 @@ only when it drags a heavy dependency behind it.
 | `react-cheminfo/ui`                | every React component and hook — 60 value exports     | React                                            |
 | `react-cheminfo/vite`              | the prerender plugin and the OG card                  | nothing; React on the card                       |
 | `react-cheminfo/pages`             | the Cloudflare Pages analytics middleware             | nothing                                          |
+| `react-cheminfo/server`            | the prerendered build, served from Node               | fastify, @fastify/static; Node only              |
 | `react-cheminfo/orbital`           | the 3D atomic-orbital viewer                          | React, molstar                                   |
 | `react-cheminfo/molecule3d`        | the 3D molecule viewer and its toolbar                | React, molstar                                   |
 | `react-cheminfo/structure`         | the structure editor and renderer                     | React, react-ocl, OCL                            |
@@ -1222,6 +1223,34 @@ view costs one invocation rather than one per asset:
 { "version": 1, "include": ["/*"], "exclude": ["/assets/*"] }
 ```
 
+### On a Node server, next to an API
+
+A prerendered site can also be deployed as a server, with its API and its MCP
+tools beside the pages. `staticSite` from `react-cheminfo/server` serves the
+build by the rules the static hosts follow: `/titration` is `titration.html`
+with no redirect, an unknown address is `404.html` and never the home page,
+pages are revalidated on every visit and `assets/` is kept for a year, the
+`TRACKING_SCRIPT` snippet is in every page, and `/health` answers the deploy
+script. Only a file the build wrote is ever served.
+
+```ts
+import { fastify } from 'fastify';
+import { staticSite } from 'react-cheminfo/server';
+
+const app = fastify();
+// …the API under /v1/…
+await app.register(staticSite, {
+  root: 'dist',
+  trackingScript: process.env.TRACKING_SCRIPT,
+  redirects: { '/precipitation': '/equilibrium' },
+});
+```
+
+Addresses under `reserved` (default `['/v1/']`) are left to the API, which
+answers its own 404. Without a build, `staticSite` logs it and serves the API
+alone. `fastify` (5) and `@fastify/static` (10) are optional peers, installed
+by a site that has a server.
+
 ## Saying which build is running
 
 A report of something going wrong is worth answering only when we know what was

package/lib/server/siteFiles.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Every file of a built site, by its path from the root, written with `/`.
+ *
+ * The build does not change while the server runs, so the list is read once,
+ * and only a file on it is ever served: a path that climbs out of the root
+ * names nothing on the list.
+ * @param root - The directory the build wrote, e.g. `dist`.
+ * @returns The paths, e.g. `titration.html` and `assets/index-a1b2.js`, or
+ * `undefined` when the directory does not exist.
+ */
+export declare function listSiteFiles(root: string): Promise<Set<string> | undefined>;
+/**
+ * The file that answers an address, as the static hosts of the family answer
+ * it: `/titration` is `titration.html` (never a redirect to `/titration/`),
+ * `/` and `/fr/` are their `index.html`, and any other file is itself.
+ * @param files - The files of the site, from {@link listSiteFiles}.
+ * @param pathname - The address, without its query, e.g. `/titration`.
+ * @returns The file, or `undefined` when the site has no such page.
+ */
+export declare function resolveAddress(files: ReadonlySet<string>, pathname: string): string | undefined;
+/**
+ * Whether a file is a bundle named by its content, which a browser may keep
+ * for a year: everything under an `assets` directory.
+ * @param file - The file, from the root.
+ * @returns True for a hashed bundle.
+ */
+export declare function isHashedBundle(file: string): boolean;
+//# sourceMappingURL=siteFiles.d.ts.map

package/lib/server/siteFiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"siteFiles.d.ts","sourceRoot":"","sources":["../../src/server/siteFiles.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,CAWlC;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,EAC1B,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD"}

package/lib/server/siteFiles.js

@@ -0,0 +1,57 @@
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+/**
+ * Every file of a built site, by its path from the root, written with `/`.
+ *
+ * The build does not change while the server runs, so the list is read once,
+ * and only a file on it is ever served: a path that climbs out of the root
+ * names nothing on the list.
+ * @param root - The directory the build wrote, e.g. `dist`.
+ * @returns The paths, e.g. `titration.html` and `assets/index-a1b2.js`, or
+ * `undefined` when the directory does not exist.
+ */
+export async function listSiteFiles(root) {
+    if (!existsSync(root))
+        return undefined;
+    const entries = await readdir(root, { recursive: true, withFileTypes: true });
+    const files = new Set();
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        files.add(relative(root, join(entry.parentPath, entry.name)).split(sep).join('/'));
+    }
+    return files;
+}
+/**
+ * The file that answers an address, as the static hosts of the family answer
+ * it: `/titration` is `titration.html` (never a redirect to `/titration/`),
+ * `/` and `/fr/` are their `index.html`, and any other file is itself.
+ * @param files - The files of the site, from {@link listSiteFiles}.
+ * @param pathname - The address, without its query, e.g. `/titration`.
+ * @returns The file, or `undefined` when the site has no such page.
+ */
+export function resolveAddress(files, pathname) {
+    let path;
+    try {
+        path = decodeURIComponent(pathname);
+    }
+    catch {
+        return undefined;
+    }
+    const local = path.replace(/^\/+/, '');
+    const candidates = local === '' || local.endsWith('/')
+        ? [`${local}index.html`]
+        : [local, `${local}.html`, `${local}/index.html`];
+    return candidates.find((candidate) => files.has(candidate));
+}
+/**
+ * Whether a file is a bundle named by its content, which a browser may keep
+ * for a year: everything under an `assets` directory.
+ * @param file - The file, from the root.
+ * @returns True for a hashed bundle.
+ */
+export function isHashedBundle(file) {
+    return file.startsWith('assets/') || file.includes('/assets/');
+}
+//# sourceMappingURL=siteFiles.js.map

package/lib/server/siteFiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"siteFiles.js","sourceRoot":"","sources":["../../src/server/siteFiles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEhD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAY;IAEZ,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9E,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE;YAAE,SAAS;QAC9B,KAAK,CAAC,GAAG,CACP,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CACxE,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,KAA0B,EAC1B,QAAgB;IAEhB,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACvC,MAAM,UAAU,GACd,KAAK,KAAK,EAAE,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;QACjC,CAAC,CAAC,CAAC,GAAG,KAAK,YAAY,CAAC;QACxB,CAAC,CAAC,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,EAAE,GAAG,KAAK,aAAa,CAAC,CAAC;IACtD,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;AACjE,CAAC"}

package/lib/server/staticSite.d.ts

@@ -0,0 +1,42 @@
+import type { FastifyInstance } from 'fastify';
+/** Options of {@link staticSite}. */
+export interface StaticSiteOptions {
+    /** The directory the build wrote, e.g. `dist`. */
+    root: string;
+    /**
+     * The analytics snippet, put at the end of the head of every page, as
+     * `TRACKING_SCRIPT` holds it.
+     * @default undefined - no snippet
+     */
+    trackingScript?: string;
+    /**
+     * Addresses the site does not have any more, and the one that does their
+     * work. The query is carried over, so a link handed out before the move
+     * keeps its configuration.
+     * @default {}
+     */
+    redirects?: Readonly<Record<string, string>>;
+    /**
+     * Address prefixes another plugin answers, such as the API, which never
+     * answer a page: an unknown address there is the API's own 404.
+     * @default ['/v1/']
+     */
+    reserved?: readonly string[];
+}
+/**
+ * Serve a site's build from Node, with the rules every static host of the
+ * family follows (static-web-server's `sws.toml`, Cloudflare Pages): a real
+ * file per address and no fallback page, `/titration` answered without a
+ * redirect, pages checked on every visit and hashed bundles kept for a year,
+ * the analytics snippet in every page, `404.html` for an address the site does
+ * not have, and `/health` for the deploy script.
+ *
+ * Register it next to the API; a build missing (a server started before the
+ * frontend was built) leaves the API alone:
+ *
+ *   await app.register(staticSite, { root: 'dist', trackingScript });
+ * @param fastify - The server.
+ * @param options - The build, the snippet and the retired addresses.
+ */
+export declare function staticSite(fastify: FastifyInstance, options: StaticSiteOptions): Promise<void>;
+//# sourceMappingURL=staticSite.d.ts.map

package/lib/server/staticSite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staticSite.d.ts","sourceRoot":"","sources":["../../src/server/staticSite.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,eAAe,EAIhB,MAAM,SAAS,CAAC;AAMjB,qCAAqC;AACrC,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAiBD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CA4Df"}

package/lib/server/staticSite.js

@@ -0,0 +1,114 @@
+import { readFile } from 'node:fs/promises';
+import { join, relative, resolve, sep } from 'node:path';
+import { injectTrackingScript } from "../seo/core/trackingScript.js";
+import { isHashedBundle, listSiteFiles, resolveAddress } from "./siteFiles.js";
+/** A page is checked on every visit: it names the bundles of its own build. */
+const PAGE_CACHE = 'no-cache';
+/** A bundle is named by its content, so it never changes under its name. */
+const BUNDLE_CACHE = 'public, max-age=31536000, immutable';
+/** Kept out of the API's documentation (`@fastify/swagger` reads `hide`). */
+const HIDDEN = { hide: true };
+/**
+ * Serve a site's build from Node, with the rules every static host of the
+ * family follows (static-web-server's `sws.toml`, Cloudflare Pages): a real
+ * file per address and no fallback page, `/titration` answered without a
+ * redirect, pages checked on every visit and hashed bundles kept for a year,
+ * the analytics snippet in every page, `404.html` for an address the site does
+ * not have, and `/health` for the deploy script.
+ *
+ * Register it next to the API; a build missing (a server started before the
+ * frontend was built) leaves the API alone:
+ *
+ *   await app.register(staticSite, { root: 'dist', trackingScript });
+ * @param fastify - The server.
+ * @param options - The build, the snippet and the retired addresses.
+ */
+export async function staticSite(fastify, options) {
+    const { trackingScript, redirects = {}, reserved = ['/v1/'] } = options;
+    const root = resolve(options.root);
+    fastify.get('/health', { logLevel: 'silent', schema: HIDDEN }, (_request, reply) => reply.send({ status: 'ok' }));
+    const files = await listSiteFiles(root);
+    if (files === undefined) {
+        fastify.log.warn({ root }, 'no built site: serving the API alone');
+        return;
+    }
+    const pages = await readPages(root, files, trackingScript);
+    // An optional peer, installed only by a site that has a server: importing
+    // react-cheminfo/server must not need it.
+    const { default: fastifyStatic } = await import('@fastify/static');
+    await fastify.register(fastifyStatic, {
+        root,
+        serve: false,
+        cacheControl: false,
+        setHeaders: (reply, path) => {
+            const file = relative(root, path).split(sep).join('/');
+            if (isHashedBundle(file)) {
+                reply.header('cache-control', BUNDLE_CACHE);
+                // A page framed by a sandboxed view may run under an opaque origin,
+                // and a module bundle is then fetched cross-origin.
+                reply.header('access-control-allow-origin', '*');
+            }
+            else {
+                reply.header('cache-control', PAGE_CACHE);
+            }
+        },
+    });
+    const answer = (request, reply) => {
+        const url = new URL(request.url, 'http://site');
+        const { pathname, search } = url;
+        if (reserved.some((prefix) => pathname.startsWith(prefix))) {
+            return reply.callNotFound();
+        }
+        const destination = redirects[pathname] ?? redirects[pathname.replace(/\/$/, '')];
+        if (destination !== undefined) {
+            return reply.redirect(`${destination}${search}`, 301);
+        }
+        const file = resolveAddress(files, pathname);
+        if (file === undefined) {
+            return sendPage(request, reply, pages.get('404.html'), 404);
+        }
+        const page = pages.get(file);
+        if (page)
+            return sendPage(request, reply, page, 200);
+        return reply.sendFile(file);
+    };
+    fastify.get('/', { schema: HIDDEN }, answer);
+    fastify.get('/*', { schema: HIDDEN }, answer);
+}
+/**
+ * Read every page of the build once, with the snippet in its head.
+ * @param root - The build.
+ * @param files - Its files.
+ * @param trackingScript - The snippet, if any.
+ * @returns The pages, by file.
+ */
+async function readPages(root, files, trackingScript) {
+    const htmlFiles = [...files].filter((file) => file.endsWith('.html'));
+    const pages = await Promise.all(htmlFiles.map(async (file) => {
+        const html = injectTrackingScript(await readFile(join(root, file), 'utf8'), trackingScript);
+        return [file, { html, etag: await etagOf(html) }];
+    }));
+    return new Map(pages);
+}
+function sendPage(request, reply, page, status) {
+    if (page === undefined) {
+        return reply
+            .code(status)
+            .type('text/plain; charset=utf-8')
+            .send('Not found');
+    }
+    reply.header('cache-control', PAGE_CACHE).header('etag', page.etag);
+    if (status === 200 && request.headers['if-none-match'] === page.etag) {
+        return reply.code(304).send();
+    }
+    return reply.code(status).type('text/html; charset=utf-8').send(page.html);
+}
+async function etagOf(text) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+    const bytes = new Uint8Array(digest).subarray(0, 12);
+    let hex = '';
+    for (const byte of bytes)
+        hex += byte.toString(16).padStart(2, '0');
+    return `"${hex}"`;
+}
+//# sourceMappingURL=staticSite.js.map

package/lib/server/staticSite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staticSite.js","sourceRoot":"","sources":["../../src/server/staticSite.ts"],"names":[],"mappings":"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"}

package/lib/server.d.ts

@@ -0,0 +1,4 @@
+export type { StaticSiteOptions } from './server/staticSite.ts';
+export { staticSite } from './server/staticSite.ts';
+export { isHashedBundle, listSiteFiles, resolveAddress, } from './server/siteFiles.ts';
+//# sourceMappingURL=server.d.ts.map

package/lib/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EACL,cAAc,EACd,aAAa,EACb,cAAc,GACf,MAAM,uBAAuB,CAAC"}

package/lib/server.js

@@ -0,0 +1,3 @@
+export { staticSite } from "./server/staticSite.js";
+export { isHashedBundle, listSiteFiles, resolveAddress, } from "./server/siteFiles.js";
+//# sourceMappingURL=server.js.map

package/lib/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EACL,cAAc,EACd,aAAa,EACb,cAAc,GACf,MAAM,uBAAuB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-cheminfo",
-  "version": "0.60.0",
+  "version": "0.61.0",
   "license": "MIT",
   "description": "React components, hooks and framework-free helpers shared by the cheminfo sites: site chrome, citations, sharing, routing, pedagogy, charts, and the structure, orbital and 3D molecule viewers",
   "author": "Luc Patiny",
@@ -25,6 +25,7 @@
     "./molstar/*": "./lib/molstar/*/index.js",
     "./orbital": "./lib/orbital.js",
     "./pages": "./lib/pages.js",
+    "./server": "./lib/server.js",
     "./slides": "./lib/slides.js",
     "./spectra": "./lib/spectra.js",
     "./structure": "./lib/structure.js",
@@ -85,6 +86,7 @@
   },
   "devDependencies": {
     "@blueprintjs/core": "^6.18.0",
+    "@fastify/static": "^10.1.6",
     "@playwright/test": "^1.62.1",
     "@storybook/addon-docs": "^10.5.8",
     "@storybook/react-vite": "^10.5.8",
@@ -99,6 +101,7 @@
     "eslint": "^9.39.5",
     "eslint-config-cheminfo-react": "^20.1.0",
     "eslint-config-cheminfo-typescript": "^22.1.0",
+    "fastify": "^5.12.7",
     "jsdom": "^30.1.1",
     "ml-dataset-iris": "^1.2.1",
     "ml-pca": "^4.1.1",
@@ -119,6 +122,8 @@
   },
   "peerDependencies": {
     "@blueprintjs/core": "^6.18.0",
+    "@fastify/static": "^10.0.0",
+    "fastify": "^5.0.0",
     "ml-pca": "^4.1.1",
     "ml-signal-processing": "^2.2.2",
     "molstar": "^5.11.0",
@@ -139,6 +144,12 @@
   },
   "homepage": "https://github.com/cheminfo/react-cheminfo#readme",
   "peerDependenciesMeta": {
+    "@fastify/static": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
     "ml-pca": {
       "optional": true
     },

package/src/server/siteFiles.ts

@@ -0,0 +1,64 @@
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+
+/**
+ * Every file of a built site, by its path from the root, written with `/`.
+ *
+ * The build does not change while the server runs, so the list is read once,
+ * and only a file on it is ever served: a path that climbs out of the root
+ * names nothing on the list.
+ * @param root - The directory the build wrote, e.g. `dist`.
+ * @returns The paths, e.g. `titration.html` and `assets/index-a1b2.js`, or
+ * `undefined` when the directory does not exist.
+ */
+export async function listSiteFiles(
+  root: string,
+): Promise<Set<string> | undefined> {
+  if (!existsSync(root)) return undefined;
+  const entries = await readdir(root, { recursive: true, withFileTypes: true });
+  const files = new Set<string>();
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    files.add(
+      relative(root, join(entry.parentPath, entry.name)).split(sep).join('/'),
+    );
+  }
+  return files;
+}
+
+/**
+ * The file that answers an address, as the static hosts of the family answer
+ * it: `/titration` is `titration.html` (never a redirect to `/titration/`),
+ * `/` and `/fr/` are their `index.html`, and any other file is itself.
+ * @param files - The files of the site, from {@link listSiteFiles}.
+ * @param pathname - The address, without its query, e.g. `/titration`.
+ * @returns The file, or `undefined` when the site has no such page.
+ */
+export function resolveAddress(
+  files: ReadonlySet<string>,
+  pathname: string,
+): string | undefined {
+  let path: string;
+  try {
+    path = decodeURIComponent(pathname);
+  } catch {
+    return undefined;
+  }
+  const local = path.replace(/^\/+/, '');
+  const candidates =
+    local === '' || local.endsWith('/')
+      ? [`${local}index.html`]
+      : [local, `${local}.html`, `${local}/index.html`];
+  return candidates.find((candidate) => files.has(candidate));
+}
+
+/**
+ * Whether a file is a bundle named by its content, which a browser may keep
+ * for a year: everything under an `assets` directory.
+ * @param file - The file, from the root.
+ * @returns True for a hashed bundle.
+ */
+export function isHashedBundle(file: string): boolean {
+  return file.startsWith('assets/') || file.includes('/assets/');
+}

package/src/server/staticSite.ts

@@ -0,0 +1,188 @@
+import { readFile } from 'node:fs/promises';
+import { join, relative, resolve, sep } from 'node:path';
+
+import type {
+  FastifyInstance,
+  FastifyReply,
+  FastifyRequest,
+  FastifySchema,
+} from 'fastify';
+
+import { injectTrackingScript } from '../seo/core/trackingScript.ts';
+
+import { isHashedBundle, listSiteFiles, resolveAddress } from './siteFiles.ts';
+
+/** Options of {@link staticSite}. */
+export interface StaticSiteOptions {
+  /** The directory the build wrote, e.g. `dist`. */
+  root: string;
+  /**
+   * The analytics snippet, put at the end of the head of every page, as
+   * `TRACKING_SCRIPT` holds it.
+   * @default undefined - no snippet
+   */
+  trackingScript?: string;
+  /**
+   * Addresses the site does not have any more, and the one that does their
+   * work. The query is carried over, so a link handed out before the move
+   * keeps its configuration.
+   * @default {}
+   */
+  redirects?: Readonly<Record<string, string>>;
+  /**
+   * Address prefixes another plugin answers, such as the API, which never
+   * answer a page: an unknown address there is the API's own 404.
+   * @default ['/v1/']
+   */
+  reserved?: readonly string[];
+}
+
+/** A page: the file with the snippet in its head, and the tag a browser checks. */
+interface Page {
+  html: string;
+  etag: string;
+}
+
+/** A page is checked on every visit: it names the bundles of its own build. */
+const PAGE_CACHE = 'no-cache';
+
+/** A bundle is named by its content, so it never changes under its name. */
+const BUNDLE_CACHE = 'public, max-age=31536000, immutable';
+
+/** Kept out of the API's documentation (`@fastify/swagger` reads `hide`). */
+const HIDDEN: FastifySchema & { hide: boolean } = { hide: true };
+
+/**
+ * Serve a site's build from Node, with the rules every static host of the
+ * family follows (static-web-server's `sws.toml`, Cloudflare Pages): a real
+ * file per address and no fallback page, `/titration` answered without a
+ * redirect, pages checked on every visit and hashed bundles kept for a year,
+ * the analytics snippet in every page, `404.html` for an address the site does
+ * not have, and `/health` for the deploy script.
+ *
+ * Register it next to the API; a build missing (a server started before the
+ * frontend was built) leaves the API alone:
+ *
+ *   await app.register(staticSite, { root: 'dist', trackingScript });
+ * @param fastify - The server.
+ * @param options - The build, the snippet and the retired addresses.
+ */
+export async function staticSite(
+  fastify: FastifyInstance,
+  options: StaticSiteOptions,
+): Promise<void> {
+  const { trackingScript, redirects = {}, reserved = ['/v1/'] } = options;
+  const root = resolve(options.root);
+
+  fastify.get(
+    '/health',
+    { logLevel: 'silent', schema: HIDDEN },
+    (_request, reply) => reply.send({ status: 'ok' }),
+  );
+
+  const files = await listSiteFiles(root);
+  if (files === undefined) {
+    fastify.log.warn({ root }, 'no built site: serving the API alone');
+    return;
+  }
+  const pages = await readPages(root, files, trackingScript);
+
+  // An optional peer, installed only by a site that has a server: importing
+  // react-cheminfo/server must not need it.
+  const { default: fastifyStatic } = await import('@fastify/static');
+  await fastify.register(fastifyStatic, {
+    root,
+    serve: false,
+    cacheControl: false,
+    setHeaders: (reply, path) => {
+      const file = relative(root, path).split(sep).join('/');
+      if (isHashedBundle(file)) {
+        reply.header('cache-control', BUNDLE_CACHE);
+        // A page framed by a sandboxed view may run under an opaque origin,
+        // and a module bundle is then fetched cross-origin.
+        reply.header('access-control-allow-origin', '*');
+      } else {
+        reply.header('cache-control', PAGE_CACHE);
+      }
+    },
+  });
+
+  const answer = (request: FastifyRequest, reply: FastifyReply) => {
+    const url = new URL(request.url, 'http://site');
+    const { pathname, search } = url;
+    if (reserved.some((prefix) => pathname.startsWith(prefix))) {
+      return reply.callNotFound();
+    }
+    const destination =
+      redirects[pathname] ?? redirects[pathname.replace(/\/$/, '')];
+    if (destination !== undefined) {
+      return reply.redirect(`${destination}${search}`, 301);
+    }
+
+    const file = resolveAddress(files, pathname);
+    if (file === undefined) {
+      return sendPage(request, reply, pages.get('404.html'), 404);
+    }
+    const page = pages.get(file);
+    if (page) return sendPage(request, reply, page, 200);
+    return reply.sendFile(file);
+  };
+
+  fastify.get('/', { schema: HIDDEN }, answer);
+  fastify.get('/*', { schema: HIDDEN }, answer);
+}
+
+/**
+ * Read every page of the build once, with the snippet in its head.
+ * @param root - The build.
+ * @param files - Its files.
+ * @param trackingScript - The snippet, if any.
+ * @returns The pages, by file.
+ */
+async function readPages(
+  root: string,
+  files: ReadonlySet<string>,
+  trackingScript: string | undefined,
+): Promise<Map<string, Page>> {
+  const htmlFiles = [...files].filter((file) => file.endsWith('.html'));
+  const pages = await Promise.all(
+    htmlFiles.map(async (file) => {
+      const html = injectTrackingScript(
+        await readFile(join(root, file), 'utf8'),
+        trackingScript,
+      );
+      return [file, { html, etag: await etagOf(html) }] as const;
+    }),
+  );
+  return new Map(pages);
+}
+
+function sendPage(
+  request: FastifyRequest,
+  reply: FastifyReply,
+  page: Page | undefined,
+  status: number,
+) {
+  if (page === undefined) {
+    return reply
+      .code(status)
+      .type('text/plain; charset=utf-8')
+      .send('Not found');
+  }
+  reply.header('cache-control', PAGE_CACHE).header('etag', page.etag);
+  if (status === 200 && request.headers['if-none-match'] === page.etag) {
+    return reply.code(304).send();
+  }
+  return reply.code(status).type('text/html; charset=utf-8').send(page.html);
+}
+
+async function etagOf(text: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(text),
+  );
+  const bytes = new Uint8Array(digest).subarray(0, 12);
+  let hex = '';
+  for (const byte of bytes) hex += byte.toString(16).padStart(2, '0');
+  return `"${hex}"`;
+}

package/src/server.ts

@@ -0,0 +1,7 @@
+export type { StaticSiteOptions } from './server/staticSite.ts';
+export { staticSite } from './server/staticSite.ts';
+export {
+  isHashedBundle,
+  listSiteFiles,
+  resolveAddress,
+} from './server/siteFiles.ts';