create-shapio 0.2.0

package/templates/next/src/components/Sections/Hero/index.tsx

@@ -0,0 +1,31 @@
+import type { ShapioAttributes } from '@shapio/visual';
+import { safeHref } from '../../../lib/site';
+import type { HeroSection } from '../../../lib/types';
+import { ResponsiveImage } from '../../ResponsiveImage';
+
+type HeroProps = { section: HeroSection; isFirst: boolean; visual?: ShapioAttributes };
+
+export const Hero = ({ section, isFirst, visual }: HeroProps) => {
+  const Heading = isFirst ? 'h1' : 'h2';
+  return (
+    <section className="hero">
+      <div className="hero-text">
+        <Heading {...visual}>{section.heading}</Heading>
+        {section.subheading ? <p className="lead">{section.subheading}</p> : null}
+        {section.ctaLabel && section.ctaUrl ? (
+          <a className="button" href={safeHref(section.ctaUrl)}>
+            {section.ctaLabel}
+          </a>
+        ) : null}
+      </div>
+      {section.image ? (
+        <ResponsiveImage
+          media={section.image}
+          sizes="(min-width: 64rem) 50vw, 100vw"
+          eager={isFirst}
+          className="hero-image"
+        />
+      ) : null}
+    </section>
+  );
+};

package/templates/next/src/components/Sections/SectionView/index.tsx

@@ -0,0 +1,30 @@
+import { shapioAttr, type EntryRef } from '@shapio/visual';
+import type { Section } from '../../../lib/types';
+import { CallToAction } from '../CallToAction';
+import { FeatureGrid } from '../FeatureGrid';
+import { Gallery } from '../Gallery';
+import { Hero } from '../Hero';
+
+type SectionViewProps = { section: Section; index: number; entry: EntryRef };
+
+export const SectionView = ({ section, index, entry }: SectionViewProps) => {
+  switch (section.__component) {
+    case 'hero':
+      return (
+        <Hero
+          section={section}
+          isFirst={index === 0}
+          visual={shapioAttr(entry, `sections/${index}/heading`)}
+        />
+      );
+    case 'featureGrid':
+      return <FeatureGrid section={section} />;
+    case 'gallery':
+      return <Gallery section={section} />;
+    case 'callToAction':
+      return <CallToAction section={section} />;
+    default:
+      // A section type this site does not know yet (added in Shapio after the last deploy): skipped.
+      return null;
+  }
+};

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

@@ -0,0 +1,19 @@
+import { shapioAttr } from '@shapio/visual';
+import type { Page } from '../../lib/types';
+import { SectionView } from './SectionView';
+
+type SectionsProps = { page: Pick<Page, 'id' | 'title' | 'sections' | 'locale'> };
+
+/** A page's dynamic zone. The page title is the heading when the page does not open with a hero. */
+export const Sections = ({ page }: SectionsProps) => (
+  <div lang={page.locale}>
+    {page.sections[0]?.__component === 'hero' ? null : (
+      <h1 className="page-title" {...shapioAttr(page, 'title')}>
+        {page.title}
+      </h1>
+    )}
+    {page.sections.map((section, index) => (
+      <SectionView key={`${section.__component}-${index}`} section={section} index={index} entry={page} />
+    ))}
+  </div>
+);

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

@@ -0,0 +1,5 @@
+import type { Article, Author } from './types';
+
+/** The populated author (`populate=author`); null when only the ID came back or the author is unpublished. */
+export const authorOf = (article: Article): Author | null =>
+  typeof article.author === 'object' && article.author !== null ? article.author : null;

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

