snappy-prerender 2.6.0 → 2.8.0

package/src/core/hydration-diff.js

@@ -0,0 +1,93 @@
+import { parse } from 'parse5';
+
+const CONTAINER_IDS = new Set(['root', 'app', '__next']);
+const STABLE_ATTRIBUTES = ['id', 'class', 'href', 'src', 'type', 'role', 'name'];
+const MAX_NODES = 5000;
+const MAX_DEPTH = 20;
+
+/**
+ * Finds the first meaningful difference between the prerendered document and the live
+ * post-boot container. Bounded so a large app cannot turn verification into a memory
+ * problem.
+ */
+export function compareContainers(expectedHtml, liveHtml) {
+  const expected = containerOf(parse(expectedHtml));
+  const actual = containerOf(parse(liveHtml));
+  if (!expected || !actual) return null;
+  const state = { visited: 0 };
+  return diffNode(expected, actual, 'body', 0, state);
+}
+
+// Finds the app container in a parsed document, falling back to the body's first child.
+function containerOf(document) {
+  const html = (document.childNodes ?? []).find((node) => node.tagName === 'html');
+  const body = (html?.childNodes ?? []).find((node) => node.tagName === 'body');
+  if (!body) return null;
+  const container = (body.childNodes ?? []).find(
+    (node) => node.tagName && CONTAINER_IDS.has(attribute(node, 'id')),
+  );
+  return container ?? (body.childNodes ?? []).find((node) => node.tagName) ?? null;
+}
+
+// Compares one node pair and descends into the first differing child.
+function diffNode(expected, actual, path, depth, state) {
+  if (state.visited > MAX_NODES || depth > MAX_DEPTH) return null;
+  state.visited += 1;
+  const here = `${path}>${expected.tagName ?? expected.nodeName}`;
+  if (!actual || expected.tagName !== actual.tagName) {
+    return {
+      path,
+      kind: 'tag',
+      expected: expected.tagName ?? expected.nodeName,
+      actual: actual?.tagName ?? actual?.nodeName ?? null,
+    };
+  }
+  for (const name of STABLE_ATTRIBUTES) {
+    const left = attribute(expected, name);
+    const right = attribute(actual, name);
+    if (left !== right)
+      return { path: here, kind: 'attribute', name, expected: left, actual: right };
+  }
+  const expectedChildren = elementChildren(expected);
+  const actualChildren = elementChildren(actual);
+  for (let index = 0; index < expectedChildren.length; index += 1) {
+    const child = expectedChildren[index];
+    const other = actualChildren[index];
+    if (!other) {
+      return {
+        path: here,
+        kind: 'missing',
+        expected: child.tagName ?? child.nodeName,
+        actual: null,
+      };
+    }
+    const difference = diffNode(child, other, `${here}[${index}]`, depth + 1, state);
+    if (difference) return difference;
+  }
+  if (actualChildren.length > expectedChildren.length) {
+    const extra = actualChildren[expectedChildren.length];
+    return { path: here, kind: 'extra', expected: null, actual: extra.tagName ?? extra.nodeName };
+  }
+  const expectedText = directText(expected);
+  const actualText = directText(actual);
+  if (expectedText !== actualText) {
+    return { path: here, kind: 'text', expected: expectedText, actual: actualText };
+  }
+  return null;
+}
+
+function elementChildren(node) {
+  return (node.childNodes ?? []).filter((child) => child.tagName);
+}
+
+function directText(node) {
+  return (node.childNodes ?? [])
+    .filter((child) => child.nodeName === '#text')
+    .map((child) => child.value)
+    .join('')
+    .trim();
+}
+
+function attribute(node, name) {
+  return node.attrs?.find((entry) => entry.name === name)?.value ?? '';
+}

package/src/core/hydration-policy.js

