snappy-prerender 2.6.0 → 2.8.0

package/docs/limitations.md

@@ -0,0 +1,94 @@
+# Limitations
+
+- **Build-time data is a snapshot.** Anything fetched during rendering is frozen into the
+  HTML until the next build. Use `cacheAjaxRequests` and `snapSaveState` so the client
+  replays the same data.
+- **Hydration mismatches are your app's to fix.** The verifier tells you exactly which route
+  and which framework error. Common causes: `Date.now()`, `Math.random()`, `localStorage`
+  reads during render, viewport-dependent markup, and CSS-in-JS that re-injects styles on
+  hydration. Use `freezeTime` and `randomSeed` for deterministic build-time values, and
+  `hydration.allowRerender`/`skip` for genuinely live routes. A fixed clock is a build and
+  verification control only; production still uses real time. `performance.now()` is not
+  frozen because schedulers rely on it, and `crypto.randomUUID()` is not patched.
+- **Markup that depends on load state cannot hydrate.** A component that swaps a placeholder
+  for real content once an image or widget loads renders one thing during prerendering
+  (where the network has settled) and another on the client's first render. The verifier
+  reports those routes as `re-rendered`. Render deterministic markup instead — a plain
+  `<img loading="lazy">` rather than a JS placeholder swap — or accept the re-render.
+- **Authenticated routes need `storageState`.** Never prerender personal data into static
+  HTML without deciding to.
+- **Path locale prefixes need app routing.** `locales.mode: 'path'` renders `/fr/...` pages,
+  but the app still has to route that prefix or use translated `routes`. The prerenderer
+  cannot rewrite the client router. Path mode expects one public origin; use single mode
+  for separate locale domains.
+- **Hreflang needs distinct URLs.** A locale selected only by cookie or `localStorage` is
+  not a crawlable alternate URL. Use path prefixes, subdomains or separate deployments.
+- **`seoLocale` does not create new URLs.** In single mode it produces one locale per
+  output. It seeds the prerender/verification browser and optionally writes a bootstrap,
+  but it does not create multiple locale URLs. `inject: false` localizes the HTML without
+  forcing the visitor's stored locale.
+- **`forceHtmlLang` overrides app metadata.** Use it only when the app hardcodes a language
+  that disagrees with the SEO locale.
+- **Runtime-only routes** (heavy API dependence, real-time data) are better served by
+  `serveCmd` or left client-rendered.
+- Route query strings are ignored; routes are deduplicated without them.
+- Routes whose decoded path contains dot segments or backslashes are skipped, so encoded
+  traversal cannot create stray directories.
+- Crawling is unbounded unless `maxRoutes` is set; hitting the cap marks the run as failed
+  so incomplete output is never shipped silently. With `maxRoutes` or `routePriority`, the
+  crawl runs in deterministic waves and reports exactly which routes did not fit in
+  `truncated.droppedRoutes`.
+- **React 19 native metadata.** React hoists `<title>`, `<meta>` and `<link>` rendered in
+  JSX. `Head` adopts a matching hoisted `<meta>` or `<link>` and updates it. A hoisted
+  `<title>` that already carries the Head text is left to React (so React can remove it on
+  navigation) and older template titles are removed. `titleAttributes` apply only when
+  `Head` owns the title. An app should still use one owner per tag: either native React 19
+  metadata or `Head`. The run warns when a page ships more than one `<title>`.
+- **`Head` is client-side only.** It manages the live document head while the app runs and
+  the prerenderer captures the result. It does not provide `HelmetProvider`,
+  `helmetContext`, `HelmetData`, `renderStatic()`, streaming head extraction or a
+  server-rendering API. A server-rendered app still needs React 19 native metadata or a
+  server head manager.
+- **`tags` and `noscript.html` are trusted input.** Script and style text is escaped so it
+  cannot close its own element, but a `noscript` value is written as inner HTML exactly as
+  supplied. Never pass user-generated content there.
+- **Attributes belong to the mounted `Head`.** html, body and title attributes are restored
+  when no Head wants them, including after client navigation and prerendered hydration. A
+  value written outside the head layer while a Head owns the same attribute is overwritten
+  on the next render.
+- If two routes would write the same file — such as `/` and `/index` with `flatOutput` —
+  neither is written and the run fails with a collision error.
+- Screenshots are viewport-width full-page captures, so they reflect the configured
+  `viewport`, not a device matrix. Identical screenshots are left untouched.
+- **Output files from routes that no longer exist** are left in place unless
+  `pruneStaleRoutes` is enabled, which deletes only files listed in the previous run's
+  `.snappy-manifest.json`.
+- **Dead extensionless links** are indistinguishable from SPA routes to the static server,
+  so a missing page can render the shell or the app's catch-all 404. Duplicate output is
+  reported; set `failOnDuplicateContent` to enforce it, and use an app-level 404 marker
+  where possible.
+- **Metadata pointing at the build server** is removed by default
+  (`stripBuildOriginMetadata: true`) and reported. Set `metadata.siteUrl` so canonical and
+  social URLs survive.
+- **`inlineCss`** rebases relative font and image URLs against each stylesheet. A sheet that
+  uses `@import` is left as a link because concatenating it would change the cascade.
+- **`verifyChangedOnly` compares the generated HTML only.** If a bundle keeps the same
+  filename while its contents change, that route's HTML is unchanged and its verification
+  is skipped; content-hashed asset names (Vite and CRA defaults) make the HTML change as
+  well.
+- **Destination directories are merged unless `cleanDestination` is on.** That option
+  empties the destination first; `pruneStaleRoutes` separately removes pages the run itself
+  generated.
+- **`removeStyleTags`** cannot be combined with `inlineCss: 'inline'` or `true`; the config
+  is rejected instead of silently shipping pages without CSS.
+- **CSP `hash` mode cannot cover inline event handlers or `style=""` attributes.** Move
+  those styles into a `<style>` element or a stylesheet; the audit warns when attributes are
+  present.
+- **CSP `strict` does not rewrite `Head` `tags`.** An inline script supplied through
+  `tags` is the app's own policy decision; give it a `nonce` the host policy allows or
+  externalise it with `src`. The package only externalises its own captured state and SEO
+  locale bootstrap.
+- **`reuseVerificationContext` shares browser storage between routes.** Use it only for
+  stateless apps; authenticated routes can see cookies or storage from another route.
+- **Failure traces can contain request data.** `traceOnError` is opt-in and writes a
+  Playwright archive under `snappy-traces/` in the output directory.

