From 06b242e5599fba9d063c13c29af6b52043f0881f Mon Sep 17 00:00:00 2001 From: adamXbot <111877622+adamXbot@users.noreply.github.com> Date: Tue, 10 Nov 2026 21:04:43 +1100 Subject: [PATCH 1/3] Serve fxcss.com as static pages Build every page to a file and publish only those files, so no site code runs per request. Security headers move to public/_headers, old addresses to public/_redirects, and /docs?path= is now read in the browser. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/website.yml | 2 +- .gitignore | 1 + DEPLOYMENT.md | 12 ++++--- README.md | 15 ++++---- app/[sample]/page.tsx | 7 ---- app/components/getting-started.tsx | 23 +++++++++--- app/docs/[slug]/page.tsx | 4 +++ app/docs/page.tsx | 10 ++---- app/layout.tsx | 19 ++++------ app/open/page.tsx | 18 +++++----- app/robots.txt/route.ts | 9 ----- app/sitemap.xml/route.ts | 21 ----------- justfile | 29 +++++++-------- next.config.ts | 2 ++ package-lock.json | 23 ------------ package.json | 7 ++-- proxy.ts | 55 ---------------------------- public/.assetsignore | 6 ++-- public/_headers | 22 ++++++++---- public/_redirects | 4 +++ public/robots.txt | 3 ++ scripts/build-content.mjs | 14 +++++++- scripts/check-built-site.sh | 2 +- scripts/check-site.mjs | 43 ++++++++++++++++------ tests/browser/site.spec.ts | 26 ++++++++++++++ tests/site.test.mjs | 58 +++++++++++++++--------------- vite.config.ts | 52 ++++----------------------- wrangler.static.jsonc | 24 +++++++++++++ 28 files changed, 229 insertions(+), 282 deletions(-) delete mode 100644 app/[sample]/page.tsx delete mode 100644 app/robots.txt/route.ts delete mode 100644 app/sitemap.xml/route.ts delete mode 100644 proxy.ts create mode 100644 public/_redirects create mode 100644 public/robots.txt create mode 100644 wrangler.static.jsonc diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml index 30c1b3b..0584be4 100644 --- a/.github/workflows/website.yml +++ b/.github/workflows/website.yml @@ -51,7 +51,7 @@ jobs: - run: npm run test:installer - run: npm run check:audit - run: npm run build - - name: Dry-run the Cloudflare Worker deploy + - name: Dry-run the Cloudflare deploy env: WRANGLER_SEND_METRICS: 'false' run: npm run deploy -- --dry-run diff --git a/.gitignore b/.gitignore index 4ae4c22..8e555e9 100644 --- a/.gitignore +++ b/.gitignore @@ -36,6 +36,7 @@ next-env.d.ts /.wrangler/ /outputs/ /work/ +/public/sitemap.xml # Source assets and TypeScript cache !/public/assets/*.png diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index cf2a43a..2f9b4be 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -4,9 +4,11 @@ The source and production build are prepared for `https://fxcss.com`. They include the interactive shell installer at `/install.sh`, canonical page URLs, `/sitemap.xml`, and `/robots.txt`. The installer is a public static asset with a plain-text content type, revalidation on every request, and no sign-in requirement in the application. -The site runs as a Cloudflare Worker named `fxcss-website`. `vite.config.ts` holds its configuration (the name, the compatibility date and Workers Logs), and the `deploy` script in `package.json` attaches the `fxcss.com` and `www.fxcss.com` custom domains. Only those domains answer: the config sets `workers_dev` and `preview_urls` to false, so there is no `workers.dev` or preview URL outside the zone's WAF, HSTS and Access, and a dashboard-only switch would be undone by the next deploy. `public/.assetsignore` lists what wrangler must never upload as a static file (Finder's `.DS_Store`, `.env*` files, the wrangler config, repository metadata); the build prepends it to `dist/client/.assetsignore`, which wrangler reads. Never list `.well-known/` there: `security.txt` stays public. It has no database, storage or secrets. `npm run build` writes the Worker (`dist/server/index.js`), its static files (`dist/client/`) and the generated `dist/server/wrangler.json`, and `npm run deploy` publishes them. Don't edit the generated file; change `vite.config.ts` and rebuild. +The site is a set of static files served by Cloudflare under the Worker name `fxcss-website`. No site code runs per request: `npm run build` writes every page to `dist/client/` as HTML, and each page's data for in-browser navigation as a matching `.txt` file. `wrangler.static.jsonc` holds the configuration, with no `main` script on purpose, and the `deploy` script in `package.json` attaches the `fxcss.com` and `www.fxcss.com` custom domains. Keep the config's name: vinext reads a file called `wrangler.jsonc` as a Worker build and refuses to run without Cloudflare's build plugin. Only the custom domains answer: the config sets `workers_dev` and `preview_urls` to false, so there is no `workers.dev` or preview URL outside the zone's WAF, HSTS and Access, and a dashboard-only switch would be undone by the next deploy. `public/.assetsignore` lists what wrangler must never upload as a static file (Finder's `.DS_Store`, `.env*` files, the wrangler config, repository metadata). Never list `.well-known/` there: `security.txt` stays public. The site has no database, storage or secrets. -The application configuration is the source of truth for the Worker and its custom domains. Verify the current deployment and DNS with the checks below; a repository checkout does not establish their live state. +The redirects for old addresses are in `public/_redirects`, and every security header is in `public/_headers`. A page can't read the request, so a feature that needs per-request data doesn't fit this setup: `/docs?path=` is read in the browser for that reason. + +The application configuration is the source of truth for the site and its custom domains. Verify the current deployment and DNS with the checks below; a repository checkout does not establish their live state. ## Launch sequence @@ -43,7 +45,7 @@ The site deploys from this `website` branch. From a fresh clone (`git clone --br - build command `npm ci && npm run build`; - deploy command `npm run deploy`. -4. Turn on two zone settings. The Worker's `proxy.ts` sends plain HTTP and `www` page requests to `https://fxcss.com`, but static files such as `/install.sh` are served before the Worker runs, so the zone has to cover them: +4. Turn on two zone settings. Nothing in the site redirects plain HTTP or `www`, so without these `www.fxcss.com` serves a duplicate copy of the site: - **SSL/TLS → Edge Certificates → Always Use HTTPS.** - A redirect rule from `www.fxcss.com/*` to `https://fxcss.com/${1}`, keeping the query string. In the dashboard: Rules → Redirect Rules, with the "Redirect from WWW to root" template. @@ -73,6 +75,6 @@ On macOS, missing pipx is installed through an existing Homebrew installation. O ## Caching policy -HTML deliberately sends `private, no-store`: every render has a fresh CSP script nonce, which must agree with the response policy. Keep that policy when changing page delivery. A hash-based policy would require separate validation of framework-generated inline scripts; it is not needed to cache static files. +HTML uses Cloudflare's default for static files, `public, max-age=0, must-revalidate`, so a deploy reaches readers on their next page load. Pages are the same bytes for everyone, so they can't carry a per-request script nonce. The Content Security Policy in `public/_headers` allows inline scripts, which the framework's page data needs, and limits where scripts can load from. -`public/_headers` gives content-hashed `/_next/static/*` chunks and `/search/*` indexes one year of immutable caching. Unversioned images, media, evidence and catalogue files get a one-hour browser cache. The installer still revalidates on every request. `scripts/check-site.mjs` checks these headers against the built Worker; verify them again at the live edge after deployment because zone rules can override them. +`public/_headers` gives content-hashed `/_next/static/*` chunks and `/search/*` indexes one year of immutable caching. Unversioned images, media, evidence and catalogue files get a one-hour browser cache, as do `robots.txt` and `sitemap.xml`. The installer still revalidates on every request. `scripts/check-site.mjs` checks these headers against the built site; verify them again at the live edge after deployment because zone rules can override them. diff --git a/README.md b/README.md index b317b55..98d6ee5 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # fxcss website -The Showcase homepage and Field guide documentation for https://fxcss.com. The application is built with vinext (the Next.js App Router on Vite) and runs as a Cloudflare Worker. +The Showcase homepage and Field guide documentation for https://fxcss.com. The application is built with vinext (the Next.js App Router on Vite) and exported as static files that Cloudflare serves. This is the `website` branch of [AdamXweb/fxcss](https://github.com/AdamXweb/fxcss). fxcss itself, and the README the documentation is generated from, live on `main`. The two share no files: website changes go to pull requests against `website`, toolkit changes against `main`. @@ -13,14 +13,13 @@ This is the `website` branch of [AdamXweb/fxcss](https://github.com/AdamXweb/fxc | `just setup` | Install the locked dependencies (Node.js 22.18 or newer). | | `just dev` | Development server on http://127.0.0.1:4317. | | `just check` | What Website CI checks before building: docs, types, lint, tests, the installer, and the dependency audit. | -| `just build` | Build the Worker into `dist/`. | -| `just preview` | Serve the built Worker on http://127.0.0.1:4318, under the production runtime. | +| `just build` | Build every page into `dist/client/`. | +| `just preview` | Serve the built site on http://127.0.0.1:4318, under the production runtime. | | `just verify [url]` | Check every page, asset, redirect and security header of a running site; `just verify https://fxcss.com` checks the live one. | | `just dry-run` | Check the deploy without uploading anything or signing in. | | `just login` | Sign in to Cloudflare with wrangler. | -| `just deploy` | Upload the Worker and attach `fxcss.com` and `www.fxcss.com`. | +| `just deploy` | Upload the built site and attach `fxcss.com` and `www.fxcss.com`. | | `just first-deploy` | `check`, `build`, `dry-run` and `deploy` in order, then the two zone settings to turn on. | -| `just tail` | Stream the deployed Worker's logs. | | `just content ../fxcss` | Refresh the documentation from a checkout of `main`. | | `just refresh` | Run the Refresh docs workflow on GitHub: regenerate from `main`, check, push here. | | `just evidence ../fxcss` | Recapture the comparison screenshots with fxcss (opens Firefox windows). | @@ -55,7 +54,7 @@ just verify vinext 1.0.1 includes `@vercel/og` 1.0.3 with the Satori SVG-escaping fix and the framework's HarfBuzz runtime support. The `satori` override pins `fflate` 0.7.5 to fix its ZIP64 parsing advisory while Satori pins 0.7.3; remove that override once Satori uses a patched release. The `@ts-morph/common` override moves `minimatch` to 11.0.3 for its globparts denial-of-service advisory; it is reached only through the `shadcn` CLI (via `ts-morph`), whose newest release still asks for `minimatch` 10, which has no patched version. Remove it once `@ts-morph/common` depends on `minimatch` 11. The lockfile also keeps `@hono/node-server` and `systeminformation` on patched versions within their existing dependency ranges. -The Website GitHub Actions workflow (`.github/workflows/website.yml`) runs the same checks, plus a deploy dry run, on every pull request and push to `website`, without deploying. Pull requests stacked on `fix/website-*` branches also run these checks. A second job warns when the recorded documentation is behind `main`. The production check visits every documentation page, validates asset responses and the security headers on pages, redirects and static files, checks raw-head metadata and share cards, checks that each labelled control's name contains its visible text, and verifies not-found responses and redirects. On Node 24, CI also runs the Playwright Chromium and Firefox suite (`npm run test:browser`) against the built Worker. It covers journey selection, game completion, search loading and recovery, route announcements, code copying, keyboard-operated comparison controls, catalogue toggles, mobile Escape handling, logo picking and its report card, sidebar search sizing and scrolling, narrow layouts, and the reported catalogue and retro contrast regressions. The main checks also run on the declared minimum Node 22.18.0. For local browser checks, run `npx playwright install chromium firefox`, `npm run build`, then `npm run test:browser`; Playwright starts and stops its own local Worker and blocks outside requests. These checks do not replace testing with screen readers or native browser zoom. +The Website GitHub Actions workflow (`.github/workflows/website.yml`) runs the same checks, plus a deploy dry run, on every pull request and push to `website`, without deploying. Pull requests stacked on `fix/website-*` branches also run these checks. A second job warns when the recorded documentation is behind `main`. The production check visits every documentation page, validates asset responses and the security headers on pages, redirects and static files, checks raw-head metadata and share cards, checks that each labelled control's name contains its visible text, and verifies not-found responses and redirects. On Node 24, CI also runs the Playwright Chromium and Firefox suite (`npm run test:browser`) against the built site. It covers journey selection, game completion, search loading and recovery, route announcements, code copying, keyboard-operated comparison controls, catalogue toggles, mobile Escape handling, logo picking and its report card, sidebar search sizing and scrolling, narrow layouts, and the reported catalogue and retro contrast regressions. The main checks also run on the declared minimum Node 22.18.0. For local browser checks, run `npx playwright install chromium firefox`, `npm run build`, then `npm run test:browser`; Playwright starts and stops its own local Worker and blocks outside requests. These checks do not replace testing with screen readers or native browser zoom. To run only Firefox, use `npm run test:browser -- --project=firefox`. If the bundled Firefox fails to start on macOS 27 with “Could not find profile folder”, give the test browser separate application data directories ([upstream issue](https://github.com/microsoft/playwright/issues/42768)): @@ -82,7 +81,7 @@ just content ../fxcss That sets `FXCSS_SOURCE` for `scripts/build-content.mjs`, which also copies `docs/icon.png`. Website CI compares the recorded copy with `main` on every run and warns when it is behind. The website's getting-started overview remains deliberately short and links to the full generated guides. -`app/components/` contains the shared navigation, documentation controls, comparison, and copy controls. `app/docs/[slug]/page.tsx` renders the generated pages. `proxy.ts` supplies a fresh Content Security Policy nonce and security headers for each production application response. `public/_headers` gives static files the same headers, and the static catalogue its own policy. `lib/share-card.ts` gives every page the share image, `public/assets/og-card.png`. There are no accounts, forms, remote fonts, or site databases. +`app/components/` contains the shared navigation, documentation controls, comparison, and copy controls. `app/docs/[slug]/page.tsx` renders the generated pages. `public/_headers` gives every page and file its security headers, and the static catalogue its own policy. `public/_redirects` keeps old addresses working. `lib/share-card.ts` gives every page the share image, `public/assets/og-card.png`. There are no accounts, forms, remote fonts, or site databases. The transparent vector logo is `public/assets/fxcss-logo.svg`. `app/components/brand-mark.tsx` reuses its named `fxcss-flames` and `fxcss-braces` groups, so the downloadable artwork and the website share one source. `app/components/brand-link.tsx` starts one flame spin on pointer entry or keyboard focus and lets it finish even when the pointer or focus leaves. Re-entry during a spin does not restart it. CSS in `app/globals.css` keeps the cyan braces glowing through the spin, then fades the glow if the link is no longer hovered or focused; the braces and wordmark stay upright. The spin is disabled when reduced motion is requested. Serve the SVG from the same origin when reusing the interactive component; a regular `` displays the static artwork. @@ -121,6 +120,6 @@ The film is rendered from an HTML source outside this repository. Its on-screen The site is prepared for **https://fxcss.com**. `/install.sh` serves the interactive installer directly as plain text. Canonical URLs, the sitemap, and setup examples use that domain. Publish the matching package metadata when the domain is live. See [DEPLOYMENT.md](DEPLOYMENT.md) for the launch, the Cloudflare zone settings and deploying on every push. -The site runs as the Cloudflare Worker `fxcss-website`, configured in `vite.config.ts`; the `deploy` script attaches the `fxcss.com` and `www.fxcss.com` custom domains. `npm run build` writes `dist/server/index.js`, `dist/client/` and the generated `dist/server/wrangler.json`, and `npm run deploy` publishes them. Production scripts require the generated Worker configuration. The public installer must work without a browser session or a sign-in redirect. Do not serve the development server publicly. +The site is served as static files under the Worker name `fxcss-website`, configured in `wrangler.static.jsonc`; the `deploy` script attaches the `fxcss.com` and `www.fxcss.com` custom domains. `npm run build` writes every page to `dist/client/`, and `npm run deploy` publishes that folder. No site code runs per request. The public installer must work without a browser session or a sign-in redirect. Do not serve the development server publicly. The tab favicon uses the existing lightweight SVG, independently of the recorded source icon. After each catalogue recapture, `scripts/prepare_catalogue.py` applies the website's document structure, language, landmarks, toggle semantics and contrast fixes without changing captured images. It fails if the toolkit's generated structure has changed unexpectedly. The captured directory is an auxiliary reference marked `noindex,follow`; `/docs/catalogue` remains its indexable documentation page. diff --git a/app/[sample]/page.tsx b/app/[sample]/page.tsx deleted file mode 100644 index 5773155..0000000 --- a/app/[sample]/page.tsx +++ /dev/null @@ -1,7 +0,0 @@ -import { notFound, permanentRedirect } from "next/navigation"; -export default async function LegacyPage({ params }: { params: Promise<{ sample: string }> }) { - const { sample } = await params; - if (sample === "field-guide") permanentRedirect("/docs"); - if (["showcase", "workbench", "editorial"].includes(sample)) permanentRedirect("/"); - notFound(); -} diff --git a/app/components/getting-started.tsx b/app/components/getting-started.tsx index 2c90918..6b866a5 100644 --- a/app/components/getting-started.tsx +++ b/app/components/getting-started.tsx @@ -1,6 +1,7 @@ 'use client'; -import { useState } from 'react'; +import { Suspense, useEffect, useState } from 'react'; import Link from 'next/link'; +import { useSearchParams } from 'next/navigation'; import { ArrowRight, Check, CodeXml, ShieldCheck } from 'lucide-react'; import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/components/ui/tabs'; import { CopyCommand } from './copy-command'; @@ -70,12 +71,21 @@ function InstallStep({ journey }: { journey: Journey }) { ); } -export function GettingStarted({ - initialJourney = 'use', +// The page is built ahead of time with no address to read, so the browser picks +// the tab named by ?path= once it is running. +function JourneyFromAddress({ + onJourney, }: { - initialJourney?: Journey; + onJourney: (journey: Journey) => void; }) { - const [journey, setJourney] = useState(initialJourney); + const path = useSearchParams().get('path'); + useEffect(() => { + onJourney(path === 'build' || path === 'maintain' ? path : 'use'); + }, [path, onJourney]); + return null; +} +export function GettingStarted() { + const [journey, setJourney] = useState('use'); function selectJourney(value: string) { if (value !== 'use' && value !== 'build' && value !== 'maintain') return; setJourney(value); @@ -87,6 +97,9 @@ export function GettingStarted({ } return ( <> + + +
Documentation / Start here
diff --git a/app/docs/[slug]/page.tsx b/app/docs/[slug]/page.tsx index b988dde..c2e4568 100644 --- a/app/docs/[slug]/page.tsx +++ b/app/docs/[slug]/page.tsx @@ -6,6 +6,10 @@ import content from "../../../content/docs.json"; import { DocArticle } from "../../components/doc-article"; import { Comparison, AppearancePreview } from "../../components/comparison"; import { shareCard } from "../../../lib/share-card"; +export const dynamicParams = false; +export function generateStaticParams() { + return content.pages.map((page) => ({ slug: page.slug })); +} export async function generateMetadata({ params, }: { diff --git a/app/docs/page.tsx b/app/docs/page.tsx index 2179c16..3e7c6ea 100644 --- a/app/docs/page.tsx +++ b/app/docs/page.tsx @@ -8,16 +8,10 @@ export const metadata: Metadata = { description: 'Install fxcss and start trying, building, or maintaining Firefox themes.', }; -export default async function Documentation({ - searchParams, -}: { - searchParams: Promise<{ path?: string }>; -}) { - const { path } = await searchParams; - const initialJourney = path === 'build' || path === 'maintain' ? path : 'use'; +export default function Documentation() { return (
- +
); } diff --git a/app/layout.tsx b/app/layout.tsx index bb1b1d4..8514aa9 100644 --- a/app/layout.tsx +++ b/app/layout.tsx @@ -1,6 +1,4 @@ import type { Metadata } from "next"; -import { headers } from "next/headers"; -import { CSPProvider } from "@base-ui/react/csp-provider"; import { OutboundClickTracking } from "./components/outbound-click-tracking"; import { EasterEggs } from "./components/easter-eggs"; import { SleepyFavicon } from "./components/sleepy-favicon"; @@ -26,26 +24,21 @@ export const metadata: Metadata = { description: "Make Firefox your own. Try themes, edit CSS live, and keep every detail working.", }), }; -export default async function RootLayout({ children }: { children: React.ReactNode }) { - const policy = (await headers()).get("content-security-policy"); - const nonce = policy?.match(/'nonce-([^']+)'/)?.[1]; +export default function RootLayout({ children }: { children: React.ReactNode }) { return ( Skip to content - - - - - {children} - - + + + + {children} +