@@ -0,0 +1,38 @@
+import { matchesPattern } from './routes.js';
+
+/**
+ * Resolves the hydration policy for one route. Global lists provide the default and a
+ * matching route override wins, so a broad allow-list can be narrowed for one route.
+ * @param {object} config
+ * @param {string} route
+ * @returns {'strict' | 'allow-rerender' | 'skip'}
+ */
+export function resolveHydrationPolicy(config, route) {
+  let policy = 'strict';
+  if ((config.hydration?.skip ?? []).some((pattern) => matchesPattern(route, pattern))) {
+    policy = 'skip';
+  } else if (
+    (config.hydration?.allowRerender ?? []).some((pattern) => matchesPattern(route, pattern))
+  ) {
+    policy = 'allow-rerender';
+  }
+  for (const override of config.routeOverrides ?? []) {
+    if (!matchesPattern(route, override.match)) continue;
+    if (override.hydration !== undefined) policy = override.hydration;
+  }
+  return policy;
+}
+
+/**
+ * Reports whether a verification result is allowed to differ from the prerendered markup.
+ * A route only becomes allowed after it actually re-rendered or logged a hydration error.
+ * @param {'strict' | 'allow-rerender' | 'skip'} policy
+ * @param {{ mode: string, hydrationErrors: string[] }} result
+ * @returns {boolean}
+ */
+export function isHydrationAllowed(policy, result) {
+  return (
+    policy === 'allow-rerender' &&
+    (result.mode === 're-rendered' || (result.hydrationErrors?.length ?? 0) > 0)
+  );
+}

package/src/core/init.js

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { DEFAULTS } from './config.js';
 import { normaliseRoute } from './routes.js';
 
 export const CONFIG_FILE = 'snappy.config.js';
@@ -15,6 +16,47 @@ const RUNNERS = [
   ['package-lock.json', 'npm'],
 ];
 
