From 57719d7fd400721783a059fee78c7d33a21cd9b6 Mon Sep 17 00:00:00 2001 From: Adam <2363879+adamdotdevin@users.noreply.github.com> Date: Tue, 10 Nov 2026 03:34:19 -0600 Subject: [PATCH] refactor(site): make every page static and stop shipping the app's JavaScript (#63067) --- services/site/AGENTS.md | 4 +- services/site/script/check-client-bundle.ts | 92 +++----- services/site/script/check-worker-start.ts | 18 +- services/site/script/i18n-plugin.ts | 77 +------ services/site/script/i18n-slices.ts | 23 +- services/site/script/static-client.ts | 27 ++- services/site/script/stylesheet-groups.ts | 8 +- services/site/src/app.tsx | 23 +- services/site/src/client/entry.ts | 208 +++++++++--------- services/site/src/client/islands.ts | 8 + services/site/src/client/islands/arcade.tsx | 33 +++ services/site/src/client/islands/font.tsx | 38 ++++ services/site/src/component/font/specimen.tsx | 6 +- .../site/arcade3d/not-found-page.tsx | 2 + .../src/component/site/preload-touched.ts | 29 --- services/site/src/component/site/site.tsx | 23 +- services/site/src/entry-client.tsx | 5 +- services/site/src/entry-server.tsx | 45 +--- services/site/src/global.d.ts | 9 - services/site/src/i18n/preload.ts | 26 --- services/site/src/lib/head-links.ts | 35 ++- services/site/src/lib/route-preloads.ts | 65 ------ services/site/src/static/render.tsx | 28 ++- services/site/src/static/routes.ts | 15 +- services/site/test/head-links.test.ts | 22 +- services/site/test/i18n-slices.test.ts | 13 +- services/site/test/route-preloads.test.ts | 73 ------ services/site/test/static-routes.test.ts | 15 +- services/site/vite.config.ts | 29 --- 29 files changed, 373 insertions(+), 626 deletions(-) create mode 100644 services/site/src/client/islands/arcade.tsx create mode 100644 services/site/src/client/islands/font.tsx delete mode 100644 services/site/src/component/site/preload-touched.ts delete mode 100644 services/site/src/i18n/preload.ts delete mode 100644 services/site/src/lib/route-preloads.ts delete mode 100644 services/site/test/route-preloads.test.ts diff --git a/services/site/AGENTS.md b/services/site/AGENTS.md index caf15c45c84..09b4423fdee 100644 --- a/services/site/AGENTS.md +++ b/services/site/AGENTS.md @@ -21,11 +21,11 @@ Read the design-system rules in `DESIGN.md` (also shown at `/dev/components#rule ## Static pages -- The pages in `staticPaths` (`src/static/routes.ts`: home, the product pages, legal, Brand, Press, the changelog and Browse) render in production as plain HTML from the same components, without hydration (`src/static/render.tsx`). They load one small script, `src/client/entry.ts`, which reads the markup the components render and loads each island in `src/client/islands/` only when the page has it. +- Production hydrates no page. The pages in `staticPaths` (`src/static/routes.ts`: home, the product pages, legal, Brand, Press, the changelog, Browse and the font page) render as plain HTML from the same components, without hydration (`src/static/render.tsx`), and so does the not-found page, for every address no route answers. They load one small script, `src/client/entry.ts`, which reads the markup the components render and loads each island in `src/client/islands/` only when the page has it. The app's browser build only provides the stylesheets. - Between the home page, /product and the product pages, a card grows into its product's hero and back with a cross-document view transition (`card-morph.ts`); every other page change is a plain page load. - Behaviour both renderings need lives in framework-free modules in `src/component/site/` that the component and the script both call, such as `contents-spy.ts`, `changelog-motion.ts`, `tooltips.ts`, `site-frame.ts`, `theme-switch.ts` and `sheet-motion.ts`. Put new behaviour there. Where a component renders its state from signals and the script keeps its own copy, each names the other in a comment: change both. - `vite dev` renders these pages hydrated, because Design mode and Settings need the app, so a change that only works hydrated looks right there. Check them in a production build served by `perf/serve.ts`: `bun run build`, then `bun perf/serve.ts --port 4300`, and open the page on that port. -- To serve a page hydrated again, remove its path from `staticPaths`. +- A new page route needs its path in `staticPaths`, or production answers it with the not-found page (`test/static-routes.test.ts` lists the ones that may be missing: the development tools). ## Funnel diff --git a/services/site/script/check-client-bundle.ts b/services/site/script/check-client-bundle.ts index 4aabac38bd4..7ad15542d52 100644 --- a/services/site/script/check-client-bundle.ts +++ b/services/site/script/check-client-bundle.ts @@ -5,14 +5,11 @@ // Also fails when server-only code reaches it: the Worker's cache, GitHub calls and the build-time // GitHub snapshot. Pages may import their modules for the queries, whose "use server" bodies the // browser build drops along with everything only those bodies read. -// Last, it fails when a page's initial JavaScript (the entry and every chunk the page's route imports -// statically, which the server modulepreloads) passes its budget below, gzipped. A static page -// (src/static/routes.ts) loads the static pages' one script (src/client/entry.ts) instead, and has -// its budget. Code a page needs only later belongs behind a dynamic import. +// Last, it fails when the app's own scripts ship, or the one script every page loads passes its budget +// below. Code a page needs only later belongs behind a dynamic import. // Run after `vite build`, optionally with the output directory: `bun script/check-client-bundle.ts .output`. import path from "node:path" import { Glob } from "bun" -import { staticPath } from "../src/static/routes" const root = path.resolve(process.argv[2] ?? path.join(import.meta.dir, "..", ".output"), "public") // Strings only the tools' own code contains, as they survive minification. @@ -63,68 +60,45 @@ console.log( `check-client-bundle: ${files.length} client files, no Settings, Design mode, device preview or server-only code`, ) -// Each page's budget in kB, gzipped: what it was when last measured, plus a kB of room. Lower a -// budget when a page gets lighter; a page without one fails until it has one. -const budgets: Record = { - "static pages": 11.3, - "[...404].tsx": 104.3, - "devices.tsx": 57.1, - "font/index.tsx": 119, - "video-editor/index.tsx": 55.5, -} +// Production hydrates no page (src/static/render.tsx): every page loads the static pages' one script +// (src/client/entry.ts, script/static-client.ts), whose islands and overlays load later. The app's +// browser build is there for its stylesheets only, so none of its scripts may ship, and the script +// may bring no router, no serialized data (seroval) and no hydration. Its budget in kB, gzipped, is +// what it was when last measured, plus a kB of room; lower it when the script gets lighter. +const budget = 11.6 type Chunk = { file: string; imports?: string[] } -const manifest: Record = await Bun.file(path.join(root, ".vite/manifest.json")).json() -const sizes = new Map() -const gzipped = async (file: string) => { - const known = sizes.get(file) - if (known !== undefined) return known - const size = Bun.gzipSync(await Bun.file(path.join(root, file)).bytes(), { level: 9 }).length - sizes.set(file, size) - return size -} -const closure = (key: string, seen = new Set()): Set => { - if (seen.has(key)) return seen - seen.add(key) - manifest[key].imports?.forEach((next) => closure(next, seen)) - return seen -} -const entry = closure("src/entry-client.tsx") -const kB = async (keys: Iterable) => - Math.round( - (await Promise.all([...keys].map((key) => gzipped(manifest[key].file)))).reduce((a, b) => a + b, 0) / 100, - ) / 10 -// The static pages' script, from its own build (script/static-client.ts): one file, whose islands and -// overlays load later. +const app: Record = await Bun.file(path.join(root, ".vite/manifest.json")).json() const statics: Record = await Bun.file(path.join(root, ".vite/static-manifest.json")).json() +const own = new Set(Object.values(statics).map((chunk) => chunk.file)) +const shipped = ( + await Promise.all( + Object.values(app) + .filter((chunk) => /\.m?js$/.test(chunk.file) && !own.has(chunk.file)) + .map(async (chunk) => ((await Bun.file(path.join(root, chunk.file)).exists()) ? [chunk.file] : [])), + ) +).flat() +if (shipped.length) { + console.error(`check-client-bundle: the app's scripts ship, though no page loads them:\n ${shipped.join("\n ")}`) + process.exit(1) +} const script = statics["src/client/entry.ts"] if (script.imports?.length) { console.error(`check-client-bundle: the static pages' script imports ${script.imports.join(", ")}; keep it one file`) process.exit(1) } -const staticScript = Math.round((await gzipped(script.file)) / 100) / 10 -const pages = await Promise.all( - Object.keys(manifest) - .filter((key) => key.startsWith("src/routes/") && key.includes("?pick=default")) - .map(async (key) => { - const route = key.slice("src/routes/".length).split("?")[0] - // The route file's address: brand/index.tsx is /brand, changelog/[tag].tsx is /changelog/:tag. - const address = `/${route.replace(/(^|\/)index\.tsx$|\.tsx$/, "").replace(/\[([^\]]+)\]/g, ":$1")}` - if (staticPath(address) === address) return { route, kB: staticScript, budget: budgets["static pages"] } - return { route, kB: await kB(new Set([...entry, ...closure(key)])), budget: budgets[route] } - }), -) -const over = pages.filter((page) => !(page.kB <= page.budget)) -if (over.length) { - console.error( - "check-client-bundle: initial JavaScript (gzipped) over its page's budget:\n " + - over.map((page) => `${page.route}: ${page.kB} kB, budget ${page.budget ?? "none"}`).join("\n "), - ) +const bytes = await Bun.file(path.join(root, script.file)).bytes() +const text = new TextDecoder().decode(bytes) +// As they survive minification: the router's scroll key, seroval's errors, hydration's global. +const brought = ["solid-router", "Seroval", "_$HY"].filter((marker) => text.includes(marker)) +if (brought.length) { + console.error(`check-client-bundle: the static pages' script brings ${brought.join(", ")}`) + process.exit(1) +} +const kB = Math.round(Bun.gzipSync(bytes, { level: 9 }).length / 100) / 10 +if (!(kB <= budget)) { + console.error(`check-client-bundle: the static pages' script is ${kB} kB gzipped, over its budget of ${budget} kB`) process.exit(1) } console.log( - "check-client-bundle: initial JavaScript within budget (kB gzipped): " + - pages - .toSorted((a, b) => b.kB - a.kB) - .map((page) => `${page.route} ${page.kB}`) - .join(", "), + `check-client-bundle: the app ships no scripts; the static pages' script is ${kB} kB gzipped (budget ${budget})`, ) diff --git a/services/site/script/check-worker-start.ts b/services/site/script/check-worker-start.ts index 3d53fed0e2a..492968d4cde 100644 --- a/services/site/script/check-worker-start.ts +++ b/services/site/script/check-worker-start.ts @@ -21,8 +21,9 @@ const root = path.resolve(import.meta.dir, "..") // Markdown twin, src/docs/middleware.ts). The docs' old /v2 address and a V1 docs path redirect. The // last three are files the Worker serves, or the assets layer before it (_headers). Every answer // carries the stage's headers (src/lib/noindex.ts): dev's noindex, none in production. The V1 docs' -// pages are noindex in both. The static pages (src/static/routes.ts) must come back as plain HTML: no -// hydration keys, no serialized data, and their own script rather than the app's. +// pages are noindex in both. Every page must come back as plain HTML (src/static/render.tsx): no +// hydration keys or markers, no serialized data, and one module script, the static pages' own; the +// not-found page too, in any language, and for the development tools' addresses (/devices). const pages: { path: string status?: number @@ -40,7 +41,10 @@ const pages: { { path: "/ja", status: 200, static: true }, { path: "/desktop", status: 200, static: true }, { path: "/ar/product", status: 200, static: true }, - { path: "/check-worker-start-404", status: 404 }, + { path: "/font", status: 200, static: true }, + { path: "/check-worker-start-404", status: 404, static: true }, + { path: "/ja/check-worker-start-404", status: 404, static: true }, + { path: "/devices", status: 404, static: true }, { path: "/docs/", status: 200 }, { path: "/docs/config/", status: 200, accept: "text/markdown" }, { path: "/v2/docs/config/", status: 301, location: "/docs/config/" }, @@ -125,8 +129,10 @@ const results = await Promise.resolve() status: response.status, location: response.headers.get("location") ?? undefined, robots: response.headers.get("x-robots-tag") ?? undefined, - hydrated: /data-hk=|_\$HY|\$R\[|entry-client-/.test(body), - scripted: /