snappy-prerender 2.6.0 → 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",
+  "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",
@@ -40,6 +40,7 @@
   },
   "files": [
     "src",
+    "docs",
     "CHANGELOG.md",
     "LICENSE",
     "README.md"

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

package/src/cli.js

@@ -1,17 +1,10 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
+import path from 'node:path';
 import process from 'node:process';
-import { createInterface } from 'node:readline/promises';
 import { pathToFileURL } from 'node:url';
 import { parseArgs } from 'node:util';
-import {
-  CONFIG_FILE,
-  detectProjectDefaults,
-  PACKAGE_NAME,
-  parseRouteList,
-  renderConfigFile,
-  writeConfigFile,
-} from './core/init.js';
+import { runInit } from './cli-init.js';
 import { createLogger } from './core/log.js';
 import { prerender } from './core/run.js';
 
@@ -66,6 +59,20 @@ Options:
       --scroll                Scroll through each page to trigger lazy content
       --flat                  Write about.html instead of about/index.html
       --not-found <route>     Route emitted as 404.html (default: /404)
+      --routes-file <file>    Read route seeds from a text/JSON file
+      --routes-from-sitemap <path-or-url>  Seed routes from a local or remote sitemap
+      --route-priority <patterns>  Patterns ranked first when crawling, comma separated
+      --report <file>         Write a machine-readable run report (JSON)
+      --audit                 Check the written site for broken links and SEO issues (default: on)
+      --no-audit              Skip the site audit
+      --fail-on-audit-error   Fail when the audit finds an error
+      --audit-ignore-links <patterns>  Link patterns excluded from the audit, comma separated
+      --preload-links         Inject module, font and LCP image preload hints into each page
+      --image-sitemap         List page images in the sitemap
+      --framework <name>      auto | react | vue | svelte | preact (default: auto)
+      --retries <n>           Retry a failed render this many times (default: 0)
+      --retry-delay <ms>      Wait between render attempts (default: 500)
+      --trace-on-error        Write a Playwright trace for the final failed attempt
       --destination <dir>     Write output to another directory (default: in place)
       --clean-destination     Empty the destination before copying the build output
       --save-as <format>      html | png | jpeg (default: html)
@@ -92,7 +99,7 @@ Options:
       --remove-styles         Strip every style tag from the output
       --async-scripts         Mark external scripts async
       --external-scripts      Write injected state scripts as same-origin files, for a strict CSP
-      --csp <mode>            off | strict: strict makes the output work under script-src 'self'
+      --csp <mode>            off | strict | hash: strict for script-src 'self', hash for inline hashes
       --no-remove-blobs       Keep blob stylesheet links instead of dropping them
       --remove-attributes <names>  Drop these attributes from the output, comma separated
       --no-strip-build-origin-metadata  Keep tags that point at the prerender server
@@ -165,6 +172,20 @@ async function main() {
       scroll: { type: 'boolean' },
       flat: { type: 'boolean' },
       'not-found': { type: 'string' },
+      'routes-file': { type: 'string' },
+      'routes-from-sitemap': { type: 'string' },
+      'route-priority': { type: 'string', multiple: true },
+      report: { type: 'string' },
+      audit: { type: 'boolean' },
+      'no-audit': { type: 'boolean' },
+      'fail-on-audit-error': { type: 'boolean' },
+      'audit-ignore-links': { type: 'string', multiple: true },
+      'preload-links': { type: 'boolean' },
+      'image-sitemap': { type: 'boolean' },
+      framework: { type: 'string' },
+      retries: { type: 'string' },
+      'retry-delay': { type: 'string' },
+      'trace-on-error': { type: 'boolean' },
       destination: { type: 'string' },
       'clean-destination': { type: 'boolean' },
       'save-as': { type: 'string' },
@@ -219,7 +240,12 @@ async function main() {
     return;
   }
   if (parsed.positionals[0] === 'init') {
-    await runInit(parsed);
+    await runInit({
+      values: parsed.values,
+      flags: cliOptions({ values: parsed.values, positionals: [] }),
+      log: createLogger(parsed.values['log-level'] ?? 'info'),
+      version: readVersion(),
+    });
     return;
   }
 
@@ -307,6 +333,26 @@ function cliOptions({ values, positionals }) {
   if (values.scroll) options.scrollToBottom = true;
   if (values.flat) options.flatOutput = true;
   if (values['not-found'] !== undefined) options.notFoundRoute = values['not-found'];
+  if (values['routes-file'] !== undefined) options.routesFile = values['routes-file'];
+  if (values['routes-from-sitemap'] !== undefined) {
+    options.routesFromSitemap = values['routes-from-sitemap'];
+  }
+  if (values['route-priority'] !== undefined) {
+    options.routePriority = splitList(values['route-priority']);
+  }
+  if (values.report !== undefined) options.reportPath = values.report;
+  if (values.audit !== undefined) options.audit = values.audit;
+  else if (values['no-audit']) options.audit = false;
+  if (values['fail-on-audit-error']) options.failOnAuditError = true;
+  if (values['audit-ignore-links'] !== undefined) {
+    options.auditIgnoreLinks = splitList(values['audit-ignore-links']);
+  }
+  if (values['preload-links']) options.preloadLinks = true;
+  if (values['image-sitemap']) options.imageSitemap = true;
+  if (values.framework !== undefined) options.framework = values.framework;
+  if (values.retries !== undefined) options.retries = Number(values.retries);
+  if (values['retry-delay'] !== undefined) options.retryDelay = Number(values['retry-delay']);
+  if (values['trace-on-error']) options.traceOnError = true;
   if (values.destination !== undefined) options.destination = values.destination;
   if (values['clean-destination']) options.cleanDestination = true;
   if (values['save-as'] !== undefined) options.saveAs = values['save-as'];
@@ -354,162 +400,6 @@ function splitList(entries) {
   return entries.flatMap((entry) => entry.split(',')).filter((entry) => entry.length > 0);
 }
 
-/**
- * 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.
- */
-async function runInit({ values }) {
-  const log = createLogger(values['log-level'] ?? 'info');
-  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 flags = cliOptions({ values, positionals: [] });
-  const defaults = defaultsFromFlags(detected, flags);
-  const answers = values.yes ? defaults : await askAnswers(defaults, log);
-  const cleaned = validatedAnswers(answers, log);
-
-  await writeConfigFile({
-    dir: cwd,
-    contents: renderConfigFile(cleaned),
-    force: values.force === true,
-  });
-  log.success(`Wrote ${CONFIG_FILE}`);
-  printNextSteps({ detected, log, tag: readVersion().includes('-') ? '@next' : '' });
-}
-
-// Turns the flags the CLI already understands into the wizard's starting answers.
-function defaultsFromFlags(detected, flags) {
-  return {
-    sourceDir: flags.sourceDir ?? detected.sourceDir,
-    base: flags.base ?? detected.base ?? '/',
-    include: flags.include ?? ['/'],
-    crawl: flags.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,
-  };
-}
-
-// 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',
-      ))
-        ? 'strict'
-        : 'off',
-      defaultImage: defaults.defaultImage,
-      trailingSlash: defaults.trailingSlash,
-    };
-  } 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((cleaned.include ?? ['/']).join(','));
-  return cleaned;
-}
-
-// 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}`;
-}
-
 // Collects the metadata flags, or null when none was passed so a config file value survives.
 function metadataOptions(values) {
   const metadata = {};
@@ -556,7 +446,22 @@ async function loadConfigFile(explicitPath) {
       `Config file must export a plain options object or a function returning one: ${explicitPath}`,
     );
   }