+// react-snap options whose name differs here, mapped to this package's option.
+const REACT_SNAP_RENAMED = {
+  source: 'sourceDir',
+  puppeteerArgs: 'browserArgs',
+  puppeteerIgnoreHTTPSErrors: 'ignoreHTTPSErrors',
+  skipThirdPartyRequests: 'blockThirdParty',
+  fixInsertRule: 'captureRuntimeStyles',
+  fixFormFields: 'captureFormState',
+  http2PushManifest: 'preloadManifest',
+};
+
+// react-snap options that keep their name and meaning.
+const REACT_SNAP_PASSTHROUGH = new Set([
+  'include',
+  'exclude',
+  'crawl',
+  'concurrency',
+  'timeout',
+  'waitFor',
+  'inlineCss',
+  'minifyHtml',
+  'minifyCss',
+  'cacheAjaxRequests',
+  'preconnectThirdParty',
+  'preloadImages',
+  'removeBlobs',
+  'removeStyleTags',
+  'removeScriptTags',
+  'asyncScriptTags',
+  'userAgent',
+  'viewport',
+  'saveAs',
+  'destination',
+]);
+
+// react-snap options that cannot be carried over, with the reason shown to the user.
+const REACT_SNAP_IGNORED = {
+  port: 'the prerenderer serves the build itself on an ephemeral port',
+  sourceMaps: 'react-snap declares it but never uses it',
+};
+
 /**
  * Reads what the project already says about itself: the framework that decides the build
  * directory, whether Vite is in use, which package runner it uses, and whether this package
@@ -26,13 +68,61 @@ export async function detectProjectDefaults(dir = process.cwd()) {
   const usesVite = Boolean(dependencies.vite) || (await anyExists(dir, VITE_CONFIGS));
   const usesCreateReactApp = Boolean(dependencies['react-scripts']) && !usesVite;
   const vite = usesVite ? await detectViteConfig(dir) : null;
-  return {
+  const detected = {
     sourceDir: vite?.sourceDir ?? (usesCreateReactApp ? 'build' : 'dist'),
     base: vite?.base ?? homepageBase(manifest?.homepage) ?? '/',
     usesVite,
     runner: await detectRunner(dir),
     installed: PACKAGE_NAME in dependencies,
   };
+  const reactSnap = mapReactSnapOptions(manifest?.reactSnap);
+  if (reactSnap) detected.reactSnap = reactSnap;
+  return detected;
+}
+
+/**
+ * Maps a legacy react-snap block onto this package's options. The result lists what
+ * carried over, what was deliberately dropped and what was not recognised, so the
+ * wizard can explain the migration instead of guessing.
+ */
+export function mapReactSnapOptions(block) {
+  if (typeof block !== 'object' || block === null || Array.isArray(block)) return null;
+  const values = {};
+  const mapping = [];
+  const ignored = [];
+  const unknown = [];
+  for (const [key, value] of Object.entries(block)) {
+    if (Object.hasOwn(REACT_SNAP_IGNORED, key)) {
+      ignored.push({ key, reason: REACT_SNAP_IGNORED[key] });
+      continue;
+    }
+    const target = REACT_SNAP_RENAMED[key] ?? (REACT_SNAP_PASSTHROUGH.has(key) ? key : null);
+    if (target === null) {
+      unknown.push(key);
+      continue;
+    }
+    // JSON cannot carry functions or RegExp, but a hand-written manifest may.
+    if (!isSerialisable(value)) {
+      unknown.push(`${key} (unsupported value)`);
+      continue;
+    }
+    const mappedValue =
+      target === 'include' && typeof value === 'string' ? parseRouteList(value) : value;
+    values[target] = mappedValue;
+    mapping.push({ from: key, to: target, value: mappedValue });
+  }
+  return { values, mapping, ignored, unknown };
+}
+
+// Reports whether a value can be written into a JavaScript config file.
+function isSerialisable(value) {
+  if (value === null) return true;
+  if (['string', 'number', 'boolean'].includes(typeof value)) return true;
+  if (Array.isArray(value)) return value.every(isSerialisable);
+  if (typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+    return Object.values(value).every(isSerialisable);
+  }
+  return false;
 }
 
 /**
@@ -87,46 +177,74 @@ export function parseRouteList(input) {
   return routes.length > 0 ? routes : ['/'];
 }
 
+/**
+ * Turns the wizard's answers into the options object the generated config will export.
+ * Only values that change a default are included, and only options the resolver knows.
+ */
+export function configValuesFromAnswers(answers = {}) {
+  const values = { sourceDir: answers.sourceDir ?? 'dist' };
+  if (answers.base && answers.base !== '/') values.base = answers.base;
+  // A supplied include list acts as an allowlist, so writing the default would stop discovery.
+  const includeValue = answers.include ?? ['/'];
+  const include = parseRouteList(
+    Array.isArray(includeValue) ? includeValue.join(',') : includeValue,
+  );
+  const includeIsDefault = include.length === 1 && include[0] === '/';
+  if (!includeIsDefault) values.include = include;
+  if (answers.crawl === false) values.crawl = false;
+  if (answers.csp === 'strict' || answers.csp === 'hash') values.csp = answers.csp;
+  if (answers.externalScripts === true) values.externalScripts = true;
+  if (answers.criticalCssPreload !== undefined && answers.criticalCssPreload !== 'media') {
+    values.criticalCssPreload = answers.criticalCssPreload;
+  }
+
+  const metadata = METADATA_KEYS.filter((key) => answers[key]).map((key) => [key, answers[key]]);
+  if (metadata.length > 0) values.metadata = Object.fromEntries(metadata);
+
+  for (const [key, value] of Object.entries(answers.extraOptions ?? {})) {
+    if (!Object.hasOwn(DEFAULTS, key) || key === 'metadata') continue;
+    if (Object.hasOwn(values, key)) continue;
+    if (!isSerialisable(value)) continue;
+    values[key] = value;
+  }
+  return values;
+}
+
 /**
  * Renders the config file for the wizard's answers, writing only the options the answers
  * actually set so every line in the file does something.
  */
 export function renderConfigFile(answers = {}) {
+  const values = configValuesFromAnswers(answers);
   const lines = [
     '// Created by `snappy-prerender init`. Every option is documented in the snappy-prerender README.',
     'export default {',
-    `  sourceDir: ${quote(answers.sourceDir ?? 'dist')},`,
   ];
-  if (answers.base && answers.base !== '/') lines.push(`  base: ${quote(answers.base)},`);
-  // A supplied include list acts as an allowlist, so writing the default would stop discovery.
-  // It is only written when the answer actually narrows the set of routes.
-  const include = parseRouteList((answers.include ?? ['/']).join(','));
-  const includeIsDefault = include.length === 1 && include[0] === '/';
-  if (!includeIsDefault) lines.push(`  include: [${include.map(quote).join(', ')}],`);
-  if (answers.crawl === false) lines.push('  crawl: false,');
-  // The CSP dial and the parts it was tuned with, so a strict-CSP project keeps the choice.
-  if (answers.csp === 'strict') lines.push('  csp: "strict",');
-  if (answers.externalScripts === true) lines.push('  externalScripts: true,');
-  if (answers.criticalCssPreload !== undefined && answers.criticalCssPreload !== 'media') {
-    // A boolean stays a literal; a mode name is quoted.
-    const value =
-      typeof answers.criticalCssPreload === 'boolean'
-        ? String(answers.criticalCssPreload)
-        : quote(answers.criticalCssPreload);
-    lines.push(`  criticalCssPreload: ${value},`);
-  }
-
-  const metadata = METADATA_KEYS.filter((key) => answers[key]).map((key) => [key, answers[key]]);
-  if (metadata.length > 0) {
+  for (const [key, value] of Object.entries(values)) {
+    if (key !== 'metadata') {
+      lines.push(`  ${key}: ${serializeValue(value)},`);
+      continue;
+    }
     lines.push('  metadata: {');
-    for (const [key, value] of metadata) lines.push(`    ${key}: ${quote(value)},`);
+    for (const [metadataKey, metadataValue] of Object.entries(value)) {
+      lines.push(`    ${metadataKey}: ${serializeValue(metadataValue)},`);
+    }
     lines.push('  },');
   }
-
   lines.push('};', '');
   return lines.join('\n');
 }
 
+// Writes a JSON-compatible value as JavaScript source with a stable, readable shape.
+function serializeValue(value) {
+  if (Array.isArray(value)) return `[${value.map(serializeValue).join(', ')}]`;
+  if (value !== null && typeof value === 'object') {
+    const entries = Object.entries(value).map(([key, entry]) => `${key}: ${serializeValue(entry)}`);
+    return `{ ${entries.join(', ')} }`;
+  }
+  return JSON.stringify(value);
+}
+
 /**
  * Writes the config file into the project, refusing to replace an existing one unless the
  * caller asked for it, so a wizard run can never silently destroy hand-written settings.
@@ -140,11 +258,6 @@ export async function writeConfigFile({ dir, contents, force = false }) {
   return target;
 }
 
-// Quotes a string for the generated module.
-function quote(value) {
-  return JSON.stringify(String(value));
-}
-
 // Reads a JSON file, treating a missing or malformed file as absent.
 async function readJson(file) {
   try {

package/src/core/inline-css.js

@@ -1,3 +1,4 @@
+import path from 'node:path';
 import { hasImportRule, rewriteCssUrls } from './css-url.js';
 import { minifyCss } from './minify.js';
 
@@ -8,8 +9,9 @@ import { minifyCss } from './minify.js';
  * place. Relative url() values are rebased against each sheet before joining so fonts
  * and images keep working on nested routes.
  */
-export async function inlineStylesheets({ page, minifyCssOptions }) {
-  const collected = await page.evaluate(async () => {
+export async function inlineStylesheets({ page, minifyCssOptions, cache = null }) {
+  const cachedCss = cache ? Object.fromEntries(cache) : {};
+  const collected = await page.evaluate(async (knownCss) => {
     // Only media that applies on screen can be inlined without changing how the sheet
     // applies, so a print stylesheet is left as a link instead of becoming active.
     const INLINEABLE_MEDIA = new Set(['', 'all', 'screen']);
@@ -22,24 +24,30 @@ export async function inlineStylesheets({ page, minifyCssOptions }) {
         skipped.push(link.href);
         continue;
       }
+      if (Object.hasOwn(knownCss, link.href)) {
+        sheets.push({ css: knownCss[link.href], href: link.href, fetched: false });
+        continue;
+      }
       try {
         const response = await fetch(link.href);
         if (!response.ok) throw new Error(String(response.status));
-        sheets.push({ css: await response.text(), href: link.href });
+        sheets.push({ css: await response.text(), href: link.href, fetched: true });
       } catch {
         skipped.push(link.href);
       }
     }
     return { sheets, skipped };
-  });
+  }, cachedCss);
 
   const inlineable = [];
   const skipped = [...collected.skipped];
+  const fetched = [];
   for (const sheet of collected.sheets) {
+    if (sheet.fetched) fetched.push({ href: sheet.href, css: sheet.css });
     if (hasImportRule(sheet.css)) skipped.push(sheet.href);
     else inlineable.push(sheet);
   }
-  if (inlineable.length === 0) return { skipped };
+  if (inlineable.length === 0) return { skipped, fetched };
 
   const pageOrigin = new URL(page.url()).origin;
   const joined = inlineable
@@ -59,7 +67,7 @@ export async function inlineStylesheets({ page, minifyCssOptions }) {
     },
     { text: css, hrefs: inlineable.map((sheet) => sheet.href) },
   );
-  return { skipped };
+  return { skipped, fetched };
 }
 
 /**
@@ -68,7 +76,43 @@ export async function inlineStylesheets({ page, minifyCssOptions }) {
  * beasties is an optional peer dependency because most projects never need it.
  * `preload` is passed through so a strict script-src can turn the swap handlers off.
  */