package/docs/react-snap-migration.md

@@ -0,0 +1,45 @@
+# Migrating from react-snap
+
+`snappy-prerender init` reads a `reactSnap` block from `package.json` and uses it as the
+wizard's defaults, so an existing project can move without retyping its settings. The
+migration table is printed after the config is written, together with any ignored or
+unknown keys.
+
+## Option mapping
+
+| react-snap | snappy-prerender |
+| --- | --- |
+| `source` | `sourceDir` |
+| `puppeteerArgs` | `browserArgs` |
+| `puppeteerIgnoreHTTPSErrors` | `ignoreHTTPSErrors` |
+| `skipThirdPartyRequests` | `blockThirdParty` |
+| `fixInsertRule` | `captureRuntimeStyles` |
+| `fixFormFields` | `captureFormState` |
+| `http2PushManifest` | `preloadManifest` |
+
+These keep their name: `include`, `exclude`, `crawl`, `concurrency`, `timeout`, `waitFor`,
+`inlineCss`, `minifyHtml`, `minifyCss`, `cacheAjaxRequests`, `preconnectThirdParty`,
+`preloadImages`, `removeBlobs`, `removeStyleTags`, `removeScriptTags`, `asyncScriptTags`,
+`userAgent`, `viewport`, `saveAs`, `destination`.
+
+Ignored, with a printed explanation: `port` (the prerenderer serves the build itself on an
+ephemeral loopback port) and `sourceMaps` (declared by react-snap but never read).
+
+## Other differences
+
+Kept: crawling, include, concurrency, viewport, waitFor, executable path, external server,
+third-party skipping (now on by default), `userAgent`, `inlineCss`, `minifyHtml`,
+`minifyCss`, `cacheAjaxRequests`, `snapSaveState`, `preconnectThirdParty`, `preloadImages`,
+`removeBlobs`, `removeStyleTags`, `removeScriptTags`, `asyncScriptTags`, `destination`,
+`saveAs` (html/png/jpeg).
+
+Changed: `http2PushManifest` became `preloadManifest` (browsers removed HTTP/2 push),
+`fixInsertRule` became `captureRuntimeStyles` and also covers constructable stylesheets,
+`fixFormFields` became `captureFormState`, `puppeteerArgs` became `browserArgs`,
+`puppeteerIgnoreHTTPSErrors` became `ignoreHTTPSErrors`, `skipThirdPartyRequests` became
+`blockThirdParty` with the same default of allowing them, `exclude` and `maxRoutes` are
+new, and `notFoundRoute` replaces the `/404` include convention.
+
+Dropped: `sourceMaps`, `fixWebpackChunksIssue` and `fixInsertRule` (webpack/Chrome-era
+workarounds), `port`, `puppeteer.cache`, and the preload polyfill (modulepreload is
+universally supported).