@@ -0,0 +1,57 @@
+/**
+ * Build-time settings, from the environment (or `.env` in this folder, which `npm run seed` writes):
+ * - SHAPIO_URL: the Shapio origin (with BASE_PATH), e.g. https://cms.example.com.
+ * - SHAPIO_DELIVERY_TOKEN: a read-only delivery token (Settings → API tokens, delivery role).
+ * - SHAPIO_SNAPSHOT: optional; the publication snapshot to build. Without it, next.config.ts pins the latest
+ *   snapshot once when `next build` starts, so every page of the build shows the same moment. When set, the
+ *   site stays at that snapshot under `next start` too (on-demand revalidation is off).
+ * - SHAPIO_WEBHOOK_SECRET: the signing secret of the Shapio webhook that calls /api/revalidate (runtime only;
+ *   `npm run seed` writes it).
+ * - SHAPIO_SITE: optional; the site key on a multi-site Shapio (default: the token's site, else the primary).
+ * - NEXT_PUBLIC_SHAPIO_URL: the Shapio URL the browser calls for previews (defaults to SHAPIO_URL; inlined into
+ *   the client bundle at build time).
+ */
+const read = (name: string): string | undefined => {
+  const value = process.env[name];
+  return value === undefined || value === '' ? undefined : value;
+};
+
+export const shapioUrl = () => read('SHAPIO_URL') ?? 'http://localhost:4300';
+
+export const deliveryToken = () => {
+  const token = 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',
+    );
+  }
+  return token;
+};
+
+export const siteKey = () => read('SHAPIO_SITE');
+
+export const configuredSnapshot = (): number | undefined => {
+  // Spelled out (not read(name)): next.config.ts hands the pinned snapshot over through Next's `env`, which
+  // replaces this exact expression at build time.
+  const value = process.env.SHAPIO_SNAPSHOT;
+  if (value === undefined || value === '') {
+    return undefined;
+  }
+  const snapshot = Number(value);
+  if (!Number.isInteger(snapshot) || snapshot < 0) {
+    throw new Error(`SHAPIO_SNAPSHOT must be a publication snapshot number, got "${value}"`);
+  }
+  return snapshot;
+};
+
+/**
+ * True when the build was pinned with SHAPIO_SNAPSHOT (next.config.ts records it): the site then keeps
+ * showing that snapshot and /api/revalidate does nothing. Spelled out so Next inlines it at build time.
+ */
+export const isSnapshotPinned = () => process.env.SHAPIO_SNAPSHOT_PINNED === 'true';
+
+/** The secret /api/revalidate checks webhook signatures with; undefined when it is not set. */
+export const webhookSecret = () => read('SHAPIO_WEBHOOK_SECRET');
+
+/** The Shapio URL the preview page calls from the browser. Spelled out so Next inlines it into the client. */
+export const publicShapioUrl = () => process.env.NEXT_PUBLIC_SHAPIO_URL || 'http://localhost:4300';

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

