snappy-prerender 2.6.0-rc.2

package/src/head/index.js

@@ -0,0 +1,56 @@
+import { useEffect, useLayoutEffect, useRef } from 'react';
+import { readMetadataDefaults, registerHead, unregisterHead } from './manager.js';
+import { buildHeadEntries } from './tags.js';
+
+const useIsomorphicLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect;
+
+let sequence = 0;
+
+/**
+ * Declares document metadata for the route being rendered: title, description, robots,
+ * canonical, Open Graph and Twitter card tags. The head is reconciled on every render while
+ * the component is mounted, so client-side navigation gives each route its own head exactly
+ * like a site that renders a page per request.
+ *
+ * Renders nothing, so it never affects hydration of the page content.
+ */
+export function Head(props) {
+  const idRef = useRef(null);
+  const sequenceRef = useRef(0);
+
+  if (idRef.current === null) {
+    sequence += 1;
+    idRef.current = `snappy-head-${sequence}`;
+    // Render order decides precedence: a page's Head is rendered after the layout's, so it
+    // wins for any tag they both set.
+    sequenceRef.current = sequence;
+  }
+
+  const entries = buildHeadEntries(props, readMetadataDefaults());
+
+  // A layout effect so a route change updates the head before the browser paints, and a
+  // plain effect on the server, where layout effects never run.
+  useIsomorphicLayoutEffect(() => {
+    registerHead(idRef.current, sequenceRef.current, entries);
+  });
+
+  useEffect(() => () => unregisterHead(idRef.current), []);
+
+  return null;
+}
+
+/**
+ * Imperative equivalent for code that is not a React component, for example a vanilla
+ * router or an analytics callback.
+ */
+export function setHead(id, props) {
+  sequence += 1;
+  registerHead(id, sequence, buildHeadEntries(props, readDefaults()));
+}
+
+/**
+ * Removes metadata previously set with setHead.
+ */
+export function clearHead(id) {
+  unregisterHead(id);
+}

package/src/head/manager.js