-  return loaded;
+  return resolveSourcePaths(loaded, path.dirname(path.resolve(explicitPath)));
+}
+
+// Resolves local route-source paths against the config file, not the process cwd, while
+// leaving URLs and absolute paths alone.
+function resolveSourcePaths(options, dir) {
+  const resolve = (value) => {
+    if (typeof value !== 'string' || value.length === 0) return value;
+    if (/^https?:\/\//i.test(value) || path.isAbsolute(value)) return value;
+    return path.resolve(dir, value);
+  };
+  return {
+    ...options,
+    routesFile: resolve(options.routesFile),
+    routesFromSitemap: resolve(options.routesFromSitemap),
+  };
 }
 
 // Reads the package version without importing JSON, keeping Node 20 compatible.

package/src/core/artifacts.js

@@ -69,6 +69,7 @@ export async function writeSitemap({ outputDir, config, log, report }) {
       routes: sitemap.routes,
       robotsUpdated: patched !== null,
       files: names,
+      locs: sitemap.locs,
     };
     log.info(`Dry run: would write ${names.join(', ')} listing ${sitemap.routes} route(s)`);
     return;
@@ -89,6 +90,7 @@ export async function writeSitemap({ outputDir, config, log, report }) {
     routes: sitemap.routes,
     robotsUpdated: patched !== null,
     files: names,
+    locs: sitemap.locs,
   };
   log.info(
     `${statuses.every((status) => status === 'unchanged') ? 'Unchanged' : 'Wrote'} ${names.join(', ')} listing ${sitemap.routes} route(s)`,