-export async function inlineCriticalCss({ html, outputDir, base, preload = 'media' }) {
+export async function inlineCriticalCss({
+  html,
+  outputDir,
+  base,
+  preload = 'media',
+  cache = null,
+}) {
+  const key = `${path.resolve(outputDir)}|${base}|${preload}`;
+  let state = cache?.get(key);
+  if (!state) {
+    state = {
+      processor: createCriticalCssProcessor({ outputDir, base, preload }),
+      tail: Promise.resolve(),
+    };
+    cache?.set(key, state);
+  }
+  // Beasties keeps per-instance selector state and is not safe for concurrent process
+  // calls, so this queue serialises routes while sharing the instance.
+  const run = state.tail.then(async () => {
+    const beasties = await state.processor;
+    return beasties.process(html);
+  });
+  state.tail = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  try {
+    return await run;
+  } catch (error) {
+    if (cache?.get(key) === state) cache.delete(key);
+    throw error;
+  }
+}
+
+// Creates the Beasties processor once per output configuration. The selector cache is
+// reused across routes; stylesheet text is still read per page by the library.
+async function createCriticalCssProcessor({ outputDir, base, preload }) {
   let Beasties;
   try {
     ({ default: Beasties } = await import('beasties'));
@@ -77,12 +121,11 @@ export async function inlineCriticalCss({ html, outputDir, base, preload = 'medi
       "inlineCss: 'critical' needs the optional beasties dependency. Install it with: npm install beasties",
     );
   }
-  const beasties = new Beasties({
+  return new Beasties({
     path: outputDir,
     publicPath: base,
     logLevel: 'silent',
     preload,
     noscriptFallback: true,
   });
-  return beasties.process(html);
 }

package/src/core/locale-context.js

@@ -0,0 +1,63 @@
+import {
+  resolveSeoLocale,
+  seedContextCookie,
+  seedCookies,
+  seedLocalStorage,
+  seedPageStorage,
+} from './seo-locale.js';
+
+/**
+ * Builds the Playwright context options that make one locale deterministic: browser
+ * locale, timezone and the base storage state. The caller keeps auth storage separate from
+ * locale cookies and local storage.
+ * @param {object} config
+ * @param {object | null} locale
+ * @returns {{ locale?: string, timezoneId?: string }}
+ */
+export function localeContextOptions(config, locale) {
+  const options = {};
+  const browserLocale = locale?.locale ?? null;
+  if (browserLocale) options.locale = browserLocale;
+  const timezone = locale?.timezone ?? config.timezone ?? null;
+  if (timezone) options.timezoneId = timezone;
+  return options;
+}
+
+/**
+ * Returns the storage state a locale should use, preferring its own file over the global
+ * authenticated state.
+ * @param {object} config
+ * @param {object | null} locale
+ * @returns {string | undefined}
+ */
+export function localeStorageState(config, locale) {
+  return locale?.storageState ?? config.storageState ?? undefined;
+}
+
+/**
+ * Seeds the extra cookies and local storage declared on a locale record. These are
+ * independent of the SEO locale recipe and let a locale carry app-specific keys.
+ * @param {{ page: import('playwright-core').Page, context: import('playwright-core').BrowserContext, origin: string, locale: object | null }} input
+ */
+export async function seedLocaleExtras({ page, context, origin, locale }) {
+  if (!locale) return;
+  await seedCookies(context, origin, locale.cookies ?? []);
+  await seedLocalStorage(page, locale.localStorage ?? {}, true);
+}
+
+/**
+ * Seeds the cookie and local storage the app reads before it boots. Render and verification
+ * use the same recipe, so the selected locale is identical in both passes.
+ * @param {{ page: import('playwright-core').Page, context: import('playwright-core').BrowserContext, origin: string, config: object, route: string, locale: object | null, phase: 'render' | 'verify' }} input
+ * @returns {Promise<object | null>} the resolved SEO locale, when one applied
+ */
+export async function seedLocaleContext({ page, context, origin, config, route, locale, phase }) {
+  await seedLocaleExtras({ page, context, origin, locale });
+  const seo = resolveSeoLocale(config, locale, route);
+  if (!seo) return null;
+  if (phase === 'render' && !seo.seedRender) return null;
+  if (phase === 'verify' && !seo.seedVerification) return null;
+  await seedPageStorage(page, seo);
+  await seedContextCookie(context, origin, seo);
+  return seo;
+}