@@ -0,0 +1,74 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { configuredSnapshot, isSnapshotPinned } from './config';
+import { log } from './log';
+
+/**
+ * The publication snapshot the site reads. `next build` renders every page at the snapshot next.config.ts
+ * pinned; under `next start`, /api/revalidate moves the site forward to each new snapshot Shapio reports and
+ * revalidates the pages that changed, which then re-render at that snapshot.
+ *
+ * The last handled snapshot lives in memory (on `globalThis`, which the route handler and the pages share in
+ * the one `next start` process) and in `.next/shapio-revalidate.json`, so a restart carries on from it. The
+ * file sits in `.next/`, which `next build` empties, so a new build starts again from its own snapshot.
+ * A build pinned with SHAPIO_SNAPSHOT ignores both: it keeps showing that snapshot.
+ */
+const STATE_FILE = join(process.cwd(), '.next', 'shapio-revalidate.json');
+
+type LiveState = { snapshot: number | undefined; loaded: boolean };
+const holder = globalThis as typeof globalThis & { __shapioLiveSnapshot?: LiveState };
+const state = (): LiveState => (holder.__shapioLiveSnapshot ??= { snapshot: undefined, loaded: false });
+
+const buildSnapshot = (): number => {
+  const pinned = configuredSnapshot();
+  if (pinned === undefined) {
+    throw new Error('No pinned snapshot: next.config.ts sets SHAPIO_SNAPSHOT when `next build` starts');
+  }
+  return pinned;
+};
+
+const readStateFile = (): number | undefined => {
+  try {
+    const { snapshot } = JSON.parse(readFileSync(STATE_FILE, 'utf8')) as { snapshot?: unknown };
+    return typeof snapshot === 'number' && Number.isInteger(snapshot) && snapshot >= 0 ? snapshot : undefined;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+      log(`Ignoring ${STATE_FILE} (${error instanceof Error ? error.message : String(error)})`);
+    }
+    return undefined;
+  }
+};
+
+/** The snapshot every delivery read sends: the build's, or the last one /api/revalidate handled. */
+export const liveSnapshot = (): number => {
+  const built = buildSnapshot();
+  if (isSnapshotPinned()) {
+    return built;
+  }
+  const current = state();
+  if (!current.loaded) {
+    current.snapshot = readStateFile();
+    current.loaded = true;
+  }
+  return Math.max(built, current.snapshot ?? built);
+};
+
+/**
+ * Moves the site to `snapshot` while `revalidate` runs (pages it marks stale re-render at the new snapshot),
+ * then records it on disk. If `revalidate` throws, the site stays where it was.
+ */
+export const advanceTo = async (snapshot: number, revalidate: () => void | Promise<void>) => {
+  const current = state();
+  const previous = liveSnapshot();
+  current.snapshot = snapshot;
+  try {
+    await revalidate();
+  } catch (error) {
+    current.snapshot = previous;
+    throw error;
+  }
+  mkdirSync(dirname(STATE_FILE), { recursive: true });
+  const temporary = `${STATE_FILE}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify({ snapshot, updatedAt: new Date().toISOString() })}\n`);
+  renameSync(temporary, STATE_FILE);
+};

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

@@ -0,0 +1,4 @@
+/** Server-side log lines (`next start` prints them with its own output). */
+export const log = (line: string) => {
+  process.stderr.write(`[shapio] ${line}\n`);
+};

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

@@ -0,0 +1,56 @@
+import { createClient } from '@shapio/client';
+import { DEFAULT_LOCALE, isLocale, type Locale } from './site';
+import type { Article, DeliveryItem, Page } from './types';
+
+/**
+ * Preview: Shapio opens `/preview/?model={modelKey}&id={entryId}&locale={locale}#token={token}` (the
+ * connection's preview URL template). `{modelKey}` is the model's route key (`pages`, `articles`). The token
+ * sits in the fragment, so it never reaches a server log or a Referer header; it is a scoped, expiring preview
+ * token, never an admin credential. The draft is read in the browser from `/api/preview/content/...` and
+ * rendered with the same components as the published pages.
+ */
+export const PREVIEW_MODELS = ['pages', 'articles'] as const;
+
+export type PreviewRequest = {
+  token: string;
+  modelKey: (typeof PREVIEW_MODELS)[number];
+  entryId: string;
+  locale: Locale;
+};
+
+export type PreviewDraft =
+  | { modelKey: 'pages'; entry: Page; locale: Locale }
+  | { modelKey: 'articles'; entry: Article; locale: Locale };
+
+/** Reads the request from a preview URL; undefined when something is missing or unknown. */
+export const parsePreviewUrl = (url: URL): PreviewRequest | undefined => {
+  const fragment = new URLSearchParams(url.hash.slice(1));
+  const token = fragment.get('token') ?? url.searchParams.get('token');
+  const modelKey = url.searchParams.get('model');
+  const entryId = url.searchParams.get('id');
+  const locale = url.searchParams.get('locale') ?? DEFAULT_LOCALE;
+  if (!token || !entryId || !(PREVIEW_MODELS as readonly string[]).includes(modelKey ?? '')) {
+    return undefined;
+  }
+  return {
+    token,
+    modelKey: modelKey as PreviewRequest['modelKey'],
+    entryId,
+    locale: isLocale(locale) ? locale : DEFAULT_LOCALE,
+  };
+};
+
+/** Fetches the draft through the preview API. */
+export const loadDraft = async (shapioUrl: string, request: PreviewRequest): Promise<PreviewDraft> => {
+  const client = createClient({ baseUrl: shapioUrl, token: request.token });
+  const params = new URLSearchParams({
+    locale: request.locale,
+    ...(request.modelKey === 'articles' ? { populate: 'author' } : {}),
+  });
+  const { data } = await client.request<DeliveryItem<Page | Article>>(
+    `/api/preview/content/${encodeURIComponent(request.modelKey)}/${encodeURIComponent(request.entryId)}?${params.toString()}`,
+  );
+  return request.modelKey === 'pages'
+    ? { modelKey: 'pages', entry: data as Page, locale: request.locale }
+    : { modelKey: 'articles', entry: data as Article, locale: request.locale };
+};

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

