create-shapio 0.5.1 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-shapio",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Scaffold a new Shapio project (npx create-shapio my-cms) or a site starter (--site astro|next|sveltekit)",
   "license": "Apache-2.0",
   "homepage": "https://shapio.dev",

package/templates/astro/README.md

@@ -17,7 +17,8 @@ npm run smoke:http  # checks the served pages over HTTP (in another terminal, wh
 
 `npm run seed` applies the models in `shapio/` to Shapio live, creates the content and writes `SHAPIO_URL` and
 `SHAPIO_DELIVERY_TOKEN` to `.env`. Other settings (`SHAPIO_SNAPSHOT`, `SHAPIO_SITE`, `PUBLIC_SHAPIO_URL`) are
-in `.env.example`. Astro's telemetry is turned off in the npm scripts.
+in `.env.example`. Settings are read from the environment and `.env` only (not `.env.local` or
+`.env.production`). Astro's telemetry is turned off in the npm scripts.
 
 Drafts mode, for your development server: set `SHAPIO_DRAFTS=true` in `.env` and `npm run dev` shows saved
 drafts instead of published content, fresh on every reload, with a **Drafts** badge on every page. Save in
@@ -28,6 +29,14 @@ without it fails with `DRAFTS_FORBIDDEN`). Never put that token or the flag in a
 (http://localhost:4321; needs `SHAPIO_ADMIN_EMAIL`/`PASSWORD` to save a test change, which it puts back). Guide:
 [drafts mode](https://github.com/mybrokengnome/shapio/blob/main/documentation/starters.md#drafts-mode).
 
+Incremental builds: `npm run build` re-renders only the pages whose data or code changed and restores the rest
+from the previous build (Astro's `experimental.incrementalBuild`; each page's `cacheKey` is a digest of what it
+renders, `src/lib/cacheKey.ts`). The cache is `node_modules/.astro`: on Cloudflare Pages, turn on build caching
+(Settings → Builds → Build cache) so it survives between builds; without it every build is a full one.
+`npm run check:incremental` checks this against the seeded Shapio (it publishes one edit and puts it back).
+`npm run build:incremental` is a local and CI tool on top: it skips the build entirely when nothing the site
+reads changed since the `dist/` on disk, and always builds where there is none.
+
 Preview: the seed creates a deployment connection named **Preview** that opens drafts at
 `http://localhost:4321/preview/` (set `SITE_URL` when seeding for another address). Add that origin to Shapio's
 `CORS_ORIGINS`. In Shapio's preview pane, clicking the title, body or cover focuses that field and saves

package/templates/astro/astro.config.mjs

@@ -47,4 +47,11 @@ export default defineConfig({
   build: { format: 'directory' },
   server: { headers: { 'Content-Security-Policy': FRAME_ANCESTORS } },
   integrations: [frameAncestorsHeaders],
+  /**
+   * Incremental builds: a page whose `cacheKey` (src/lib/cacheKey.ts) and code are unchanged is restored from
+   * the previous build instead of rendered. The cache lives in Astro's cacheDir, `node_modules/.astro`, which
+   * Cloudflare Pages build caching (Settings → Builds → Build cache) restores between builds. Do not set
+   * `cacheDir`: the cache would silently stop surviving there, and every build would render every page.
+   */
+  experimental: { incrementalBuild: true },
 });

package/templates/astro/package.json

@@ -17,12 +17,13 @@
     "smoke:http": "node --import tsx scripts/smokeHttp.ts --url http://localhost:4321",
     "report-status": "node --env-file-if-exists=.env --import tsx scripts/reportStatus.ts",
     "build:incremental": "node --env-file-if-exists=.env --import tsx scripts/incrementalBuild.ts",
+    "check:incremental": "node --env-file-if-exists=.env --import tsx scripts/incrementalCheck.ts",
     "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run"
   },
   "dependencies": {
-    "@shapio/client": "^0.5.1",
-    "@shapio/visual": "^0.5.1",
+    "@shapio/client": "^0.5.3",
+    "@shapio/visual": "^0.5.3",
     "astro": "7.3.5"
   },
   "devDependencies": {

package/templates/astro/scripts/incrementalBuild.ts

@@ -1,10 +1,12 @@
 import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { createClient, ShapioApiError, type SnapshotChange } from '@shapio/client';
 
 /**
- * `npm run build:incremental [--dry-run]`: builds only when content changed.
+ * `npm run build:incremental [--dry-run]`: skips a build that would change nothing. A local and CI tool, for
+ * machines where `dist/` survives between builds.
  *
  * It asks Shapio what changed between the snapshot the last build showed (`dist/build.json`, or
  * SHAPIO_FROM_SNAPSHOT) and the current one (`/api/snapshots/changes`), prints the routes those changes
@@ -12,6 +14,11 @@ import { createClient, ShapioApiError, type SnapshotChange } from '@shapio/clien
  * schema change between the two snapshots, or no previous build, means a full rebuild. The printed routes
  * are what a server-rendered site would revalidate (documentation/snapshots.md shows `revalidatePath`).
  *
+ * The per-page work is Astro's: the build itself restores every page whose data and code are unchanged
+ * (`experimental.incrementalBuild`, src/lib/cacheKey.ts). This script only decides whether to build at all, and
+ * it never skips without a `dist/` to keep: on a host that starts every build from a fresh checkout (Cloudflare
+ * Pages, Netlify), a skipped build would leave nothing to deploy, so there it always builds.
+ *
  * Settings: SHAPIO_URL and SHAPIO_DELIVERY_TOKEN (as for `npm run build`), SHAPIO_FROM_SNAPSHOT (optional).
  */
 const DIST_BUILD_INFO = resolve(import.meta.dirname, '../dist/build.json');
@@ -66,6 +73,13 @@ const slugAt = async (change: SnapshotChange, locale: string, snapshot: number):
   }
 };
 
