create-shapio 0.4.1 → 0.5.1

package/templates/next/scripts/seed.ts

@@ -40,13 +40,16 @@ import { createPng } from './lib/png.js';
  * 5. with `--revalidate-path` (the Next.js starter's /api/revalidate), a webhook named "Site revalidation" that
  *    sends publish, unpublish, delete, change set and schema events to SITE_URL + that path; its signing secret
  *    (rotated on every run, as Shapio shows it only once) is written to .env as SHAPIO_WEBHOOK_SECRET;
- * 6. a delivery role and token for the build, written with SHAPIO_URL to .env in the current directory.
+ * 6. a delivery role and token for the build, written with SHAPIO_URL to .env in the current directory;
+ * 7. a second delivery role and token for development servers, "<site> dev", that may also read drafts (drafts
+ *    mode: SHAPIO_DRAFTS=true), written to .env as SHAPIO_DEV_DELIVERY_TOKEN. Never put it in production.
  */
 const SCHEMA_DIR = resolve(import.meta.dirname, '..', 'shapio');
 const SCHEMA_KINDS = ['models', 'components'] as const;
 const SITE_MODELS = ['page', 'article', 'author', 'siteSettings'];
 const DELIVERY_ROLE_KEY = 'starter-delivery';
 const DELIVERY_TOKEN_NAME = 'starter build';
+const DEV_ROLE_KEY = 'starter-dev';
 const PREVIEW_CONNECTION_NAME = 'Preview';
 /** Where Shapio opens a draft: the starter's /preview/ page, the token in the fragment (never sent to a server). */
 const PREVIEW_PATH = '/preview/?model={modelKey}&id={entryId}&locale={locale}#token={token}';
@@ -308,35 +311,71 @@ const upsertEntry = async (client: ShapioClient, spec: EntrySpec) => {
   log(`${spec.publish ? 'Published' : 'Saved draft'} ${spec.model} ${spec.slug} (en, fr)`);
 };
 
-/** A delivery role that reads the site's models, and a fresh token bound to it (older ones are revoked). */
-const createDeliveryToken = async (client: ShapioClient) => {
+type DeliveryRoleSpec = {
+  key: string;
+  name: string;
+  description: string;
+  tokenName: string;
+  drafts: boolean;
+};
+
+/**
+ * A delivery role that reads the site's models (and, for development servers, their drafts), and a fresh token
+ * bound to it (older ones of the same name are revoked).
+ */
+const createDeliveryToken = async (client: ShapioClient, spec: DeliveryRoleSpec) => {
   const summary = await client.admin.schema.summary();
   const modelIds = summary.definitions
     .filter((definition) => SITE_MODELS.includes(definition.apiKey))
     .map((definition) => definition.id);
-  const permissions = modelIds.map((modelId) => ({
-    action: 'read' as const,
-    modelId,
-    condition: null,
-    fieldIds: null,
-  }));
+  const grant = { condition: null, fieldIds: null };
+  const permissions = [
+    ...modelIds.map((modelId) => ({ action: 'read' as const, modelId, ...grant })),
+    // Read drafts always covers every model; the role still reads only the models above.
+    ...(spec.drafts ? [{ action: 'readDrafts' as const, modelId: null, ...grant }] : []),
+  ];
   const roles = await client.admin.roles.list();
-  const existing = roles.find((role) => role.key === DELIVERY_ROLE_KEY);
+  const existing = roles.find((role) => role.key === spec.key);
   const role = existing
     ? await client.admin.roles.update(existing.id, { expectedVersion: existing.version, permissions })
     : await client.admin.roles.create({
-        key: DELIVERY_ROLE_KEY,
-        name: 'Starter site (delivery)',
-        description: 'Reads published pages, articles, authors and the site settings for the starter build.',
+        key: spec.key,
+        name: spec.name,
+        description: spec.description,
         kind: 'delivery',
         permissions,
       });
   for (const token of await client.admin.tokens.list()) {
-    if (token.name === DELIVERY_TOKEN_NAME && !token.revokedAt) {
+    if (token.name === spec.tokenName && !token.revokedAt) {
       await client.admin.tokens.revoke(token.id);
     }
   }
-  return (await client.admin.tokens.create({ name: DELIVERY_TOKEN_NAME, roleId: role.id })).token;
+  return (await client.admin.tokens.create({ name: spec.tokenName, roleId: role.id })).token;
+};
+
+const BUILD_ROLE: DeliveryRoleSpec = {
+  key: DELIVERY_ROLE_KEY,
+  name: 'Starter site (delivery)',
+  description: 'Reads published pages, articles, authors and the site settings for the starter build.',
+  tokenName: DELIVERY_TOKEN_NAME,
+  drafts: false,
+};
+
+/** The development token's role: the build role plus Read drafts. Named after the site it reads. */
+const devRole = (siteName: string): DeliveryRoleSpec => ({
+  key: DEV_ROLE_KEY,
+  name: 'Starter site dev (drafts)',
+  description:
+    'Reads the starter models and their drafts, for development servers (drafts mode). Never use its tokens in production.',
+  tokenName: `${siteName} dev`,
+  drafts: true,
+});
+
+/** The name of the site the seed works on: SHAPIO_SITE, else the primary site. */
+const siteNameOf = async (client: ShapioClient, siteKey: string | undefined) => {
+  const sites = await client.admin.sites.list();
+  const site = sites.find((candidate) => (siteKey ? candidate.key === siteKey : candidate.isPrimary));
+  return site?.name ?? siteKey ?? 'site';
 };
 
 /** The "Preview" connection, created once and pointed at this starter's /preview/ page on every run. */
@@ -402,24 +441,30 @@ const tryRevalidateWebhook = async (client: ShapioClient, siteUrl: string, path:
   }
 };
 
-const writeEnv = async (
-  url: string,
-  site: string | undefined,
-  deliveryToken: string,
-  webhookSecret: string | undefined,
-) => {
+type SeededEnv = {
+  url: string;
+  site: string | undefined;
+  deliveryToken: string;
+  devDeliveryToken: string;
+  webhookSecret: string | undefined;
+};
+
+const writeEnv = async ({ url, site, deliveryToken, devDeliveryToken, webhookSecret }: SeededEnv) => {
   const path = resolve('.env');
   const lines = [
-    '# Written by the seed. The delivery token is read-only; keep this file out of git.',
+    '# Written by the seed. The delivery tokens are read-only; keep this file out of git.',
     `SHAPIO_URL=${url}`,
     `SHAPIO_DELIVERY_TOKEN=${deliveryToken}`,
+    '# Development only: drafts mode (SHAPIO_DRAFTS=true) reads with this token, which may read drafts.',
+    '# Never put it in a production environment.',
+    `SHAPIO_DEV_DELIVERY_TOKEN=${devDeliveryToken}`,
     // The site the content was seeded on: the starter reads the same one.
     ...(site ? [`SHAPIO_SITE=${site}`] : []),
     ...(webhookSecret ? [`SHAPIO_WEBHOOK_SECRET=${webhookSecret}`] : []),
   ];
   await writeFile(path, `${lines.join('\n')}\n`, { mode: 0o600 });
   log(
-    `Wrote SHAPIO_URL, ${site ? 'SHAPIO_SITE, ' : ''}SHAPIO_DELIVERY_TOKEN${webhookSecret ? ' and SHAPIO_WEBHOOK_SECRET' : ''} to ${path}`,
+    `Wrote SHAPIO_URL, ${site ? 'SHAPIO_SITE, ' : ''}SHAPIO_DELIVERY_TOKEN, SHAPIO_DEV_DELIVERY_TOKEN${webhookSecret ? ' and SHAPIO_WEBHOOK_SECRET' : ''} to ${path}`,
   );
 };
 
@@ -444,7 +489,15 @@ const main = async () => {
     const webhookSecret = revalidatePath
       ? await tryRevalidateWebhook(admin.client, siteUrl, revalidatePath)
       : undefined;
-    await writeEnv(admin.url, admin.site, await createDeliveryToken(admin.client), webhookSecret);
+    const siteName = await siteNameOf(admin.client, admin.site);
+    await writeEnv({
+      url: admin.url,
+      site: admin.site,
+      deliveryToken: await createDeliveryToken(admin.client, BUILD_ROLE),
+      devDeliveryToken: await createDeliveryToken(admin.client, devRole(siteName)),
+      webhookSecret,
+    });
+    log(`Created the "${siteName} dev" token for drafts mode (SHAPIO_DRAFTS=true); keep it off production.`);
     log('Seeded. Build the site with: npm run build');
   } finally {
     await admin.close();

package/templates/next/scripts/smokeDrafts.ts

@@ -0,0 +1,109 @@
+import { parseArgs } from 'node:util';
+import { connectAdmin } from './lib/admin.js';
+
+/**
+ * `npm run smoke:drafts`, after `npm run seed` and starting the dev server with SHAPIO_DRAFTS=true (drafts mode,
+ * which reads with the seed's SHAPIO_DEV_DELIVERY_TOKEN): checks that the site shows drafts, that every page
+ * carries the "Drafts" badge, and that a change saved in Shapio (not published) shows on the next reload.
+ * The saved change is put back afterwards. Needs SHAPIO_ADMIN_EMAIL and SHAPIO_ADMIN_PASSWORD (or SHAPIO_TOKEN,
+ * an admin API token) to save the change, as the seed does.
+ *
+ * `--url` is the running dev server's origin (default: SMOKE_URL, then http://localhost:3000).
+ */
+const DRAFT_TITLE = 'Coming soon: our winter projects';
+const ARTICLE = 'modelling-without-a-deploy';
+const BADGE = 'data-shapio-drafts';
+/** How long a saved draft may take to show: the dev server reads fresh, so this only absorbs a slow render. */
+const SHOW_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 fetchPage = async (origin: string, path: string) => {
+  const response = await fetch(new URL(path, origin));
+  return { status: response.status, html: await response.text() };
+};
+
+/** Reloads `path` until it contains `needle` (a real condition, not a fixed wait); false when it never does. */
+const showsWithin = async (origin: string, path: string, needle: string): Promise<boolean> => {
+  const deadline = Date.now() + SHOW_WITHIN_MS;
+  while (Date.now() < deadline) {
+    if ((await fetchPage(origin, path)).html.includes(needle)) {
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, POLL_EVERY_MS));
+  }
+  return false;
+};
+
+/** Saves (does not publish) the article's English title, and returns a function that puts the old one back. */
+const saveTitle = async (client: Awaited<ReturnType<typeof connectAdmin>>['client'], 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;
+  // A save sends only the fields it changes.
+  const saved = await client.admin.content.update('article', item.id, {
+    locale: 'en',
+    expectedVersion: entry.version,
+    data: { title },
+  });
+  return async () => {
+    await client.admin.content.update('article', item.id, {
+      locale: 'en',
+      expectedVersion: saved.version,
+      data: { title: original },
+    });
+  };
+};
+
+const main = async () => {
+  const { values } = parseArgs({ options: { url: { type: 'string' } } });
+  const origin = values.url ?? process.env.SMOKE_URL ?? 'http://localhost:3000';
+
+  const list = await fetchPage(origin, '/en/articles/');
+  check(list.status === 200, `/en/articles/: HTTP ${list.status}`);
+  check(list.html.includes(BADGE), '/en/articles/: the Drafts badge');
+  check(list.html.includes(DRAFT_TITLE), 'the unpublished draft is listed (drafts mode)');
+  const draft = await fetchPage(origin, '/en/articles/winter-projects/');
+  check(
+    draft.status === 200 && draft.html.includes(DRAFT_TITLE),
+    `the unpublished draft is served (HTTP ${draft.status})`,
+  );
+
+  const admin = await connectAdmin(process.env);
+  try {
+    const marker = `Saved, not published ${Date.now()}`;
+    const restore = await saveTitle(admin.client, marker);
+    try {
+      check(
+        await showsWithin(origin, `/en/articles/${ARTICLE}/`, marker),
+        'a change saved in Shapio shows on reload, without publishing',
+      );
+    } finally {
+      await restore();
+    }
+  } finally {
+    await admin.close();
+  }
+
+  if (failures.length > 0) {
+    throw new Error(`${failures.length} check(s) failed against ${origin}`);
+  }
+  process.stdout.write(`Drafts smoke test passed against ${origin}.\n`);
+};
+
+main().catch((error: unknown) => {
+  process.stderr.write(`smoke:drafts: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});

package/templates/next/scripts/smokeHttp.ts

@@ -1,4 +1,6 @@
 import { createHmac } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { parseArgs } from 'node:util';
 
 /**
@@ -13,6 +15,10 @@ import { parseArgs } from 'node:util';
  * `--url` is the running site's origin (default: SMOKE_URL, then http://localhost:4321). `--revalidate` (the
  * Next.js starter) also checks its on-demand revalidation route: an unsigned POST to /api/revalidate is refused,
  * and an event signed with SHAPIO_WEBHOOK_SECRET is answered 200 with the paths it revalidated.
+ *
+ * `--save <dir>` also writes each checked page's rendered markup to `<dir>` (scripts and the framework's own
+ * asset links removed: they name build-specific chunks), so two builds of a site can be compared with
+ * `diff -r`, e.g. the Next.js starter reading over HTTP and in process.
  */
 const DRAFT_TITLE = 'Coming soon: our winter projects';
 const ARTICLE = 'modelling-without-a-deploy';
@@ -85,6 +91,18 @@ const fetchPage = async (origin: string, path: string) => {
   return { status: response.status, html: await response.text() };
 };
 
+/** The page as rendered: without scripts and framework asset links, which differ from build to build. */
+const renderedMarkup = (html: string) =>
+  html
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/g, '')
+    .replace(/<link\b[^>]*\/_next\/[^>]*>/g, '')
+    .replace(/<meta\b[^>]*name="next-size-adjust"[^>]*>/g, '');
+
+const savePage = async (directory: string, path: string, html: string) => {
+  const name = path.replace(/^\/|\/$/g, '').replace(/\//g, '__') || 'index';
+  await writeFile(join(directory, `${name}.html`), `${renderedMarkup(html)}\n`);
+};
+
 const REVALIDATE_PATH = '/api/revalidate/';
 
 const postEvent = (origin: string, body: string, headers: Record<string, string>) =>
@@ -137,12 +155,22 @@ const checkRevalidation = async (origin: string) => {
 
 const main = async () => {
   const { values } = parseArgs({
-    options: { url: { type: 'string' }, revalidate: { type: 'boolean', default: false } },
+    options: {
+      url: { type: 'string' },
+      revalidate: { type: 'boolean', default: false },
+      save: { type: 'string' },
+    },
   });
   const origin = values.url ?? process.env.SMOKE_URL ?? 'http://localhost:4321';
+  if (values.save) {
+    await mkdir(values.save, { recursive: true });
+  }
   for (const page of PAGES) {
     const { status, html } = await fetchPage(origin, page.path);
     check(status === 200, `${page.path}: HTTP ${status}`);
+    if (values.save) {
+      await savePage(values.save, page.path, html);
+    }
     for (const [needle, label] of page.expect) {
       check(html.includes(needle), `${page.path}: ${label}`);
     }

package/templates/next/src/app/[locale]/layout.tsx

@@ -2,7 +2,9 @@ import type { Metadata } from 'next';
 import Link from 'next/link';
 import { notFound } from 'next/navigation';
 import type { ReactNode } from 'react';
+import { DraftsBadge } from '../../components/DraftsBadge';
 import { LocaleSwitch } from '../../components/LocaleSwitch';
+import { isDraftsMode } from '../../lib/config';
 import { getSiteSettings } from '../../lib/shapio';
 import {
   articlesPath,
@@ -73,6 +75,7 @@ const LocaleLayout = async ({ children, params }: LocaleLayoutProps) => {
             {settings?.siteName ?? strings.siteName} · {settings?.footer ?? strings.footer} · Next.js
           </p>
         </footer>
+        {isDraftsMode() ? <DraftsBadge strings={strings} /> : null}
       </body>
     </html>
   );

package/templates/next/src/app/api/revalidate/route.ts

@@ -8,7 +8,9 @@ import { readWebhookEvent } from '../../../lib/webhookEvent';
  * POST /api/revalidate/ (with the slash: `trailingSlash` redirects the other form, and Shapio's webhooks do not
  * follow redirects): the target of the Shapio webhook the seed creates (publish, unpublish, delete,
  * change set shipped, schema change, site settings). A signed delivery refreshes the pages whose content changed since the
- * snapshot the site shows (src/lib/revalidation.ts). A failure answers 500, so Shapio retries the delivery.
+ * snapshot the site shows and expires the cached reads tagged with their models and entries; `site.updated` and
+ * schema changes expire the site tag, which every read carries (src/lib/revalidation.ts). A failure answers 500,
+ * so Shapio retries the delivery.
  */
 export const POST = async (request: Request) => {
   const read = await readWebhookEvent(request, webhookSecret());

package/templates/next/src/app/site.css

@@ -197,3 +197,17 @@ main {
   text-align: center;
   font-weight: 600;
 }
+/* Drafts mode (SHAPIO_DRAFTS=true): a corner badge, so a drafts build is never mistaken for the real site. */
+.drafts-badge {
+  position: fixed;
+  right: 1rem;
+  bottom: 1rem;
+  z-index: 10;
+  margin: 0;
+  background: #78350f;
+  color: #fef3c7;
+  padding: 0.25rem 0.75rem;
+  border-radius: 999px;
+  font-size: 0.875rem;
+  font-weight: 700;
+}

package/templates/next/src/components/DraftsBadge/index.tsx

@@ -0,0 +1,10 @@
+import type { Strings } from '../../lib/site';
+
+type DraftsBadgeProps = { strings: Strings };
+
+/** The corner badge of drafts mode (SHAPIO_DRAFTS=true): this server shows saved drafts, not the published site. */
+export const DraftsBadge = ({ strings }: DraftsBadgeProps) => (
+  <p className="drafts-badge" title={strings.draftsNote} data-shapio-drafts="">
+    {strings.drafts}
+  </p>
+);

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

@@ -12,6 +12,14 @@
  *   URL (and `og:url`) unless the entry sets its own.
  * - NEXT_PUBLIC_SHAPIO_URL: the Shapio URL the browser calls for previews (defaults to SHAPIO_URL; inlined into
  *   the client bundle at build time).
+ * - SHAPIO_MODE: `http` (default) reads Shapio's delivery API over HTTP; `in-process` reads the same API as
+ *   function calls in this server process (@shapio/local), from Shapio's database at DATABASE_URL. Previews
+ *   and the browser still use SHAPIO_URL. See documentation/in-process.md.
+ * - DATABASE_URL: Shapio's own database (PostgreSQL or MySQL), for SHAPIO_MODE=in-process only.
+ * - SHAPIO_DRAFTS: `true` turns on drafts mode, for your development server: every read shows saved drafts
+ *   instead of published content, fresh on every request (no snapshot, no cache), 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.
  */
 const read = (name: string): string | undefined => {
   const value = process.env[name];
@@ -20,8 +28,13 @@ const read = (name: string): string | undefined => {
 
 export const shapioUrl = () => read('SHAPIO_URL') ?? 'http://localhost:4300';
 
+/** Drafts mode (SHAPIO_DRAFTS=true): the site reads saved drafts. Never set in production. */
+export const isDraftsMode = () => read('SHAPIO_DRAFTS') === 'true';
+
 export const deliveryToken = () => {
-  const token = read('SHAPIO_DELIVERY_TOKEN');
+  // Drafts mode reads with the development token (Read drafts) when there is one.
+  const token =
+    (isDraftsMode() ? read('SHAPIO_DEV_DELIVERY_TOKEN') : undefined) ?? read('SHAPIO_DELIVERY_TOKEN');
   if (!token) {
     throw new Error(
       'Set SHAPIO_DELIVERY_TOKEN (a Shapio delivery token) to build the site; `npm run seed` writes one to .env',
@@ -32,6 +45,24 @@ export const deliveryToken = () => {
 
 export const siteKey = () => read('SHAPIO_SITE');
 
+export type ShapioMode = 'http' | 'in-process';
+
+export const shapioMode = (): ShapioMode => {
+  const mode = read('SHAPIO_MODE') ?? 'http';
+  if (mode !== 'http' && mode !== 'in-process') {
+    throw new Error(`SHAPIO_MODE must be "http" or "in-process", got "${mode}"`);
+  }
+  return mode;
+};
+
+export const databaseUrl = () => {
+  const url = read('DATABASE_URL');
+  if (!url) {
+    throw new Error("SHAPIO_MODE=in-process reads Shapio's database: set DATABASE_URL to it");
+  }
+  return url;
+};
+
 export const siteUrl = () => read('SITE_URL');
 
 export const configuredSnapshot = (): number | undefined => {
@@ -54,6 +85,9 @@ export const configuredSnapshot = (): number | undefined => {
  */
 export const isSnapshotPinned = () => process.env.SHAPIO_SNAPSHOT_PINNED === 'true';
 
+/** True under `next dev`. Spelled out so Next inlines it. */
+export const isDevServer = () => process.env.NODE_ENV === 'development';
+
 /** The secret /api/revalidate checks webhook signatures with; undefined when it is not set. */
 export const webhookSecret = () => read('SHAPIO_WEBHOOK_SECRET');
 

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

@@ -1,8 +1,9 @@
 import { ShapioApiError, type SnapshotChange, type SnapshotChangeKind } from '@shapio/client';
-import { revalidatePath } from 'next/cache';
-import { configuredSnapshot, isSnapshotPinned } from './config';
+import { revalidatePath, revalidateTag } from 'next/cache';
+import { configuredSnapshot, isDraftsMode, isSnapshotPinned, siteKey } from './config';
 import { advanceTo, liveSnapshot } from './liveSnapshot';
 import { log } from './log';
+import { changeTags, siteTags } from './revalidationTags';
 import {
   EVERY_PAGE,
   revalidationTargets,
@@ -13,12 +14,21 @@ import { shapio } from './shapio';
 
 /**
  * On-demand revalidation (`next start`): asks Shapio what changed between the snapshot the site shows and
- * the current one (`/api/snapshots/changes`), revalidates the pages those changes touch and moves the site to
- * the new snapshot. The diff, not the event, is the source of truth: one call covers a change set's many
- * entries, retried or missed deliveries, and both locales of a publish.
+ * the current one (`/api/snapshots/changes`), revalidates the pages those changes touch and the cached reads
+ * tagged with their models and entries, and moves the site to the new snapshot. The diff, not the event, is the
+ * source of truth: one call covers a change set's many entries, retried or missed deliveries, and both locales
+ * of a publish.
  */
 export type RevalidationResult =
-  { from: number; to: number; changed: number; revalidated: RevalidationTarget[] } | { skipped: string };
+  | { from: number; to: number; changed: number; revalidated: RevalidationTarget[]; tags: string[] }
+  | { skipped: string };
+
+/** Expires the cached reads at once (not stale-while-revalidate): the next render reads the new content. */
+const expireTags = (tags: readonly string[]) => {
+  for (const tag of tags) {
+    revalidateTag(tag, { expire: 0 });
+  }
+};
 
 /** Models whose pages are addressed by slug. */
 const SLUGGED_MODELS: ReadonlySet<string> = new Set(['page', 'article']);
@@ -59,24 +69,29 @@ const changedEntries = async (items: readonly SnapshotChange[], from: number, to
 };
 
 const revalidateNow = async (): Promise<RevalidationResult> => {
+  if (isDraftsMode()) {
+    return { skipped: 'drafts mode (SHAPIO_DRAFTS=true) reads drafts, which are never pinned or cached' };
+  }
   if (isSnapshotPinned()) {
     return { skipped: `the build is pinned to snapshot ${configuredSnapshot()} by SHAPIO_SNAPSHOT` };
   }
   const from = liveSnapshot();
   const { snapshot: to } = await shapio().snapshots.current();
   if (to <= from) {
-    return { from, to: from, changed: 0, revalidated: [] };
+    return { from, to: from, changed: 0, revalidated: [], tags: [] };
   }
   const diff = await shapio().snapshots.allChanges({ from, to });
   const { schemaVersions } = diff;
   const schemaChanged = schemaVersions.from === null || schemaVersions.from !== schemaVersions.to;
   const targets = revalidationTargets(await changedEntries(diff.items, from, to), schemaChanged);
+  const tags = changeTags(diff.items, schemaChanged, siteKey());
   await advanceTo(to, () => {
+    expireTags(tags);
     for (const target of targets) {
       revalidatePath(target.path, target.type);
     }
   });
-  return { from, to, changed: diff.items.length, revalidated: targets };
+  return { from, to, changed: diff.items.length, revalidated: targets, tags };
 };
 
 /** One run at a time: deliveries that arrive together diff from the snapshot the previous run reached. */
@@ -89,22 +104,25 @@ export const revalidateChanges = (): Promise<RevalidationResult> => {
     log(
       'skipped' in result
         ? `Revalidation skipped: ${result.skipped}`
-        : `Snapshots ${result.from} → ${result.to}: revalidated ${result.revalidated.length} path(s)`,
+        : `Snapshots ${result.from} → ${result.to}: revalidated ${result.revalidated.length} path(s), ${result.tags.length} tag(s)`,
     );
     return result;
   });
 };
 
 /**
- * Site-wide changes that publish no snapshot (the site's SEO defaults: `site.updated`): every page is
- * revalidated at the snapshot the site already shows.
+ * Site-wide changes that publish no snapshot (the site's SEO defaults: `site.updated`): the site tag expires
+ * every cached read (`site.get()` among them) and every page is revalidated at the snapshot the site already
+ * shows.
  */
 export const revalidateEveryPage = (): RevalidationResult => {
   if (isSnapshotPinned()) {
     return { skipped: `the build is pinned to snapshot ${configuredSnapshot()} by SHAPIO_SNAPSHOT` };
   }
+  const tags = siteTags(siteKey());
+  expireTags(tags);
   revalidatePath(EVERY_PAGE.path, EVERY_PAGE.type);
   const at = liveSnapshot();
   log(`Site settings changed: revalidated every page at snapshot ${at}`);
-  return { from: at, to: at, changed: 0, revalidated: [EVERY_PAGE] };
+  return { from: at, to: at, changed: 0, revalidated: [EVERY_PAGE], tags };
 };

package/templates/next/src/lib/revalidationTags.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { changeTags, siteTags } from './revalidationTags';
+
+describe('changeTags', () => {
+  it("tags each changed entry's model and the entry, without duplicates", () => {
+    expect(
+      changeTags(
+        [
+          { routeKey: 'articles', id: 'a1' },
+          { routeKey: 'articles', id: 'a2' },
+          { routeKey: 'siteSettings', id: 's1' },
+          { routeKey: 'articles', id: 'a1' },
+        ],
+        false,
+        'marketing',
+      ),
+    ).toEqual([
+      'shapio:articles',
+      'shapio:articles:a1',
+      'shapio:articles:a2',
+      'shapio:siteSettings',
+      'shapio:siteSettings:s1',
+    ]);
+  });
+
+  it('revalidates the site tag (every read) after a schema change', () => {
+    expect(changeTags([{ routeKey: 'articles', id: 'a1' }], true, 'marketing')).toEqual([
+      'shapio:site:marketing',
+    ]);
+    expect(changeTags([], true, undefined)).toEqual(['shapio:site']);
+  });
+
+  it('has nothing to revalidate when nothing changed', () => {
+    expect(changeTags([], false, undefined)).toEqual([]);
+  });
+});
+
+describe('siteTags', () => {
+  it("is the client's site tag: keyed when the site is configured, bare otherwise", () => {
+    expect(siteTags('marketing')).toEqual(['shapio:site:marketing']);
+    expect(siteTags(undefined)).toEqual(['shapio:site']);
+  });
+});

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

@@ -0,0 +1,30 @@
+import { shapioTags, type SnapshotChange } from '@shapio/client';
+
+/**
+ * What a set of Shapio changes means for Next's data cache: the arguments for `revalidateTag`, matching the
+ * tags `@shapio/client` puts on every delivery read (`shapioTags`). Pure, so the mapping is unit-tested;
+ * src/lib/revalidation.ts feeds it from the snapshot diff, which names each changed entry by its route key.
+ */
+export type ChangedEntryRef = Pick<SnapshotChange, 'routeKey' | 'id'>;
+
+/** Every delivery read of the site carries this tag: the site's settings, and everything after a schema change. */
+export const siteTags = (siteKey: string | undefined): string[] => [shapioTags.site(siteKey)];
+
+/**
+ * The tags to revalidate for the entries that changed between two snapshots: each entry's model and the entry
+ * itself. A schema change (fields added, converted or removed) can change any read, so it revalidates the
+ * site tag, which every read carries.
+ */
+export const changeTags = (
+  changes: readonly ChangedEntryRef[],
+  schemaChanged: boolean,
+  siteKey: string | undefined,
+): string[] => {
+  if (schemaChanged) {
+    return siteTags(siteKey);
+  }
+  const tags = new Set(
+    changes.flatMap(({ routeKey, id }) => [shapioTags.model(routeKey), shapioTags.entry(routeKey, id)]),
+  );
+  return [...tags].sort();
+};