@@ -0,0 +1,91 @@
+import { ShapioApiError, type SnapshotChange, type SnapshotChangeKind } from '@shapio/client';
+import { revalidatePath } from 'next/cache';
+import { configuredSnapshot, isSnapshotPinned } from './config';
+import { advanceTo, liveSnapshot } from './liveSnapshot';
+import { log } from './log';
+import { revalidationTargets, type ChangedEntry, type RevalidationTarget } from './revalidationTargets';
+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.
+ */
+export type RevalidationResult =
+  { from: number; to: number; changed: number; revalidated: RevalidationTarget[] } | { skipped: string };
+
+/** Models whose pages are addressed by slug. */
+const SLUGGED_MODELS: ReadonlySet<string> = new Set(['page', 'article']);
+
+/** The entry's slug in `locale` at `snapshot`; null when it was not published there. */
+const slugAt = async (change: SnapshotChange, locale: string, snapshot: number): Promise<string | null> => {
+  try {
+    const { data } = await shapio().delivery.get<{ slug?: unknown }>(change.routeKey, change.id, {
+      locale,
+      snapshot,
+      fields: ['slug'],
+    });
+    return typeof data.slug === 'string' ? data.slug : null;
+  } catch (error) {
+    if (error instanceof ShapioApiError && error.status === 404) {
+      return null;
+    }
+    throw error;
+  }
+};
+
+/** Where the entry was (unpublished), is (published), or both (updated: the slug may have changed). */
+const slugSnapshots = (kind: SnapshotChangeKind, from: number, to: number): number[] =>
+  kind === 'published' ? [to] : kind === 'unpublished' ? [from] : [from, to];
+
+const changedEntries = async (items: readonly SnapshotChange[], from: number, to: number) => {
+  const lookups = items.flatMap((change) =>
+    change.locales.map(async ({ locale, change: kind }): Promise<ChangedEntry> => {
+      if (!SLUGGED_MODELS.has(change.modelKey)) {
+        return { modelKey: change.modelKey, locale, slugs: [] };
+      }
+      const slugs = await Promise.all(slugSnapshots(kind, from, to).map((at) => slugAt(change, locale, at)));
+      const found = slugs.filter((slug): slug is string => slug !== null);
+      return { modelKey: change.modelKey, locale, slugs: [...new Set(found)] };
+    }),
+  );
+  return Promise.all(lookups);
+};
+
+const revalidateNow = async (): Promise<RevalidationResult> => {
+  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: [] };
+  }
+  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);
+  await advanceTo(to, () => {
+    for (const target of targets) {
+      revalidatePath(target.path, target.type);
+    }
+  });
+  return { from, to, changed: diff.items.length, revalidated: targets };
+};
+
+/** One run at a time: deliveries that arrive together diff from the snapshot the previous run reached. */
+let queue: Promise<unknown> = Promise.resolve();
+
+export const revalidateChanges = (): Promise<RevalidationResult> => {
+  const run = queue.then(revalidateNow, revalidateNow);
+  queue = run.catch(() => undefined);
+  return run.then((result) => {
+    log(
+      'skipped' in result
+        ? `Revalidation skipped: ${result.skipped}`
+        : `Snapshots ${result.from} → ${result.to}: revalidated ${result.revalidated.length} path(s)`,
+    );
+    return result;
+  });
+};

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

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { EVERY_PAGE, revalidationTargets } from './revalidationTargets';
+
+describe('revalidationTargets', () => {
+  it('maps a changed article to its page and the locale’s article list', () => {
+    expect(revalidationTargets([{ modelKey: 'article', locale: 'fr', slugs: ['hello'] }], false)).toEqual([
+      { path: '/fr/articles/' },
+      { path: '/fr/articles/hello/' },
+    ]);
+  });
+
+  it('revalidates both slugs of an article whose slug changed, and its list once', () => {
+    expect(
+      revalidationTargets(
+        [
+          { modelKey: 'article', locale: 'en', slugs: ['old', 'new'] },
+          { modelKey: 'article', locale: 'en', slugs: ['other'] },
+        ],
+        false,
+      ),
+    ).toEqual([
+      { path: '/en/articles/' },
+      { path: '/en/articles/new/' },
+      { path: '/en/articles/old/' },
+      { path: '/en/articles/other/' },
+    ]);
+  });
+
+  it('maps pages by slug, with home as the locale’s front page', () => {
+    expect(
+      revalidationTargets(
+        [
+          { modelKey: 'page', locale: 'en', slugs: ['home'] },
+          { modelKey: 'page', locale: 'fr', slugs: ['about'] },
+        ],
+        false,
+      ),
+    ).toEqual([{ path: '/en/' }, { path: '/fr/about/' }]);
+  });
+
+  it('refreshes the article list and every article page for an author', () => {
+    expect(revalidationTargets([{ modelKey: 'author', locale: 'en', slugs: [] }], false)).toEqual([
+      { path: '/[locale]/articles/[slug]', type: 'page' },
+      { path: '/en/articles/' },
+    ]);
+  });
+
+  it('refreshes every page for the siteSettings singleton or a schema change', () => {
+    const page = { modelKey: 'page', locale: 'en', slugs: ['about'] };
+    expect(revalidationTargets([page, { modelKey: 'siteSettings', locale: 'en', slugs: [] }], false)).toEqual(
+      [EVERY_PAGE],
+    );
+    expect(revalidationTargets([page], true)).toEqual([EVERY_PAGE]);
+  });
+
+  it('ignores models the site does not render and entries without a slug', () => {
+    expect(
+      revalidationTargets(
+        [
+          { modelKey: 'product', locale: 'en', slugs: ['x'] },
+          { modelKey: 'page', locale: 'en', slugs: [] },
+        ],
+        false,
+      ),
+    ).toEqual([]);
+  });
+});

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