package/docs/report.md

@@ -0,0 +1,135 @@
+# Report and audit
+
+`reportPath` (CLI `--report <file>`) writes a versioned JSON document after the run. The
+file is written through a temporary file, so a reader never sees a partial report, and it
+is skipped in `--dry-run`.
+
+```json
+{
+  "version": 1,
+  "generatedAt": "2026-10-28T00:00:00.000Z",
+  "durationMs": 0,
+  "timings": { "render": 0, "write": 0, "artifacts": 0, "verify": 0, "audit": 0 },
+  "ok": true,
+  "clock": { "fixedTime": 0, "timezone": "UTC" },
+  "locales": {
+    "mode": "path",
+    "default": "en",
+    "active": null,
+    "rendered": { "en": 0, "fr": 0 }
+  },
+  "seoLocale": {
+    "code": "fr",
+    "source": "both",
+    "inject": true,
+    "script": "snappy-seo-locale-abc123.js",
+    "scripts": ["snappy-seo-locale-abc123.js"]
+  },
+  "summary": { "routes": 0, "files": 0, "errors": 0, "warnings": 0 },
+  "verification": {
+    "ok": true,
+    "modes": { "hydrated": 0, "re-rendered": 0, "undetected": 0, "unknown": 0 },
+    "frameworks": { "react": 0 },
+    "skipped": 0,
+    "policySkipped": 0,
+    "allowed": 0,
+    "allowedRerender": 0,
+    "errors": []
+  },
+  "routes": [
+    {
+      "route": "/",
+      "locale": "en",
+      "order": 0,
+      "file": "index.html",
+      "status": "written",
+      "bytes": 0,
+      "depth": 0,
+      "attempts": 1,
+      "httpStatus": 200,
+      "finalUrl": "http://127.0.0.1:1234/",
+      "mode": "hydrated",
+      "framework": "react",
+      "empty": false,
+      "notFound": false,
+      "noindex": false,
+      "meta": {
+        "title": "",
+        "description": "",
+        "canonical": "",
+        "robots": "",
+        "lang": "en",
+        "dir": null,
+        "ogLocale": "en_US",
+        "h1Count": 1,
+        "alternates": [],
+        "localeUrl": null,
+        "images": [],
+        "inlineStyleAttributes": 0
+      },
+      "hydrationErrors": [],
+      "ignoredHydrationErrors": [],
+      "hydrationPolicy": "strict",
+      "hydrationAllowed": false,
+      "pageErrors": [],
+      "consoleErrors": [],
+      "failedRequests": [],
+      "firstMismatch": null
+    }
+  ],
+  "audit": { "errors": [], "warnings": [], "linksChecked": 0 },
+  "sitemap": null,
+  "preloadManifest": null,
+  "truncated": null,
+  "notFoundRoutes": [],
+  "duplicateOutputs": [],
+  "routeSources": [],
+  "cspSkipped": [],
+  "traces": []
+}
+```
+
+The document never includes the full configuration, `storageState`, captured AJAX state,
+cookies, tokens, request bodies or full asset URLs containing credentials. It does include
+non-secret summaries of the fixed clock, locale mode and SEO locale source. URLs in the JSON
+are reduced to their origin and path, and the configured `storageState` path is redacted
+wherever it appears in a message. `order` is the crawl acceptance order; with
+`maxRoutes` or `routePriority` it follows the deterministic wave order rather than the
+alphabetical write order.
+
+## Audit rules
+
+The audit runs by default and reports findings without failing the build. Set
+`failOnAuditError: true` (CLI `--fail-on-audit-error`) to make `ok` false when an error is
+present. `auditIgnoreLinks` (CLI `--audit-ignore-links`) excludes known dynamic links.
+
+Errors:
+
+- `route-error` — a route failed while rendering, or its output could not be written.
+- `route-cap` — `maxRoutes` stopped the crawl before every discovered route was accepted.
+- `empty-page` — a route rendered no app content.
+- `duplicate-output` — two routes produced byte-identical HTML.
+- `broken-internal-link` — an internal link with no written route or output file.
+- `duplicate-title` — two routes share a title.
+- `multiple-titles` — a page ships more than one document `<title>`.
+- `hreflang-invalid` — an alternate has an invalid language code.
+- `hreflang-duplicate` — the same hreflang appears more than once on a page.
+- `hreflang-missing-return` — same-build alternates do not link back to each other.
+- `sitemap-missing-page` — an indexable page is absent from the sitemap.
+- `sitemap-unknown-page` — the sitemap lists a URL with no indexable page.
+- `sitemap-noindex-page` — the sitemap lists a noindex or 404 page.
+
+Warnings:
+
+- `missing-title`, `missing-description`, `missing-canonical`.
+- `duplicate-description`.
+- `heading-count` — zero or more than one `<h1>`.
+- `hreflang-missing-self`, `hreflang-missing-x-default`.
+- `hreflang-canonical-mismatch`, `html-lang-missing`, `html-lang-mismatch`,
+  `og-locale-missing`.
+- `canonical-mismatch` — canonical differs from the expected public URL.
+- `build-origin-metadata` — a tag still points at the build server.
+- `orphan-page` — an indexable page no written page links to.
+- `inline-style-attributes` — `csp: 'hash'` cannot cover `style=""` attributes.
+- `existing-csp-meta` — a CSP meta already existed, so hashes were not injected.
+- `csp-console-violation` — the browser reported a request blocked by the generated policy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snappy-prerender",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "Drop-in prerendering for existing single-page apps. Renders your built app in a real browser, writes static HTML per route, reports React hydration mismatches, and optimises the output with critical CSS, link hints and cached AJAX state.",
   "type": "module",
   "license": "MIT",