+/**
+ * The models whose entries have a route of their own, found by slug. Any other model (a redirect type a user
+ * adds, say) maps to no route here: it may have no `slug` field, and Astro's incremental build still decides
+ * page by page what to rebuild.
+ */
+const SLUG_ROUTED_MODELS = new Set(['page', 'article']);
+
 /** Site routes (src/pages) an entry change touches. */
 const routesOf = async (change: SnapshotChange, from: number, to: number): Promise<string[]> => {
   const routes: string[] = [];
@@ -74,6 +88,9 @@ const routesOf = async (change: SnapshotChange, from: number, to: number): Promi
       routes.push(`/${locale}/articles/`);
       continue;
     }
+    if (!SLUG_ROUTED_MODELS.has(change.modelKey)) {
+      continue;
+    }
     // An unpublished entry's route is where it was; the others are where they are now.
     const slug = await slugAt(change, locale, kind === 'unpublished' ? from : to);
     if (slug === null) {
@@ -108,7 +125,10 @@ const main = async () => {
   const say = (line: string) => process.stdout.write(`${line}\n`);
 
   if (from === undefined) {
-    say(`No previous build: building everything at snapshot ${to}.`);
+    say(`No previous build: building at snapshot ${to}.`);
+  } else if (!existsSync(DIST_BUILD_INFO)) {
+    // SHAPIO_FROM_SNAPSHOT without the build it names: skipping would leave no dist/ to deploy.
+    say(`No dist/ from snapshot ${from} here: building at snapshot ${to}.`);
   } else if (from === to) {
     say(`Nothing published since snapshot ${from}: skipping the build.`);
     return;
@@ -125,7 +145,9 @@ const main = async () => {
       for (const change of diff.items) {
         (await routesOf(change, from, to)).forEach((route) => routes.add(route));
       }
-      say(`Snapshots ${from} → ${to}: ${diff.items.length} changed entries; routes to refresh:`);
+      say(
+        `Snapshots ${from} → ${to}: ${diff.items.length} changed entries; the routes they touch (the build re-renders only pages whose data changed):`,
+      );
       [...routes].sort().forEach((route) => say(`  ${route}`));
     }
   }

package/templates/astro/scripts/incrementalCheck.ts

@@ -0,0 +1,218 @@
+import { spawn } from 'node:child_process';
+import { cp, mkdtemp, readdir, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, relative, resolve } from 'node:path';
+import { createClient } from '@shapio/client';
+import { connectAdmin, type AdminConnection } from './lib/admin.js';
+
+/**
+ * `npm run check:incremental`, after `npm run seed`: checks Astro's incremental build end to end against a running
+ * Shapio. Each step runs `astro build`:
+ * 1. a full build (`--force`), kept as the reference;
+ * 2. the same snapshot again: every keyed page is restored, and dist/ matches the reference except build.json
+ *    (its `builtAt` changes on every build);
+ * 3. the same content pinned with SHAPIO_SNAPSHOT (as a webhook-triggered build is): every keyed page is still
+ *    restored, so no setting's value leaks into the code Astro hashes;
+ * 4. one article's English title edited and published: only that page re-renders among the keyed ones, with the
+ *    new title (the title is put back afterwards);
+ * 5. the cache removed: a full build, nothing restored.
+ * Changes content (and puts it back): run it after anything else that reads the seeded site. Needs
+ * SHAPIO_ADMIN_EMAIL and SHAPIO_ADMIN_PASSWORD (or SHAPIO_TOKEN) to publish the edit, as the seed does.
+ */
+const ROOT = resolve(import.meta.dirname, '..');
+const DIST = join(ROOT, 'dist');
+const CACHE_DIR = join(ROOT, 'node_modules', '.astro');
+const MANIFEST = join(CACHE_DIR, 'incremental-build.json');
+const ARTICLE = 'modelling-without-a-deploy';
+const EDITED_PAGE = `en/articles/${ARTICLE}/index.html`;
+/** Always rendered, and carries the build time: the only file two builds of one snapshot may differ in. */
+const TIMESTAMPED = new Set(['build.json']);
+/** How long a publish may take to become the current snapshot: polled, so a fast server costs nothing. */
+const SNAPSHOT_WITHIN_MS = 30_000;
+const POLL_EVERY_MS = 250;
+
+const failures: string[] = [];
+const check = (condition: boolean, message: string) => {
+  process.stdout.write(`${condition ? 'ok  ' : 'FAIL'} ${message}\n`);
+  if (!condition) {
+    failures.push(message);
+  }
+};
+const say = (line: string) => process.stdout.write(`${line}\n`);
+
+/** Runs `astro build` (with `npm run build`, as a site's host does) and returns its output. */
+const build = (args: string[] = [], env: NodeJS.ProcessEnv = {}) =>
+  new Promise<string>((resolveBuild, reject) => {
+    const child = spawn('npm', ['run', 'build', '--', ...args], {
+      cwd: ROOT,
+      env: { ...process.env, ...env, FORCE_COLOR: '0', NO_COLOR: '1' },
+    });
+    let output = '';
+    child.stdout.on('data', (chunk: Buffer) => (output += chunk.toString()));
+    child.stderr.on('data', (chunk: Buffer) => (output += chunk.toString()));
+    child.on('error', reject);
+    child.on('exit', (code) =>
+      code === 0 ? resolveBuild(output) : reject(new Error(`astro build exited with ${code}:\n${output}`)),
+    );
+  });
+
+type Manifest = { routes: Record<string, { paths: Record<string, { outputFile: string }> }> };
+
+/** The output files of every keyed page (a page whose getStaticPaths entry has a cacheKey). */
+const keyedFiles = async (): Promise<string[]> => {
+  const manifest = JSON.parse(await readFile(MANIFEST, 'utf8')) as Manifest;
+  return Object.values(manifest.routes)
+    .flatMap((route) => Object.values(route.paths).map((path) => path.outputFile))
+    .sort();
+};
+
+/** How a build treated each keyed page: Astro logs `├─ /<file> (restored)` for one it did not render. */
+const outcomes = (output: string, files: string[]) => {
+  const lines = output.split('\n');
+  const restored = files.filter((file) =>
+    lines.some((line) => line.includes(` /${file} `) && /\((restored|cached)\)/.test(line)),
+  );
+  return { restored, rendered: files.filter((file) => !restored.includes(file)) };
+};
+
+const listTree = async (root: string): Promise<string[]> =>
+  (await readdir(root, { recursive: true, withFileTypes: true }))
+    .filter((entry) => entry.isFile())
+    .map((entry) => relative(root, join(entry.parentPath, entry.name)).split('\\').join('/'))
+    .sort();
+
+/** Files that differ between two output directories (missing on either side, or different bytes). */
+const differences = async (left: string, right: string): Promise<string[]> => {
+  const [a, b] = await Promise.all([listTree(left), listTree(right)]);
+  const all = [...new Set([...a, ...b])].sort();
+  const differing: string[] = [];
+  for (const file of all) {
+    if (!a.includes(file) || !b.includes(file)) {
+      differing.push(file);
+      continue;
+    }
+    const [x, y] = await Promise.all([readFile(join(left, file)), readFile(join(right, file))]);
+    if (!x.equals(y)) {
+      differing.push(file);
+    }
+  }
+  return differing;
+};
+
+const delivery = () => {
+  const token = process.env.SHAPIO_DELIVERY_TOKEN;
+  if (!token) {
+    throw new Error('Set SHAPIO_DELIVERY_TOKEN (npm run seed writes it to .env)');
+  }
+  return createClient({ baseUrl: process.env.SHAPIO_URL ?? 'http://localhost:4300', token });
+};
+
+/** Waits until the current snapshot is past `after` (a real condition, not a fixed wait). */
+const waitForSnapshotAfter = async (after: number) => {
+  const deadline = Date.now() + SNAPSHOT_WITHIN_MS;
+  while (Date.now() < deadline) {
+    const { snapshot } = await delivery().snapshots.current();
+    if (snapshot > after) {
+      return snapshot;
+    }
+    await new Promise((resolveWait) => setTimeout(resolveWait, POLL_EVERY_MS));
+  }
+  throw new Error(`No snapshot after ${after} within ${SNAPSHOT_WITHIN_MS} ms of publishing`);
+};
+
+/** Saves and publishes the article's English title; returns a function that publishes the old one again. */
+const publishTitle = async ({ client }: AdminConnection, title: string) => {
+  const [item] = (
+    await client.admin.content.list('article', { locale: 'en', filters: { slug: { $eq: ARTICLE } } })
+  ).items;
+  if (!item) {
+    throw new Error(`The seeded article "${ARTICLE}" is missing; run npm run seed first`);
+  }
+  const entry = await client.admin.content.get('article', item.id, { locale: 'en' });
+  const original = entry.data.title;
+  const publish = async (expectedVersion: number, value: unknown) => {
+    const before = (await delivery().snapshots.current()).snapshot;
+    const saved = await client.admin.content.update('article', item.id, {
+      locale: 'en',
+      expectedVersion,
+      data: { title: value },
+    });
+    await client.admin.content.publish('article', item.id, { locales: ['en'] });
+    await waitForSnapshotAfter(before);
+    return saved.version;
+  };
+  const version = await publish(entry.version, title);
+  return () => publish(version, original);
+};
+
+const main = async () => {
+  const reference = await mkdtemp(join(tmpdir(), 'shapio-astro-incremental-'));
+  const admin = await connectAdmin(process.env);
+  try {
+    say('1. Full build (--force)');
+    await build(['--force']);
+    await cp(DIST, reference, { recursive: true });
+    const keyed = await keyedFiles();
+    check(keyed.length > 0, `${keyed.length} keyed pages recorded in the cache`);
+
+    say('2. The same snapshot again');
+    const second = outcomes(await build(), keyed);
+    check(
+      second.rendered.length === 0,
+      `${second.restored.length}/${keyed.length} keyed pages restored${second.rendered.length > 0 ? `; rendered: ${second.rendered.join(', ')}` : ''}`,
+    );
+    const changed = await differences(reference, DIST);
+    check(
+      changed.every((file) => TIMESTAMPED.has(file)),
+      `dist/ matches the full build except build.json (differs: ${changed.join(', ') || 'nothing'})`,
+    );
+
+    say('3. The same content, pinned with SHAPIO_SNAPSHOT');
+    const { snapshot } = await delivery().snapshots.current();
+    const pinned = outcomes(await build([], { SHAPIO_SNAPSHOT: String(snapshot) }), keyed);
+    check(
+      pinned.rendered.length === 0,
+      `${pinned.restored.length}/${keyed.length} keyed pages restored with SHAPIO_SNAPSHOT=${snapshot}${pinned.rendered.length > 0 ? `; rendered: ${pinned.rendered.join(', ')}` : ''}`,
+    );
+
+    say('4. One article edited and published');
+    const marker = `Incremental check ${Date.now()}`;
+    const restore = await publishTitle(admin, marker);
+    try {
+      const third = outcomes(await build(), keyed);
+      check(
+        third.rendered.length === 1 && third.rendered[0] === EDITED_PAGE,
+        `only ${EDITED_PAGE} re-rendered among keyed pages (rendered: ${third.rendered.join(', ') || 'none'}; restored ${third.restored.length})`,
+      );
+      check(
+        (await readFile(join(DIST, EDITED_PAGE), 'utf8')).includes(marker),
+        `${EDITED_PAGE} has the new title`,
+      );
+    } finally {
+      await restore();
+    }
+
+    say('5. No cache');
+    await rm(CACHE_DIR, { recursive: true, force: true });
+    const fourth = await build();
+    check(!/\((restored|cached)\)/.test(fourth), 'a build without the cache renders every page');
+    const afterRestore = await differences(reference, DIST);
+    check(
+      afterRestore.every((file) => TIMESTAMPED.has(file)),
+      `with the title put back, dist/ matches the first build except build.json (differs: ${afterRestore.join(', ') || 'nothing'})`,
+    );
+  } finally {
+    await admin.close();
+    await rm(reference, { recursive: true, force: true });
+  }
+
+  if (failures.length > 0) {
+    throw new Error(`${failures.length} check(s) failed`);
+  }
+  say('Incremental build check passed.');
+};
+
+main().catch((error: unknown) => {
+  process.stderr.write(`check:incremental: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});

package/templates/astro/src/layouts/Base.astro

@@ -1,9 +1,8 @@
 ---
 import '../styles/site.css';
 import type { SeoResolved } from '@shapio/client';
-import { isDraftsMode } from '../lib/config.js';
+import { layoutInputs } from '../lib/layoutInputs.js';
 import { seoHead, type SeoHead } from '../lib/seo.js';
-import { getSite, getSiteSettings } from '../lib/shapio.js';
 import {
   articlesPath,
   colophonPath,
@@ -31,12 +30,13 @@ const { title, seo, type, locale, alternatePath, noindex = false } = Astro.props
 const strings = stringsFor(locale);
 const other = otherLocale(locale);
 // The name, tagline and footer come from the siteSettings singleton (the built-in strings until it is published).
-const settings = await getSiteSettings(locale);
+// Read through layoutInputs, which keyed pages fold into their cacheKey (src/lib/cacheKey.ts).
+const { settings, site, env } = await layoutInputs(locale);
 const siteName = settings?.siteName ?? strings.siteName;
 // Title, description, social tags and canonical: the entry's SEO fields over the site's SEO defaults.
 const head = seoHead({
   seo: seo ?? null,
-  site: await getSite(),
+  site,
   locale,
   localeChain: [locale, DEFAULT_LOCALE],
   title,
@@ -92,7 +92,7 @@ const robotsNoindex = noindex || head.noindex;
       <p>{siteName} · {settings?.footer ?? 'Built with Shapio'} · Astro</p>
     </footer>
     {
-      isDraftsMode() ? (
+      env.drafts ? (
         <p class="drafts-badge" title={strings.draftsNote} data-shapio-drafts="">
           {strings.drafts}
         </p>

package/templates/astro/src/lib/cacheKey.test.ts

@@ -0,0 +1,63 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { buildEnvKey, cacheKeyOf } from './cacheKey.js';
+
+describe('cacheKeyOf', () => {
+  it('is a 32-character hex digest', () => {
+    expect(cacheKeyOf({ title: 'Hello' })).toMatch(/^[0-9a-f]{32}$/);
+  });
+
+  it('does not depend on the order of object keys, at any depth', () => {
+    expect(cacheKeyOf({ a: 1, b: { c: 2, d: [{ e: 3, f: 4 }] } })).toBe(
+      cacheKeyOf({ b: { d: [{ f: 4, e: 3 }], c: 2 }, a: 1 }),
+    );
+  });
+
+  it('changes when any nested value changes', () => {
+    const page = { title: 'Home', sections: [{ heading: 'Hi', image: { url: '/a.webp' } }] };
+    const edited = { title: 'Home', sections: [{ heading: 'Hi', image: { url: '/b.webp' } }] };
+    expect(cacheKeyOf(page)).not.toBe(cacheKeyOf(edited));
+  });
+
+  it('is sensitive to array order', () => {
+    expect(cacheKeyOf([1, 2])).not.toBe(cacheKeyOf([2, 1]));
+  });
+
+  it('tells its inputs apart (a value moved from one argument to the next is a different key)', () => {
+    expect(cacheKeyOf({ a: 1 }, { b: 2 })).not.toBe(cacheKeyOf({ a: 1, b: 2 }));
+  });
+
+  it('reads undefined as null and a date as its ISO text', () => {
+    expect(cacheKeyOf({ a: undefined })).toBe(cacheKeyOf({ a: null }));
+    expect(cacheKeyOf({ at: new Date('2026-10-07T00:00:00.000Z') })).toBe(
+      cacheKeyOf({ at: '2026-10-07T00:00:00.000Z' }),
+    );
+  });
+
+  it('throws on what is not plain data, naming where it is', () => {
+    expect(() => cacheKeyOf({ render: () => '' })).toThrow('inputs[0].render is a function');
+    expect(() => cacheKeyOf({ id: Symbol('x') })).toThrow('is a symbol');
+    expect(() => cacheKeyOf({ size: 1n })).toThrow('is a bigint');
+    expect(() => cacheKeyOf({ tags: new Set(['a']) })).toThrow('is a Set');
+  });
+
+  it('throws on a value that refers back to itself, but accepts the same object twice', () => {
+    const shared = { name: 'Ada' };
+    expect(() => cacheKeyOf({ author: shared, editor: shared })).not.toThrow();
+    const loop: Record<string, unknown> = {};
+    loop.self = loop;
+    expect(() => cacheKeyOf(loop)).toThrow('refers back to itself');
+  });
+});
+
+describe('buildEnvKey', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('carries drafts mode and the year, which a page shows without reading them from its data', () => {
+    vi.stubEnv('SHAPIO_DRAFTS', 'true');
+    expect(buildEnvKey()).toEqual({ drafts: true, year: new Date().getFullYear() });
+    vi.stubEnv('SHAPIO_DRAFTS', '');
+    expect(buildEnvKey().drafts).toBe(false);
+  });
+});

package/templates/astro/src/lib/cacheKey.ts

@@ -0,0 +1,57 @@
+import { createHash } from 'node:crypto';
+import { isDraftsMode } from './config.js';
+
+/**
+ * Keys for Astro's incremental build (`experimental.incrementalBuild` in astro.config.mjs). A page returned by
+ * `getStaticPaths()` with a `cacheKey` is restored from the previous build, not rendered, when its key and its
+ * code (Astro hashes the page's import graph) are both unchanged. So the key must cover every piece of data the
+ * page renders: its props, what the layout reads (`layoutInputs`), and the build environment (`buildEnvKey`).
+ * Whole objects go in, never a hand-picked list of fields, which would drift from what the page renders.
+ */
+
+/** Plain data in a stable form: object keys sorted, arrays in order, `undefined` as null, dates as ISO text. */
+const normalize = (value: unknown, path: string, seen: Set<object>): unknown => {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return value;
+  }
+  if (typeof value === 'function' || typeof value === 'symbol' || typeof value === 'bigint') {
+    throw new TypeError(`cacheKeyOf: ${path} is a ${typeof value}, not plain data`);
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  const object = value;
+  if (seen.has(object)) {
+    throw new TypeError(`cacheKeyOf: ${path} refers back to itself`);
+  }
+  seen.add(object);
+  try {
+    if (Array.isArray(object)) {
+      return object.map((item, index) => normalize(item, `${path}[${index}]`, seen));
+    }
+    const prototype = Object.getPrototypeOf(object) as unknown;
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new TypeError(`cacheKeyOf: ${path} is a ${object.constructor.name}, not plain data`);
+    }
+    const entries = Object.entries(object).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return Object.fromEntries(entries.map(([key, item]) => [key, normalize(item, `${path}.${key}`, seen)]));
+  } finally {
+    seen.delete(object);
+  }
+};
+
+/** A stable digest of the data a page renders: same inputs, same key, whatever the order of object keys. */
+export const cacheKeyOf = (...inputs: unknown[]): string =>
+  createHash('sha256')
+    .update(JSON.stringify(normalize(inputs, 'inputs', new Set())))
+    .digest('hex')
+    .slice(0, 32);
+
+/**
+ * What a page shows that comes from neither its data nor its code: settings read from the environment and the
+ * clock when it renders, which Astro's code and config hashes do not see.
+ */
+export const buildEnvKey = () => ({ drafts: isDraftsMode(), year: new Date().getFullYear() });

package/templates/astro/src/lib/config.ts

@@ -10,10 +10,13 @@
  *   instead of published content (no snapshot), and pages carry a "Drafts" badge. The token must be a delivery
  *   token whose role grants Read drafts: SHAPIO_DEV_DELIVERY_TOKEN when set (`npm run seed` writes one), else
  *   SHAPIO_DELIVERY_TOKEN. Never set it in a production environment.
+ *
+ * Settings come from `process.env` only (astro.config.mjs loads `.env` into it). Reading Vite's env object as a
+ * whole instead would make Vite write every variable named in this file into the compiled code, so a changed
+ * SHAPIO_SNAPSHOT would change the code Astro hashes and re-render every page (see src/lib/cacheKey.ts).
  */
 const read = (name: string): string | undefined => {
-  const fromVite = (import.meta as { env?: Record<string, string | undefined> }).env?.[name];
-  const value = fromVite ?? process.env[name];
+  const value = process.env[name];
   return value === undefined || value === '' ? undefined : value;
 };
 
@@ -50,5 +53,20 @@ export const publicShapioUrl = () => read('PUBLIC_SHAPIO_URL') ?? shapioUrl();
 
 export const siteKey = () => read('SHAPIO_SITE');
 
-/** True under `astro dev` (Vite's import.meta.env.DEV); false in builds and in the scripts. */
-export const isDev = () => (import.meta as { env?: { DEV?: boolean } }).env?.DEV === true;
+type ViteImportMeta = ImportMeta & { env: { DEV?: boolean } };
+
+/**
+ * True under `astro dev`; false in builds and in the scripts. Written out in full (`import.meta.env.DEV`) so Vite
+ * replaces it with a constant; outside Vite (the scripts, run by Node) there is no env object, which is the
+ * TypeError caught here, and that is not dev.
+ */
+export const isDev = (): boolean => {
+  try {
+    return (import.meta as ViteImportMeta).env.DEV === true;
+  } catch (error) {
+    if (error instanceof TypeError) {
+      return false;
+    }
+    throw error;
+  }
+};

package/templates/astro/src/lib/layoutInputs.ts

@@ -0,0 +1,13 @@
+import { buildEnvKey } from './cacheKey.js';
+import { getSite, getSiteSettings } from './shapio.js';
+import type { Locale } from './site.js';
+
+/**
+ * Everything layouts/Base.astro reads when it renders, besides its props: the site settings and the site's SEO
+ * defaults (both read once per build) and the build environment. The layout reads through this function and
+ * every keyed page folds it into its `cacheKey`, so a read added to the layout is in the key too.
+ */
+export const layoutInputs = async (locale: Locale) => {
+  const [settings, site] = await Promise.all([getSiteSettings(locale), getSite()]);
+  return { settings, site, env: buildEnvKey() };
+};

package/templates/astro/src/lib/shapio.ts

@@ -64,17 +64,22 @@ export const pinnedSnapshot = async (): Promise<number | undefined> => {
   return resolver();
 };
 
-/** Every published entry of a collection (by plural API ID) in one locale, page by page, at the pinned snapshot. */
-const listAll = async <T>(routeKey: string, query: DeliveryListQuery): Promise<T[]> => {
+/**
+ * Every published entry of a collection (by plural API ID) in one locale, page by page, at the pinned snapshot.
+ * The defaults (server-rendered HTML, SEO fields resolved) apply unless the query overrides them: a collection
+ * without SEO fields (a redirect type, say) is read with `{ seo: 'raw' }`, since Shapio refuses `seo=resolved`
+ * for a model that has none.
+ */
+export const listAll = async <T>(routeKey: string, query: DeliveryListQuery): Promise<T[]> => {
   const snapshot = await pinnedSnapshot();
   const entries: T[] = [];
   for (let page = 1; ; page += 1) {
     const result = await shapio().delivery.list<T>(routeKey, {
-      ...query,
       // The site renders the server's sanitized HTML, so it asks for that instead of the JSON document, and
       // its SEO fields with the site's defaults filled in (`seo=resolved`).
       richText: 'html',
       seo: 'resolved',
+      ...query,
       snapshot,
       page,
       pageSize: PAGE_SIZE,

package/templates/astro/src/pages/[locale]/[...slug].astro

@@ -1,20 +1,29 @@
 ---
 import Base from '../../layouts/Base.astro';
+import { cacheKeyOf } from '../../lib/cacheKey.js';
 import { isDev } from '../../lib/config.js';
+import { layoutInputs } from '../../lib/layoutInputs.js';
 import { renderPage } from '../../lib/render.js';
 import { findBySlug, renderTimeEntry } from '../../lib/renderTime.js';
 import { listPages } from '../../lib/shapio.js';
 import { HOME_SLUG, LOCALES, otherLocale, pagePath, type Locale } from '../../lib/site.js';
 import type { Page } from '../../lib/types.js';
 
-/** Every published page in every locale; `home` is the locale's front page (`/en/`, `/fr/`). */
+/**
+ * Every published page in every locale; `home` is the locale's front page (`/en/`, `/fr/`). The page renders
+ * only its props and what the layout reads, so those are its cacheKey: a build restores it from the previous
+ * build while they are unchanged (src/lib/cacheKey.ts).
+ */
 export const getStaticPaths = async () => {
   const paths = [];
   for (const locale of LOCALES) {
+    const layout = await layoutInputs(locale);
     for (const page of await listPages(locale)) {
+      const props = { page, locale };
       paths.push({
         params: { locale, slug: page.slug === HOME_SLUG ? undefined : page.slug },
-        props: { page, locale },
+        props,
+        cacheKey: cacheKeyOf(props, layout),
       });
     }
   }

package/templates/astro/src/pages/[locale]/articles/[slug].astro

@@ -1,17 +1,26 @@
 ---
 import Base from '../../../layouts/Base.astro';
+import { cacheKeyOf } from '../../../lib/cacheKey.js';
 import { isDev } from '../../../lib/config.js';
+import { layoutInputs } from '../../../lib/layoutInputs.js';
 import { renderArticle } from '../../../lib/render.js';
 import { findBySlug, renderTimeEntry } from '../../../lib/renderTime.js';
 import { listArticles } from '../../../lib/shapio.js';
 import { articlePath, LOCALES, otherLocale, stringsFor, type Locale } from '../../../lib/site.js';
 import type { Article } from '../../../lib/types.js';
 
+/**
+ * Every published article in every locale. The page renders only its props (the author arrives populated inside
+ * the article; the strings are in the code) and what the layout reads, so those are its cacheKey: a build
+ * restores it from the previous build while they are unchanged (src/lib/cacheKey.ts).
+ */
 export const getStaticPaths = async () => {
   const paths = [];
   for (const locale of LOCALES) {
+    const layout = await layoutInputs(locale);
     for (const article of await listArticles(locale)) {
-      paths.push({ params: { locale, slug: article.slug }, props: { locale, article } });
+      const props = { locale, article };
+      paths.push({ params: { locale, slug: article.slug }, props, cacheKey: cacheKeyOf(props, layout) });
     }
   }
   return paths;

package/templates/astro/src/pages/[locale]/articles/index.astro

@@ -7,6 +7,7 @@ import { listArticles } from '../../../lib/shapio.js';
 import { articlesPath, LOCALES, otherLocale, stringsFor, type Locale } from '../../../lib/site.js';
 import type { Article } from '../../../lib/types.js';
 
+// No cacheKey: the listing renders on every build (it shows every article, so most publishes change it).
 export const getStaticPaths = async () =>
   Promise.all(
     LOCALES.map(async (locale) => ({ params: { locale }, props: { locale, articles: await listArticles(locale) } })),

package/templates/astro/src/pages/[locale]/colophon.astro

@@ -3,7 +3,7 @@ import Base from '../../layouts/Base.astro';
 import { getSiteSettings } from '../../lib/shapio.js';
 import { colophonPath, LOCALES, otherLocale, stringsFor, type Locale } from '../../lib/site.js';
 
-/** The singleton page: the siteSettings entry's colophon, one per locale. */
+/** The singleton page: the siteSettings entry's colophon, one per locale. No cacheKey: it renders on every build. */
 export const getStaticPaths = () => LOCALES.map((locale) => ({ params: { locale }, props: { locale } }));
 
 type Props = { locale: Locale };

package/templates/next/package.json

@@ -18,9 +18,9 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@shapio/client": "^0.5.1",
-    "@shapio/local": "0.5.1",
-    "@shapio/visual": "^0.5.1",
+    "@shapio/client": "^0.5.3",
+    "@shapio/local": "0.5.3",
+    "@shapio/visual": "^0.5.3",
     "next": "16.3.8",
     "react": "19.3.0",
     "react-dom": "19.3.0"

package/templates/next/src/lib/shapio.ts

@@ -58,16 +58,21 @@ const snapshot = async (): Promise<number | undefined> =>
         }))()
       : liveSnapshot();
 
-/** Every published entry of a collection in one locale, page by page, at the pinned snapshot. */
-const listAll = async <T>(routeKey: string, query: DeliveryListQuery): Promise<T[]> => {
+/**
+ * Every published entry of a collection in one locale, page by page, at the pinned snapshot.
+ * The defaults (server-rendered HTML, SEO fields resolved) apply unless the query overrides them: a collection
+ * without SEO fields (a redirect type, say) is read with `{ seo: 'raw' }`, since Shapio refuses `seo=resolved`
+ * for a model that has none.
+ */
+export const listAll = async <T>(routeKey: string, query: DeliveryListQuery): Promise<T[]> => {
   const entries: T[] = [];
   for (let page = 1; ; page += 1) {
     const result = await shapio().delivery.list<T>(routeKey, {
-      ...query,
       // The site renders the server's sanitized HTML, so it asks for that instead of the JSON document, and
       // its SEO fields with the site's defaults filled in.
       richText: 'html',
       seo: 'resolved',
+      ...query,
       snapshot: await snapshot(),
       page,
       pageSize: PAGE_SIZE,

package/templates/sveltekit/package.json

@@ -23,8 +23,8 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@shapio/client": "^0.5.1",
-    "@shapio/visual": "^0.5.1"
+    "@shapio/client": "^0.5.3",
+    "@shapio/visual": "^0.5.3"
   },
   "devDependencies": {
     "@sveltejs/adapter-static": "4.0.0",

package/templates/sveltekit/src/lib/server/shapio.ts

@@ -57,16 +57,21 @@ const once = <T>(key: string, read: () => Promise<T>): Promise<T> => {
   return cached();
 };
 
-/** Every published entry of a collection in one locale, page by page, at the pinned snapshot. */
-const listAll = async <T>(routeKey: string, query: DeliveryListQuery): Promise<T[]> => {
+/**
+ * Every published entry of a collection in one locale, page by page, at the pinned snapshot.
+ * The defaults (server-rendered HTML, SEO fields resolved) apply unless the query overrides them: a collection
+ * without SEO fields (a redirect type, say) is read with `{ seo: 'raw' }`, since Shapio refuses `seo=resolved`
+ * for a model that has none.
+ */
+export const listAll = async <T>(routeKey: string, query: DeliveryListQuery): Promise<T[]> => {
   const entries: T[] = [];
   for (let page = 1; ; page += 1) {
     const result = await shapio().delivery.list<T>(routeKey, {
-      ...query,
       // The site renders the server's sanitized HTML, so it asks for that instead of the JSON document, and
       // its SEO fields with the site's defaults filled in.
       richText: 'html',
       seo: 'resolved',
+      ...query,
       snapshot: await snapshot(),
       page,
       pageSize: PAGE_SIZE,