@@ -0,0 +1,66 @@
+import { articlePath, articlesPath, pagePath } from './site';
+
+/**
+ * What a set of Shapio changes means for this site's pages: the arguments for Next's `revalidatePath`. Pure,
+ * so the mapping is unit-tested; src/lib/revalidation.ts feeds it from the snapshot diff.
+ */
+export type RevalidationTarget = { path: string; type?: 'page' | 'layout' };
+
+/** One entry's change in one locale, with its slugs (where it was and where it is; empty for models without). */
+export type ChangedEntry = { modelKey: string; locale: string; slugs: readonly string[] };
+
+/** Every page: the root layout holds them all (the siteSettings singleton is on each, in its header and footer). */
+export const EVERY_PAGE: RevalidationTarget = { path: '/', type: 'layout' };
+/** Every article page in every locale (each shows its author). */
+const EVERY_ARTICLE: RevalidationTarget = { path: '/[locale]/articles/[slug]', type: 'page' };
+
+/** The webhook events that can change what the site shows; anything else is acknowledged and ignored. */
+export const REVALIDATING_EVENTS: readonly string[] = [
+  'entry.published',
+  'entry.unpublished',
+  'entry.deleted',
+  'change_set.shipped',
+  'schema.activated',
+  'schema.deleted',
+  // "Send test" in Shapio's webhook screen: runs a real (usually empty) revalidation.
+  'webhook.test',
+];
+
+const targetsOf = ({ modelKey, locale, slugs }: ChangedEntry): RevalidationTarget[] => {
+  switch (modelKey) {
+    case 'page':
+      return slugs.map((slug) => ({ path: pagePath(locale, slug) }));
+    case 'article':
+      return [{ path: articlesPath(locale) }, ...slugs.map((slug) => ({ path: articlePath(locale, slug) }))];
+    case 'author':
+      return [{ path: articlesPath(locale) }, EVERY_ARTICLE];
+    case 'siteSettings':
+      return [EVERY_PAGE];
+    default:
+      // A model this site does not render.
+      return [];
+  }
+};
+
+const keyOf = (target: RevalidationTarget) => `${target.type ?? ''} ${target.path}`;
+
+/**
+ * The pages to revalidate, without duplicates. A schema change between the two snapshots (fields added,
+ * converted or removed without a republish) or a change to every page collapses to revalidating everything.
+ */
+export const revalidationTargets = (
+  entries: readonly ChangedEntry[],
+  schemaChanged: boolean,
+): RevalidationTarget[] => {
+  if (schemaChanged) {
+    return [EVERY_PAGE];
+  }
+  const targets = new Map<string, RevalidationTarget>();
+  for (const target of entries.flatMap(targetsOf)) {
+    targets.set(keyOf(target), target);
+  }
+  if (targets.has(keyOf(EVERY_PAGE))) {
+    return [EVERY_PAGE];
+  }
+  return [...targets.values()].sort((a, b) => a.path.localeCompare(b.path));
+};

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