@@ -0,0 +1,230 @@
+import { headKey, mergeHeadEntries } from './tags.js';
+
+const OWNER_ATTRIBUTE = 'data-snappy-head';
+const CREATED_ATTRIBUTE = 'data-snappy-head-created';
+const stack = [];
+const snapshots = new WeakMap();
+const createdElements = new WeakSet();
+const originals = readRecordedOriginals();
+publishOriginals();
+
+/**
+ * Reads the metadata defaults the prerenderer persisted: an inert JSON script once the page
+ * carries one, or the init-script global while prerendering, before that element exists.
+ */
+export function readMetadataDefaults() {
+  const element =
+    typeof document === 'undefined' ? null : document.querySelector('script[data-snappy-meta]');
+  if (element) {
+    try {
+      return JSON.parse(element.textContent) ?? {};
+    } catch {
+      return {};
+    }
+  }
+  return typeof window === 'undefined' ? {} : (window.__SNAPPY_META__ ?? {});
+}
+
+/**
+ * Registers one mounted Head's tag list and reconciles the document head with the merged
+ * result. Called on every render, so a client-side route change updates the head without a
+ * page load.
+ */
+export function registerHead(id, sequence, entries) {
+  const index = stack.findIndex((item) => item.id === id);
+  const item = { id, sequence, entries };
+  if (index === -1) stack.push(item);
+  else stack[index] = item;
+  applyMerged();
+}
+
+/**
+ * Removes a Head's contribution and releases the tags it owned, so leaving a route does not
+ * leave that route's metadata behind.
+ */
+export function unregisterHead(id) {
+  const index = stack.findIndex((item) => item.id === id);
+  if (index === -1) return;
+  stack.splice(index, 1);
+  applyMerged();
+}
+
+// Brings the head in line with the merged entries: create, adopt or update each tag, drop
+// duplicates of the same identity, release tags that are no longer wanted, then restore a
+// deterministic order.
+function applyMerged() {
+  if (typeof document === 'undefined' || !document.head) return;
+  const head = document.head;
+  const merged = mergeHeadEntries(stack);
+  const desired = new Map(merged.map((entry) => [headKey(entry), entry]));
+
+  for (const [key, entry] of desired) {
+    const matches = findTags(head, key);
+    const element = matches[0] ?? createTag(head, entry);
+    writeTag(element, entry, key);
+    // A second tag with the same identity is one the page should not ship twice. Titles are
+    // exempt: React 19 native metadata and the head layer can each write one.
+    if (key !== 'title') {
+      for (const duplicate of matches.slice(1)) removeDuplicate(duplicate, key);
+    }
+  }
+
+  for (const element of [...head.querySelectorAll(`[${OWNER_ATTRIBUTE}]`)]) {
+    const key = element.getAttribute(OWNER_ATTRIBUTE);
+    if (!desired.has(key)) releaseTag(element, key);
+  }
+
+  orderTags(head, merged);
+}
+
+/**
+ * Finds every tag a key refers to, in document order. Matching on the attribute a crawler
+ * reads means a tag already in the document — including one in prerendered HTML — is
+ * updated in place instead of duplicated.
+ */
+function findTags(head, key) {
+  if (key === 'title') {
+    const title = head.querySelector('title');
+    return title ? [title] : [];
+  }
+  const [kind, attribute, ...rest] = key.split(':');
+  const value = rest.join(':');
+  if (
+    kind === 'meta' &&
+    (attribute === 'name' || attribute === 'property' || attribute === 'http-equiv')
+  ) {
+    return [...head.querySelectorAll(`meta[${attribute}="${cssEscape(value)}"]`)];
+  }
+  if (kind === 'link' && attribute === 'rel') return findRelLinks(head, value);
+  const owned = head.querySelector(`[${OWNER_ATTRIBUTE}="${cssEscape(key)}"]`);
+  return owned ? [owned] : [];
+}
+
+// Matches links by rel, and by href when the key carries one, so two links that share a rel
+// but point elsewhere stay distinct.
+function findRelLinks(head, value) {
+  const [rel, href] = value.split('|');
+  const links = [...head.querySelectorAll(`link[rel="${cssEscape(rel)}"]`)];
+  if (href === undefined) return links;
+  return links.filter((link) => link.getAttribute('href') === href);
+}
+
+function createTag(head, entry) {
+  const element = document.createElement(entry.kind);
+  createdElements.add(element);
+  head.appendChild(element);
+  return element;
+}
+
+// Drops a tag that repeats an identity already rendered, leaving tags owned under another
+// key alone so a shared element is never removed by mistake.
+function removeDuplicate(element, key) {
+  const owner = element.getAttribute(OWNER_ATTRIBUTE);
+  if (owner !== null && owner !== key) return;
+  element.remove();
+}
+
+// Writes the entry onto its element and marks the element as owned, pruning attributes that
+// are no longer part of the entry. A tag the head layer created is also marked, so a later
+// page load can still tell it apart from one the app wrote and remove rather than restore it.
+function writeTag(element, entry, key) {
+  snapshotTag(element, key);
+  element.setAttribute(OWNER_ATTRIBUTE, key);
+  if (createdElements.has(element)) element.setAttribute(CREATED_ATTRIBUTE, '');
+  if (entry.kind === 'title') {
+    element.textContent = entry.text;
+    return;
+  }
+  for (const attribute of [...element.attributes]) {
+    if (attribute.name === OWNER_ATTRIBUTE || attribute.name === CREATED_ATTRIBUTE) continue;
+    if (!Object.hasOwn(entry.attrs, attribute.name)) element.removeAttribute(attribute.name);
+  }
+  for (const [name, value] of Object.entries(entry.attrs)) element.setAttribute(name, value);
+}
+
+// Remembers what a tag looked like before the head layer first touched it, so an app-owned
+// tag can be handed back unchanged once no Head wants it any more. App-owned tags are also
+// recorded under a global the prerenderer picks up, so the generated HTML can carry the
+// original and a later page load can still hand the app's tag back.
+function snapshotTag(element, key) {
+  if (snapshots.has(element)) return;
+  const attrs = new Map();
+  for (const attribute of element.attributes) {
+    if (attribute.name === OWNER_ATTRIBUTE || attribute.name === CREATED_ATTRIBUTE) continue;
+    attrs.set(attribute.name, attribute.value);
+  }
+  const snapshot = {
+    attrs: Object.fromEntries(attrs),
+    text: element.tagName === 'TITLE' ? element.textContent : null,
+  };
+  snapshots.set(element, snapshot);
+  if (createdElements.has(element) || element.hasAttribute(CREATED_ATTRIBUTE)) return;
+  // A record from an earlier prerender stays as it is, so a rerun over already generated
+  // output reproduces the same bytes instead of recording its own output as the original.
+  if (key in originals) return;
+  originals[key] = snapshot;
+  publishOriginals();
+}
+
+// Mirrors the recorded originals into a global the prerenderer picks up, so the generated HTML
+// can carry them and a later page load can hand the app's own tags back. Published once at
+// module load as well, because a rerun must not lose records it did not add itself.
+function publishOriginals() {
+  if (typeof window !== 'undefined') window.__snappyHeadOriginals = originals;
+}
+
+// Reads the originals an earlier prerender baked into the page.
+function readRecordedOriginals() {
+  const recorded = readMetadataDefaults().originals;
+  return recorded && typeof recorded === 'object' ? { ...recorded } : {};
+}
+
+// Removes a tag the head layer created, including one generated in an earlier prerender, or
+// restores an adopted tag to the state it was in before the head layer wrote to it, which
+// hands the app's own metadata back.
+function releaseTag(element, key) {
+  if (createdElements.has(element) || element.hasAttribute(CREATED_ATTRIBUTE)) {
+    element.remove();
+    return;
+  }
+  // A record baked into the page by a prerender beats this session's snapshot, because the
+  // markup already holds the head layer's output rather than the app's own value.
+  const restore = readRecordedOriginal(key) ?? snapshots.get(element) ?? null;
+  if (!restore) {
+    element.remove();
+    return;
+  }
+  applySnapshot(element, restore);
+  snapshots.delete(element);
+}
+
+// Reads the original attributes a previous prerender recorded for a key.
+function readRecordedOriginal(key) {
+  return key in originals ? originals[key] : null;
+}
+
+// Replaces every attribute and the text of a tag with a recorded snapshot.
+function applySnapshot(element, snapshot) {
+  for (const name of [...element.attributes].map((attribute) => attribute.name)) {
+    element.removeAttribute(name);
+  }
+  for (const [name, value] of Object.entries(snapshot.attrs ?? {})) {
+    element.setAttribute(name, value);
+  }
+  if (snapshot.text !== null && snapshot.text !== undefined) element.textContent = snapshot.text;
+}
+
+// Re-appends owned tags in merged order, so the emitted head is identical between runs
+// regardless of the order in which components first rendered their tags.
+function orderTags(head, merged) {
+  const order = merged.flatMap((entry) => findTags(head, headKey(entry)));
+  const owned = [...head.querySelectorAll(`[${OWNER_ATTRIBUTE}]`)];
+  const sameOrder =
+    owned.length === order.length && owned.every((element, index) => element === order[index]);
+  if (sameOrder) return;
+  for (const element of order) head.appendChild(element);
+}
+
+function cssEscape(value) {
+  return String(value).replace(/["\\]/g, '\\$&');
+}

package/src/head/tags.js

@@ -0,0 +1,211 @@
+import { collectBuildOrigins } from '../core/metadata-origin.js';
+
+const ABSOLUTE = /^https?:\/\//i;
+const PROTOCOL_RELATIVE = /^\/\//;
+const URL_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+const SINGLETON_LINK_RELS = new Set(['canonical']);
+
+/**
+ * Turns component props plus project defaults into the tag list the document head should
+ * hold: title, description, robots, canonical, Open Graph and Twitter card. Values the
+ * caller did not supply are simply absent, so the component never invents metadata the app
+ * did not ask for.
+ */
+export function buildHeadEntries(props = {}, defaults = {}) {
+  const entries = [];
+  const template = props.titleTemplate ?? defaults.titleTemplate ?? null;
+  const siteName = props.siteName ?? defaults.siteName ?? null;
+  const image = props.image ?? defaults.defaultImage ?? null;
+
+  const title = props.title ? applyTitleTemplate(props.title, template, siteName) : null;
+  if (title) entries.push({ kind: 'title', text: title });
+  if (title && props.openGraph !== false) entries.push(metaProp('og:title', title));
+  if (title && props.twitter !== false) entries.push(metaName('twitter:title', title));
+
+  if (props.description) {
+    entries.push(metaName('description', props.description));
+    if (props.openGraph !== false) entries.push(metaProp('og:description', props.description));
+    if (props.twitter !== false) entries.push(metaName('twitter:description', props.description));
+  }
+
+  if (props.robots) entries.push(metaName('robots', props.robots));
+
+  if (props.openGraph !== false) {
+    entries.push(metaProp('og:type', props.type ?? 'website'));
+    if (siteName) entries.push(metaProp('og:site_name', siteName));
+    if (props.locale) entries.push(metaProp('og:locale', props.locale));
+    const url = pageUrl(props.canonical ?? currentPath(), defaults);
+    if (url) entries.push(metaProp('og:url', url));
+    if (image) entries.push(metaProp('og:image', absoluteUrl(image, defaults)));
+  }
+
+  if (props.twitter !== false) {
+    entries.push(metaName('twitter:card', image ? 'summary_large_image' : 'summary'));
+    if (image) entries.push(metaName('twitter:image', absoluteUrl(image, defaults)));
+  }
+
+  if (props.canonical !== false) {
+    const url = pageUrl(props.canonical ?? currentPath(), defaults);
+    if (url)
+      entries.push({ kind: 'link', key: 'rel:canonical', attrs: { rel: 'canonical', href: url } });
+  }
+
+  for (const extra of props.extra ?? []) entries.push(extraEntry(extra));
+
+  return entries;
+}
+
+/**
+ * Merges every mounted Head into one tag list. Later entries win per tag key, and the
+ * render order recorded by each component decides "later", so a page's Head overrides the
+ * layout's Head rather than the other way around.
+ */
+export function mergeHeadEntries(stack = []) {
+  const merged = new Map();
+  for (const item of [...stack].sort((a, b) => a.sequence - b.sequence)) {
+    for (const entry of item.entries) merged.set(headKey(entry), entry);
+  }
+  const values = [...merged.values()];
+  const titles = values.filter((entry) => entry.kind === 'title');
+  const rest = values.filter((entry) => entry.kind !== 'title');
+  return [...titles, ...sortMetasFirst(rest)];
+}
+
+/**
+ * Identifies a tag by what a browser or crawler matches on, not by who wrote it, so an
+ * existing tag is updated in place rather than duplicated.
+ */
+export function headKey(entry) {
+  if (entry.kind === 'title') return 'title';
+  if (entry.kind === 'link') return `link:${entry.key ?? attrsKey(entry.attrs)}`;
+  if (entry.key) return `meta:${entry.key}`;
+  const name = attrsValue(entry.attrs, 'name');
+  if (name) return `meta:name:${name}`;
+  const property = attrsValue(entry.attrs, 'property');
+  if (property) return `meta:property:${property}`;
+  const httpEquiv = attrsValue(entry.attrs, 'http-equiv');
+  if (httpEquiv) return `meta:http-equiv:${httpEquiv}`;
+  return `meta:${attrsKey(entry.attrs)}`;
+}
+
+/**
+ * Collects the absolute metadata URLs in a document that point at the machine the
+ * prerenderer ran on, which happens when no public siteUrl was configured.
+ */
+export function findBuildOriginUrls(html) {
+  return collectBuildOrigins(html);
+}
+
+// Applies the site's title template unless the title already carries its suffix or is the
+// site name itself, so an app that composed its own title never gets it suffixed twice.
+function applyTitleTemplate(title, template, siteName) {
+  if (!template || !template.includes('%s')) return title;
+  if (alreadyTemplated(title, template, siteName)) return title;
+  return template.replaceAll('%s', title);
+}
+
+// Reports whether the title already ends with the template's fixed part, compared as a
+// whole suffix rather than a substring, so a site name inside a title does not skip it.
+function alreadyTemplated(title, template, siteName) {
+  if (siteName && title === siteName) return true;
+  const suffix = template.replaceAll('%s', '').trim();
+  return suffix.length > 0 && title.endsWith(suffix);
+}
+
+// Resolves a metadata URL. Protocol-relative and non-http values stay as given, paths are
+// resolved against the public site URL, and spaces are encoded so the value is a valid URL.
+function absoluteUrl(value, defaults) {
+  if (!value) return null;
+  const raw = String(value);
+  if (ABSOLUTE.test(raw) || PROTOCOL_RELATIVE.test(raw) || URL_SCHEME.test(raw)) {
+    return encodeSpaces(raw);
+  }
+  const base = defaults.siteUrl ?? (typeof location === 'undefined' ? null : location.origin);
+  if (!base) return null;
+  const prefix = defaults.base && defaults.base !== '/' ? defaults.base.replace(/\/$/, '') : '';
+  const path = raw.startsWith('/') ? raw : `/${raw}`;
+  return encodeSpaces(`${base.replace(/\/$/, '')}${prefix}${path}`);
+}
+
+// Resolves a page URL and applies the trailing slash convention to it. Asset URLs never go
+// through this, because a file path must not gain or lose a slash.
+function pageUrl(value, defaults) {
+  const url = absoluteUrl(value, defaults);
+  return url ? withTrailingSlash(url, defaults.trailingSlash) : null;
+}
+
+// Encodes space characters so a value pasted into metadata still serialises as a valid URL.
+function encodeSpaces(url) {
+  return url.replace(/ /g, '%20');
+}
+
+// Applies the site's trailing slash convention to a URL, leaving the root alone.
+function withTrailingSlash(url, convention) {
+  if (convention !== 'always' && convention !== 'never') return url;
+  const [path, query] = url.split('?');
+  const isRoot = /^https?:\/\/[^/]+\/?$/i.test(path);
+  if (convention === 'always') {
+    const next = path.endsWith('/') ? path : `${path}/`;
+    return query ? `${next}?${query}` : next;
+  }
+  if (isRoot) return query ? `${path.replace(/\/$/, '/')}?${query}` : path.replace(/\/?$/, '/');
+  const next = path.replace(/\/+$/, '');
+  return query ? `${next}?${query}` : next;
+}
+
+// Reads the route being rendered, which under prerendering is the page being captured.
+function currentPath() {
+  return typeof location === 'undefined' ? '/' : location.pathname;
+}
+
+function metaName(name, content) {
+  return { kind: 'meta', key: `name:${name}`, attrs: { name, content } };
+}
+
+function metaProp(property, content) {
+  return { kind: 'meta', key: `property:${property}`, attrs: { property, content } };
+}
+
+// Builds an entry from the caller's escape hatch for tags the model does not cover.
+function extraEntry(extra) {
+  const attrs = { ...extra };
+  delete attrs.key;
+  const kind = attrs.rel && !attrs.content ? 'link' : 'meta';
+  const key = extra.key ?? (kind === 'link' ? linkKey(attrs) : identityKey(attrs));
+  return { kind, key, attrs };
+}
+
+// Keys a meta tag the same way the model keys its own, so a later Head can override it
+// instead of adding a duplicate.
+function identityKey(attrs) {
+  if (attrs.name) return `name:${attrs.name}`;
+  if (attrs.property) return `property:${attrs.property}`;
+  if (attrs['http-equiv']) return `http-equiv:${attrs['http-equiv']}`;
+  return attrsKey(attrs);
+}
+
+// Keys a link by rel, plus href for every rel a page may legitimately use more than once
+// (preload, alternate, icon). Only singleton rels collapse to one tag per document.
+function linkKey(attrs) {
+  const rel = String(attrs.rel);
+  if (SINGLETON_LINK_RELS.has(rel.toLowerCase()) || !attrs.href) return `rel:${rel}`;
+  return `rel:${rel}|${attrs.href}`;
+}
+
+function attrsKey(attrs) {
+  return Object.entries(attrs)
+    .map(([name, value]) => `${name}=${value}`)
+    .join('|');
+}
+
+function attrsValue(attrs = {}, name) {
+  return attrs[name];
+}
+
+// Keeps output deterministic: title, then name/property metas, then links.
+function sortMetasFirst(entries) {
+  return [...entries].sort((a, b) => {
+    const rank = (entry) => (entry.kind === 'meta' ? 0 : 1);
+    return rank(a) - rank(b);
+  });
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { DEFAULTS, prerender, resolveConfig } from './core/index.js';
+export { default } from './vite-plugin.js';

package/src/vite-plugin.js

@@ -0,0 +1,49 @@
+import path from 'node:path';
+import { prerender } from './core/run.js';
+
+/**
+ * Decides whether a build should be prerendered at all. Skipped for SSR, library
+ * and non-writing builds, and for any environment other than the client one so a
+ * multi-environment build cannot run the prerenderer more than once.
+ */
+export function shouldPrerender(viteConfig, environmentName) {
+  if (!viteConfig) return false;
+  if (viteConfig.build.ssr || viteConfig.build.lib || viteConfig.build.write === false) {
+    return false;
+  }
+  if (environmentName && environmentName !== 'client') return false;
+  return true;
+}
+
+/**
+ * Vite plugin wrapper around the prerenderer. Runs after the client build has been
+ * written, prerenders the output directory, and fails the build when rendering or
+ * hydration verification fails.
+ */
+export default function snappyPrerender(options = {}) {
+  let viteConfig = null;
+  let done = false;
+  return {
+    name: 'snappy-prerender',
+    apply: 'build',
+    configResolved(config) {
+      viteConfig = config;
+    },
+    async closeBundle() {
+      if (done || !shouldPrerender(viteConfig, this.environment?.name)) return;
+      done = true;
+
+      const report = await prerender({
+        sourceDir: path.resolve(viteConfig.root, viteConfig.build.outDir),
+        base: viteConfig.base,
+        ...options,
+      });
+      if (!report.ok) {
+        const hydrationFailed = report.verification && !report.verification.ok;
+        throw new Error(
+          `snappy-prerender failed: ${report.errors.length} route error(s)${hydrationFailed ? ', hydration verification failed' : ''}`,
+        );
+      }
+    },
+  };
+}