@@ -40,6 +40,8 @@
   },
   "files": [
     "src",
+    "assets",
+    "docs",
     "CHANGELOG.md",
     "LICENSE",
     "README.md"
@@ -50,6 +52,7 @@
   "scripts": {
     "test": "node scripts/run-tests.mjs tests/unit",
     "test:integration": "node scripts/run-tests.mjs tests/integration",
+    "benchmark": "node scripts/benchmark.mjs",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "prepublishOnly": "npm run lint && npm test && npm run test:integration"

package/src/cli-init.js

@@ -0,0 +1,205 @@
+import fs from 'node:fs';
+import { createInterface } from 'node:readline/promises';
+import { resolveConfig } from './core/config.js';
+import {
+  CONFIG_FILE,
+  configValuesFromAnswers,
+  detectProjectDefaults,
+  PACKAGE_NAME,
+  parseRouteList,
+  renderConfigFile,
+  writeConfigFile,
+} from './core/init.js';
+
+/**
+ * Setup wizard: asks for the handful of values that decide what gets prerendered and what the
+ * metadata says, then writes snappy.config.js. Flags cover every question, so
+ * `snappy-prerender init --yes --metadata-site-url https://example.com` works without a
+ * terminal.
+ */
+export async function runInit({ values, flags, log, version }) {
+  const cwd = process.cwd();
+  if (!values.force && fs.existsSync(CONFIG_FILE)) {
+    throw new Error(`${CONFIG_FILE} already exists; pass --force to replace it`);
+  }
+  if (!values.yes && !process.stdin.isTTY) {
+    throw new Error('init needs an interactive terminal; pass --yes to accept the defaults');
+  }
+
+  const detected = await detectProjectDefaults(cwd);
+  const defaults = defaultsFromFlags(detected, flags);
+  const answers = values.yes ? defaults : await askAnswers(defaults, log);
+  const cleaned = validatedAnswers(answers, log);
+  // Validate what will be written before touching an existing config file.
+  resolveConfig(configValuesFromAnswers(cleaned));
+
+  await writeConfigFile({
+    dir: cwd,
+    contents: renderConfigFile(cleaned),
+    force: values.force === true,
+  });
+  log.success(`Wrote ${CONFIG_FILE}`);
+  if (detected.reactSnap) printReactSnapMapping(detected.reactSnap, log);
+  printNextSteps({ detected, log, tag: version.includes('-') ? '@next' : '' });
+}
+
+// Turns the flags the CLI already understands into the wizard's starting answers.
+function defaultsFromFlags(detected, flags) {
+  const mapped = detected.reactSnap?.values ?? {};
+  // Options the wizard renders itself stay out of the generic list.
+  const handled = new Set(['sourceDir', 'include', 'crawl', 'csp', 'externalScripts']);
+  const extraOptions = Object.fromEntries(
+    Object.entries(mapped).filter(([key]) => !handled.has(key) && key !== 'criticalCssPreload'),
+  );
+  return {
+    ...mapped,
+    sourceDir: flags.sourceDir ?? mapped.sourceDir ?? detected.sourceDir,
+    base: flags.base ?? detected.base ?? '/',
+    include: includeList(flags.include ?? mapped.include),
+    crawl: flags.crawl ?? mapped.crawl ?? true,
+    siteUrl: flags.metadata?.siteUrl ?? '',
+    siteName: flags.metadata?.siteName ?? '',
+    titleTemplate: flags.metadata?.titleTemplate ?? '',
+    defaultImage: flags.metadata?.defaultImage ?? '',
+    trailingSlash: flags.metadata?.trailingSlash ?? '',
+    csp: flags.csp ?? 'off',
+    externalScripts: flags.externalScripts,
+    criticalCssPreload: flags.criticalCssPreload ?? mapped.criticalCssPreload,
+    extraOptions,
+  };
+}
+
+// Asks every question in order, closing the terminal interface whatever the outcome.
+async function askAnswers(defaults, log) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    log.info('A few questions, then a config file with only the options you set.');
+    return {
+      sourceDir: await ask(rl, 'Build output directory', defaults.sourceDir),
+      base: await ask(rl, 'Public base path', defaults.base),
+      include: parseRouteList(
+        await ask(rl, 'Routes to prerender, comma separated', defaults.include.join(',')),
+      ),
+      crawl: await askYesNo(rl, 'Follow same-origin links while rendering?', defaults.crawl),
+      siteUrl: await ask(
+        rl,
+        'Public site URL for canonical and og:url, blank to skip',
+        defaults.siteUrl,
+      ),
+      siteName: await ask(rl, 'Site name, blank to skip', defaults.siteName),
+      titleTemplate: await ask(
+        rl,
+        "Title template such as '%s | Example', blank to skip",
+        defaults.titleTemplate,
+      ),
+      csp: (await askYesNo(
+        rl,
+        "Serve a strict CSP (script-src 'self', no inline scripts)?",
+        defaults.csp === 'strict' || defaults.csp === 'hash',
+      ))
+        ? defaults.csp === 'hash'
+          ? 'hash'
+          : 'strict'
+        : 'off',
+      defaultImage: defaults.defaultImage,
+      trailingSlash: defaults.trailingSlash,
+      extraOptions: defaults.extraOptions ?? {},
+    };
+  } finally {
+    rl.close();
+  }
+}
+
+// Asks one question, showing the value Enter will accept.
+async function ask(rl, question, fallback) {
+  const answer = (await rl.question(`${question} (${fallback}): `)).trim();
+  return answer.length > 0 ? answer : fallback;
+}
+
+// Asks a yes/no question, treating Enter as the default.
+async function askYesNo(rl, question, fallback) {
+  const answer = (await rl.question(`${question} (${fallback ? 'Y/n' : 'y/N'}): `))
+    .trim()
+    .toLowerCase();
+  if (answer.length === 0) return fallback;
+  return answer === 'y' || answer === 'yes';
+}
+
+// Drops values that would make a broken config, so a typo becomes a warning instead.
+function validatedAnswers(answers, log) {
+  const cleaned = { ...answers };
+  if (cleaned.siteUrl && !/^https?:\/\//.test(cleaned.siteUrl)) {
+    log.warn(`ignoring site URL ${cleaned.siteUrl}: it must start with http:// or https://`);
+    cleaned.siteUrl = '';
+  }
+  if (cleaned.titleTemplate && !cleaned.titleTemplate.includes('%s')) {
+    log.warn('ignoring the title template: it has no %s placeholder');
+    cleaned.titleTemplate = '';
+  }
+  cleaned.include = parseRouteList(
+    Array.isArray(cleaned.include) ? cleaned.include.join(',') : (cleaned.include ?? '/'),
+  );
+  return cleaned;
+}
+
+// Accepts the array, comma-separated string or absent include value from every source.
+function includeList(value) {
+  if (Array.isArray(value)) return value;
+  if (typeof value === 'string') return parseRouteList(value);
+  return ['/'];
+}
+
+// Prints what the wizard carried over from a legacy react-snap block, and what it did not.
+function printReactSnapMapping(reactSnap, log) {
+  log.info('');
+  log.info('react-snap migration:');
+  if (reactSnap.mapping.length === 0) log.info('  no options carried over');
+  for (const { from, to, value } of reactSnap.mapping) {
+    log.info(`  reactSnap.${from} -> ${to} = ${JSON.stringify(value)}`);
+  }
+  for (const { key, reason } of reactSnap.ignored) {
+    log.warn(`  ignored reactSnap.${key}: ${reason}`);
+  }
+  for (const key of reactSnap.unknown) {
+    log.warn(`  unknown reactSnap.${key} was not migrated`);
+  }
+}
+
+// Prints what to do next: install if needed, run it, and where the head layer goes.
+function printNextSteps({ detected, log, tag = '' }) {
+  const run = runnerCommand(detected.runner, PACKAGE_NAME);
+  const install = installCommand(detected.runner, tag);
+  log.info('');
+  log.info('Next steps:');
+  if (!detected.installed) log.info(`  Install      ${install}`);
+  log.info(`  Dry run      ${run} --dry-run`);
+  log.info(`  Prerender    ${run}`);
+  log.info('');
+  log.info('Per-route titles and meta tags come from the head layer:');
+  log.info("  import { Head } from 'snappy-prerender/head';");
+  log.info('  <Head title="Awards" description="..." image="/share/awards.png" />');
+  if (detected.usesVite) {
+    log.info('');
+    log.info('Or run it inside the build (vite.config.js):');
+    log.info("  import snappy from 'snappy-prerender';");
+    log.info('  plugins: [react(), snappy()],');
+    log.info(
+      `  ${CONFIG_FILE} is read by the snappy-prerender command, so pass the same options to snappy() too.`,
+    );
+  }
+}
+
+// Builds the command that runs a locally installed binary for the project's package runner.
+function runnerCommand(runner, binary) {
+  if (runner === 'pnpm') return `pnpm exec ${binary}`;
+  if (runner === 'yarn') return `yarn ${binary}`;
+  return `npx ${binary}`;
+}
+
+// Builds the command that installs this package as a dev dependency.
+function installCommand(runner, tag = '') {
+  const pkg = `${PACKAGE_NAME}${tag}`;
+  if (runner === 'pnpm') return `pnpm add -D ${pkg}`;
+  if (runner === 'yarn') return `yarn add -D ${pkg}`;
+  return `npm install --save-dev ${pkg}`;
+}