@@ -0,0 +1,75 @@
+import { createClient, ShapioApiError, type DeliveryListQuery } from '@shapio/client';
+import { deliveryToken, shapioUrl, siteKey } from './config';
+import { liveSnapshot } from './liveSnapshot';
+import type { Locale } from './site';
+import type { Article, Page, SiteSettings } from './types';
+
+/**
+ * The site's read side: Shapio's delivery API through `@shapio/client`, at one publication snapshot. Next
+ * renders pages in several worker processes, so the snapshot is pinned once in next.config.ts (it sets
+ * SHAPIO_SNAPSHOT for the whole build) and every request here sends it. Under `next start`, /api/revalidate
+ * moves that snapshot forward (src/lib/liveSnapshot.ts).
+ */
+const PAGE_SIZE = 100;
+
+/** Delivery addresses a collection by its plural API ID, a singleton by its API ID. */
+const PAGES = 'pages';
+const ARTICLES = 'articles';
+const SITE_SETTINGS = 'siteSettings';
+
+/** The fields each read renders (`fields=`): smaller responses, and accurate field usage in Shapio. */
+const PAGE_FIELDS = ['title', 'slug', 'description', 'sections'];
+const ARTICLE_FIELDS = ['title', 'slug', 'excerpt', 'body', 'cover', 'author', 'publishedOn'];
+const SITE_SETTINGS_FIELDS = ['siteName', 'tagline', 'footer', 'colophon'];
+
+export const createShapio = () =>
+  createClient({ baseUrl: shapioUrl(), token: deliveryToken(), site: siteKey() });
+
+let client: ReturnType<typeof createShapio> | undefined;
+export const shapio = () => (client ??= createShapio());
+
+const snapshot = 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[]> => {
+  const entries: T[] = [];
+  for (let page = 1; ; page += 1) {
+    const result = await shapio().delivery.list<T>(routeKey, {
+      ...query,
+      snapshot: snapshot(),
+      page,
+      pageSize: PAGE_SIZE,
+    });
+    entries.push(...result.data);
+    if (page >= result.meta.pagination.pageCount) {
+      return entries;
+    }
+  }
+};
+
+export const listPages = (locale: Locale) => listAll<Page>(PAGES, { locale, fields: PAGE_FIELDS });
+
+export const listArticles = (locale: Locale) =>
+  listAll<Article>(ARTICLES, {
+    locale,
+    fields: ARTICLE_FIELDS,
+    populate: ['author'],
+    sort: [{ field: 'publishedOn', direction: 'desc' }],
+  });
+
+/** The siteSettings singleton in one locale; null until it is published. */
+export const getSiteSettings = async (locale: Locale): Promise<SiteSettings | null> => {
+  try {
+    const { data } = await shapio().delivery.singleton<SiteSettings>(SITE_SETTINGS, {
+      locale,
+      snapshot: snapshot(),
+      fields: SITE_SETTINGS_FIELDS,
+    });
+    return data;
+  } catch (error) {
+    if (error instanceof ShapioApiError && error.status === 404) {
+      return null;
+    }
+    throw error;
+  }
+};

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

