snappy-prerender 2.6.0-rc.3 → 2.7.0

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,102 @@
+# 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,
+  "ok": true,
+  "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,
+    "errors": []
+  },
+  "routes": [
+    {
+      "route": "/",
+      "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": "",
+        "h1Count": 1,
+        "alternates": [],
+        "images": [],
+        "inlineStyleAttributes": 0
+      },
+      "hydrationErrors": [],
+      "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 configuration, `storageState`, captured AJAX state, cookies,
+tokens, request bodies or full asset URLs containing credentials. 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>`.
+- `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>`.
+- `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-rc.3",
+  "version": "2.7.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",
@@ -26,7 +26,7 @@
     "playwright"
   ],
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=22.12.0"
   },
   "main": "./src/index.js",
   "exports": {
@@ -36,14 +36,18 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "snappy-prerender": "./src/cli.js"
+    "snappy-prerender": "src/cli.js"
   },
   "files": [
     "src",
+    "docs",
+    "CHANGELOG.md",
     "LICENSE",
     "README.md"
   ],
-  "sideEffects": false,
+  "sideEffects": [
+    "./src/head/manager.js"
+  ],
   "scripts": {
     "test": "node scripts/run-tests.mjs tests/unit",
     "test:integration": "node scripts/run-tests.mjs tests/integration",
@@ -65,7 +69,7 @@
     "beasties": "0.4.1",
     "react": "19.2.0",
     "react-dom": "19.2.0",
-    "vite": "7.3.6"
+    "vite": "7.3.7"
   },
   "workspaces": [
     "tests/fixtures/react16-app",

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}`;
+}