@@ -0,0 +1,66 @@
+/** The site's locales (they must exist in Shapio: the seed creates `fr`; `en` is Shapio's default). */
+export const LOCALES = ['en', 'fr'] as const;
+export type Locale = (typeof LOCALES)[number];
+export const DEFAULT_LOCALE: Locale = 'en';
+
+/** The page whose slug is `home` is each locale's front page. */
+export const HOME_SLUG = 'home';
+
+export const isLocale = (value: string): value is Locale => (LOCALES as readonly string[]).includes(value);
+
+/** Reads a route's `[locale]` segment; the layout answers 404 for any other value. */
+export const toLocale = (value: string): Locale => (isLocale(value) ? value : DEFAULT_LOCALE);
+
+const STRINGS = {
+  en: {
+    siteName: 'Northwind Studio',
+    articles: 'Journal',
+    colophon: 'Colophon',
+    by: 'By',
+    switchTo: 'Français',
+    skipToContent: 'Skip to content',
+    footer: 'Built with Shapio',
+    previewBanner: 'Preview: this is a draft, not the published page.',
+    previewLoading: 'Loading the draft…',
+    previewFailed: 'The preview could not be loaded',
+    previewIncomplete: 'This preview link is incomplete.',
+  },
+  fr: {
+    siteName: 'Studio Northwind',
+    articles: 'Journal',
+    colophon: 'Colophon',
+    by: 'Par',
+    switchTo: 'English',
+    skipToContent: 'Aller au contenu',
+    footer: 'Construit avec Shapio',
+    previewBanner: 'Aperçu : ceci est un brouillon, pas la page publiée.',
+    previewLoading: 'Chargement du brouillon…',
+    previewFailed: "L'aperçu n'a pas pu être chargé",
+    previewIncomplete: "Ce lien d'aperçu est incomplet.",
+  },
+} as const satisfies Record<Locale, Record<string, string>>;
+
+export type Strings = (typeof STRINGS)[Locale];
+
+export const stringsFor = (locale: Locale): Strings => STRINGS[locale];
+
+export const otherLocale = (locale: Locale): Locale => (locale === 'en' ? 'fr' : 'en');
+
+export const formatDate = (iso: string, locale: string) =>
+  new Intl.DateTimeFormat(locale, { dateStyle: 'long', timeZone: 'UTC' }).format(new Date(iso));
+
+export const pagePath = (locale: string, slug: string) =>
+  slug === HOME_SLUG ? `/${locale}/` : `/${locale}/${slug}/`;
+export const articlesPath = (locale: string) => `/${locale}/articles/`;
+export const articlePath = (locale: string, slug: string) => `/${locale}/articles/${slug}/`;
+export const colophonPath = (locale: string) => `/${locale}/colophon/`;
+
+/** The same path in another locale (slugs are shared across locales in this starter's models). */
+export const switchLocale = (pathname: string, locale: Locale) =>
+  pathname.replace(/^\/(en|fr)(?=\/|$)/, `/${locale}`);
+
+/** Links from content: web, mail, phone and site-relative only (a `javascript:` URL becomes `#`). */
+export const safeHref = (value: string | null | undefined): string => {
+  const href = (value ?? '').trim();
+  return /^(https?:\/\/|mailto:|tel:|\/(?!\/)|#)/i.test(href) ? href : '#';
+};