create-shapio 0.4.1 → 0.5.1

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

@@ -1,13 +1,16 @@
-import { createClient, ShapioApiError, type DeliverySite } from '@shapio/client';
-import { configuredSnapshot, deliveryToken, shapioUrl, siteKey } from './config.js';
+import { createClient, ShapioApiError, type DeliveryListQuery, type DeliverySite } from '@shapio/client';
+import { configuredSnapshot, deliveryToken, isDev, isDraftsMode, shapioUrl, siteKey } from './config.js';
 import type { Locale } from './site.js';
-import type { Article, DeliveryList, Page, SiteSettings } from './types.js';
+import { cachedRead, cacheWindow, createSnapshotResolver } from './snapshotResolver.js';
+import type { Article, Page, SiteSettings } from './types.js';
 
 /**
  * The site's read side: Shapio's delivery API through `@shapio/client`, pinned to one publication snapshot
  * for the whole build. The snapshot is read once, when the build starts (or taken from SHAPIO_SNAPSHOT), and
  * sent with every request, so a page built a minute later still shows the same moment: a publish during the
- * build never yields a site that mixes old and new content.
+ * build never yields a site that mixes old and new content. Under `astro dev` the snapshot and the site settings
+ * are read again once the last read is a second old, so a publish shows on reload (src/lib/snapshotResolver.ts).
+ * Drafts mode (SHAPIO_DRAFTS=true) reads saved drafts, which have no snapshot: no read sends one.
  */
 const PAGE_SIZE = 100;
 
@@ -19,8 +22,8 @@ const ARTICLES = 'articles';
  * The fields each listing renders, sent as `fields=`: the response carries only these, and Shapio's field
  * usage shows exactly what the site reads (a whole-model read would count every field as used).
  */
-const PAGE_FIELDS = 'title,slug,description,sections,seo';
-const ARTICLE_FIELDS = 'title,slug,excerpt,body,cover,author,publishedOn,seo';
+const PAGE_FIELDS = ['title', 'slug', 'description', 'sections', 'seo'];
+const ARTICLE_FIELDS = ['title', 'slug', 'excerpt', 'body', 'cover', 'author', 'publishedOn', 'seo'];
 
 /** The `siteSettings` singleton is read by its API ID (singletons have no plural). */
 const SITE_SETTINGS = 'siteSettings';
@@ -28,40 +31,54 @@ const SITE_SETTINGS_FIELDS = ['siteName', 'tagline', 'footer', 'colophon'];
 
 let client: ReturnType<typeof createClient> | undefined;
 const shapio = () =>
-  (client ??= createClient({ baseUrl: shapioUrl(), token: deliveryToken(), site: siteKey() }));
+  (client ??= createClient({
+    baseUrl: shapioUrl(),
+    token: deliveryToken(),
+    site: siteKey(),
+    drafts: isDraftsMode(),
+  }));
 
-let pinned: Promise<number> | undefined;
+let resolver: (() => Promise<number>) | undefined;
 
-/** The snapshot every request of this build reads. */
-export const pinnedSnapshot = (): Promise<number> =>
-  (pinned ??= (async () => {
-    const configured = configuredSnapshot();
-    if (configured !== undefined) {
-      return configured;
-    }
-    const { snapshot } = await shapio().snapshots.current();
-    // Shared with any other copy of this module in the build (one value per build).
-    process.env.SHAPIO_SNAPSHOT = String(snapshot);
-    return snapshot;
-  })());
-
-const query = (params: Record<string, string | number>) =>
-  new URLSearchParams(Object.entries(params).map(([key, value]) => [key, String(value)])).toString();
+/**
+ * The snapshot every request reads: one for the whole build; in dev, the current one (re-read after 1 s); in
+ * drafts mode, none (drafts cannot be pinned).
+ */
+export const pinnedSnapshot = async (): Promise<number | undefined> => {
+  if (isDraftsMode()) {
+    return undefined;
+  }
+  const dev = isDev();
+  resolver ??= createSnapshotResolver({
+    dev,
+    configured: configuredSnapshot(),
+    current: async () => {
+      const { snapshot } = await shapio().snapshots.current();
+      if (!dev) {
+        // Shared with any other copy of this module in the build (one value per build).
+        process.env.SHAPIO_SNAPSHOT = String(snapshot);
+      }
+      return snapshot;
+    },
+  });
+  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,
-  locale: Locale,
-  extra: Record<string, string> = {},
-): Promise<T[]> => {
+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().request<DeliveryList<T>>(
+    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`).
-      `/api/content/${routeKey}?${query({ locale, snapshot, page, pageSize: PAGE_SIZE, richText: 'html', seo: 'resolved', ...extra })}`,
-    );
+      richText: 'html',
+      seo: 'resolved',
+      snapshot,
+      page,
+      pageSize: PAGE_SIZE,
+    });
     entries.push(...result.data);
     if (page >= result.meta.pagination.pageCount) {
       return entries;
@@ -69,55 +86,62 @@ const listAll = async <T>(
   }
 };
 
-export const listPages = (locale: Locale) => listAll<Page>(PAGES, locale, { fields: PAGE_FIELDS });
+export const listPages = (locale: Locale) => listAll<Page>(PAGES, { locale, fields: PAGE_FIELDS });
 
 export const listArticles = (locale: Locale) =>
-  listAll<Article>(ARTICLES, locale, {
+  listAll<Article>(ARTICLES, {
+    locale,
     fields: ARTICLE_FIELDS,
-    populate: 'author',
-    sort: 'publishedOn:desc',
+    populate: ['author'],
+    sort: [{ field: 'publishedOn', direction: 'desc' }],
   });
 
-const settingsByLocale = new Map<Locale, Promise<SiteSettings | null>>();
+const readSiteSettings = async (locale: Locale): Promise<SiteSettings | null> => {
+  try {
+    const { data } = await shapio().delivery.singleton<SiteSettings>(SITE_SETTINGS, {
+      locale,
+      snapshot: await pinnedSnapshot(),
+      fields: SITE_SETTINGS_FIELDS,
+      richText: 'html',
+    });
+    return data;
+  } catch (error) {
+    if (error instanceof ShapioApiError && error.status === 404) {
+      return null;
+    }
+    throw error;
+  }
+};
+
+const settingsByLocale = new Map<Locale, () => Promise<SiteSettings | null>>();
 
 /** The site settings singleton in one locale at the pinned snapshot; null until it is published. */
 export const getSiteSettings = (locale: Locale): Promise<SiteSettings | null> => {
   let settings = settingsByLocale.get(locale);
   if (!settings) {
-    settings = (async () => {
-      try {
-        const snapshot = await pinnedSnapshot();
-        const { data } = await shapio().delivery.singleton<SiteSettings>(SITE_SETTINGS, {
-          locale,
-          snapshot,
-          fields: SITE_SETTINGS_FIELDS,
-          richText: 'html',
-        });
-        return data;
-      } catch (error) {
-        if (error instanceof ShapioApiError && error.status === 404) {
-          return null;
-        }
-        throw error;
-      }
-    })();
+    settings = cachedRead(() => readSiteSettings(locale), cacheWindow(isDev()));
     settingsByLocale.set(locale, settings);
   }
-  return settings;
+  return settings();
 };
 
-let site: Promise<DeliverySite | null> | undefined;
+const readSite = async (): Promise<DeliverySite | null> => {
+  try {
+    return await shapio().site.get();
+  } catch (error) {
+    if (error instanceof ShapioApiError && error.status === 404) {
+      return null;
+    }
+    throw error;
+  }
+};
+
+let site: (() => Promise<DeliverySite | null>) | undefined;
 
 /**
  * The site and its SEO defaults (name and title template per locale, default image, Twitter handle), once per
- * build. Null when the Shapio predates them: the pages still render, with plain titles.
+ * build (in dev, re-read after 1 s). Null when the Shapio predates them: the pages still render, with plain
+ * titles.
  */
 export const getSite = (): Promise<DeliverySite | null> =>
-  (site ??= shapio()
-    .site.get()
-    .catch((error: unknown) => {
-      if (error instanceof ShapioApiError && error.status === 404) {
-        return null;
-      }
-      throw error;
-    }));
+  (site ??= cachedRead(readSite, cacheWindow(isDev())))();

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

@@ -22,6 +22,8 @@ const STRINGS = {
     previewLoading: 'Loading the draft…',
     previewFailed: 'The preview could not be loaded',
     skipToContent: 'Skip to content',
+    drafts: 'Drafts',
+    draftsNote: 'Drafts mode: this server shows saved drafts, not the published site.',
   },
   fr: {
     siteName: 'Studio Northwind',
@@ -36,6 +38,8 @@ const STRINGS = {
     previewLoading: 'Chargement du brouillon…',
     previewFailed: "L'aperçu n'a pas pu être chargé",
     skipToContent: 'Aller au contenu',
+    drafts: 'Brouillons',
+    draftsNote: 'Mode brouillons : ce serveur montre les brouillons enregistrés, pas le site publié.',
   },
 } as const satisfies Record<Locale, Record<string, string>>;
 

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

@@ -0,0 +1,64 @@
+import { describe, expect, it, vi } from 'vitest';
+import { cachedRead, createSnapshotResolver, DEV_WINDOW_MS } from './snapshotResolver.js';
+
+const clock = (start = 0) => {
+  let time = start;
+  return { now: () => time, advance: (ms: number) => (time += ms) };
+};
+
+describe('createSnapshotResolver', () => {
+  it('pins the first snapshot for the whole build', async () => {
+    const { now, advance } = clock();
+    const current = vi.fn().mockResolvedValueOnce(7).mockResolvedValue(8);
+    const snapshot = createSnapshotResolver({ dev: false, configured: undefined, current, now });
+
+    expect(await snapshot()).toBe(7);
+    advance(60 * 60 * 1000);
+    expect(await snapshot()).toBe(7);
+    expect(current).toHaveBeenCalledTimes(1);
+  });
+
+  it('reuses a dev read within the window and reads the current snapshot again after it', async () => {
+    const { now, advance } = clock();
+    const current = vi.fn().mockResolvedValueOnce(7).mockResolvedValue(8);
+    const snapshot = createSnapshotResolver({ dev: true, configured: undefined, current, now });
+
+    expect(await snapshot()).toBe(7);
+    advance(DEV_WINDOW_MS - 1);
+    expect(await snapshot()).toBe(7);
+    expect(current).toHaveBeenCalledTimes(1);
+
+    advance(1);
+    expect(await snapshot()).toBe(8);
+    expect(current).toHaveBeenCalledTimes(2);
+  });
+
+  it('keeps SHAPIO_SNAPSHOT in dev and in builds, without asking Shapio', async () => {
+    const current = vi.fn().mockResolvedValue(8);
+    for (const dev of [true, false]) {
+      const snapshot = createSnapshotResolver({ dev, configured: 3, current });
+      expect(await snapshot()).toBe(3);
+    }
+    expect(current).not.toHaveBeenCalled();
+  });
+});
+
+describe('cachedRead', () => {
+  it('shares one read between calls that overlap it', async () => {
+    const read = vi.fn().mockResolvedValue('value');
+    const cached = cachedRead(read, DEV_WINDOW_MS, clock().now);
+
+    const [first, second] = await Promise.all([cached(), cached()]);
+    expect([first, second]).toEqual(['value', 'value']);
+    expect(read).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not keep a failed read', async () => {
+    const read = vi.fn().mockRejectedValueOnce(new Error('down')).mockResolvedValue('value');
+    const cached = cachedRead(read, Number.POSITIVE_INFINITY, clock().now);
+
+    await expect(cached()).rejects.toThrow('down');
+    expect(await cached()).toBe('value');
+    expect(read).toHaveBeenCalledTimes(2);
+  });
+});

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

@@ -0,0 +1,52 @@
+/**
+ * Which publication snapshot the site reads, and for how long a read is reused. A build pins one snapshot
+ * for all its pages (SHAPIO_SNAPSHOT, else the current one when the build starts). The dev server reads the
+ * current snapshot again once the last read is older than DEV_WINDOW_MS, so a publish shows on reload while
+ * the reads of one page render still share a snapshot.
+ */
+export const DEV_WINDOW_MS = 1000;
+
+/** How long a cached read is reused: for the whole process in a build, DEV_WINDOW_MS in dev. */
+export const cacheWindow = (dev: boolean): number => (dev ? DEV_WINDOW_MS : Number.POSITIVE_INFINITY);
+
+/** `read`, reused for `windowMs` after it starts. A read that fails is not kept: the next call tries again. */
+export const cachedRead = <T>(
+  read: () => Promise<T>,
+  windowMs: number,
+  now: () => number = Date.now,
+): (() => Promise<T>) => {
+  let cached: { value: Promise<T>; at: number } | undefined;
+  return () => {
+    const at = now();
+    if (cached && at - cached.at < windowMs) {
+      return cached.value;
+    }
+    const entry = { value: read(), at };
+    cached = entry;
+    entry.value.catch(() => {
+      if (cached === entry) {
+        cached = undefined;
+      }
+    });
+    return entry.value;
+  };
+};
+
+type SnapshotResolverOptions = {
+  /** True under the dev server. */
+  dev: boolean;
+  /** SHAPIO_SNAPSHOT: when set, the site shows exactly this snapshot, in dev too. */
+  configured: number | undefined;
+  /** Reads Shapio's current publication snapshot. */
+  current: () => Promise<number>;
+  now?: () => number;
+};
+
+/** The snapshot every delivery read sends. */
+export const createSnapshotResolver = ({
+  dev,
+  configured,
+  current,
+  now,
+}: SnapshotResolverOptions): (() => Promise<number>) =>
+  configured === undefined ? cachedRead(current, cacheWindow(dev), now) : () => Promise.resolve(configured);

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

@@ -91,13 +91,4 @@ export type SiteSettings = EntryBase & {
   colophon: RichText | null;
 };
 
-export type DeliveryList<T> = {
-  data: T[];
-  meta: {
-    locale: string;
-    snapshot: number;
-    pagination: { page: number; pageSize: number; total: number; pageCount: number };
-  };
-};
-
 export type DeliveryItem<T> = { data: T; meta: { locale: string; snapshot: number } };

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

@@ -1,6 +1,8 @@
 ---
 import Base from '../../layouts/Base.astro';
+import { isDev } from '../../lib/config.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';
@@ -20,7 +22,16 @@ export const getStaticPaths = async () => {
 };
 
 type Props = { page: Page; locale: Locale };
-const { page, locale } = Astro.props;
+const { locale } = Astro.props;
+// In `astro dev`, read at render time (src/lib/renderTime.ts); a build renders the props above.
+const page = await renderTimeEntry({
+  dev: isDev(),
+  props: Astro.props.page,
+  read: async () => findBySlug(await listPages(locale), Astro.params.slug ?? HOME_SLUG),
+});
+if (!page) {
+  return Astro.rewrite('/404/');
+}
 ---
 
 <Base title={page.title} seo={page.seo} locale={locale} alternatePath={pagePath(otherLocale(locale), page.slug)}>

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

@@ -1,6 +1,8 @@
 ---
 import Base from '../../../layouts/Base.astro';
+import { isDev } from '../../../lib/config.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';
@@ -16,7 +18,16 @@ export const getStaticPaths = async () => {
 };
 
 type Props = { locale: Locale; article: Article };
-const { locale, article } = Astro.props;
+const { locale } = Astro.props;
+// In `astro dev`, read at render time (src/lib/renderTime.ts); a build renders the props above.
+const article = await renderTimeEntry({
+  dev: isDev(),
+  props: Astro.props.article,
+  read: async () => findBySlug(await listArticles(locale), Astro.params.slug ?? ''),
+});
+if (!article) {
+  return Astro.rewrite('/404/');
+}
 const context = { locale, strings: stringsFor(locale) };
 ---
 

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

@@ -1,6 +1,8 @@
 ---
 import Base from '../../../layouts/Base.astro';
+import { isDev } from '../../../lib/config.js';
 import { renderArticleCard } from '../../../lib/render.js';
+import { renderTimeEntry } from '../../../lib/renderTime.js';
 import { listArticles } from '../../../lib/shapio.js';
 import { articlesPath, LOCALES, otherLocale, stringsFor, type Locale } from '../../../lib/site.js';
 import type { Article } from '../../../lib/types.js';
@@ -11,7 +13,10 @@ export const getStaticPaths = async () =>
   );
 
 type Props = { locale: Locale; articles: Article[] };
-const { locale, articles } = Astro.props;
+const { locale } = Astro.props;
+// In `astro dev`, read at render time (src/lib/renderTime.ts); a build renders the props above.
+const articles =
+  (await renderTimeEntry({ dev: isDev(), props: Astro.props.articles, read: () => listArticles(locale) })) ?? [];
 const strings = stringsFor(locale);
 const context = { locale, strings };
 ---

package/templates/astro/src/pages/build.json.ts

@@ -1,9 +1,16 @@
 import { pinnedSnapshot } from '../lib/shapio.js';
 import { LOCALES } from '../lib/site.js';
 
-/** `/build.json`: which publication snapshot this build shows (for checks and deployment debugging). */
+/**
+ * `/build.json`: which publication snapshot this build shows (for checks and deployment debugging); null in
+ * drafts mode, which shows saved drafts.
+ */
 export const GET = async () =>
   new Response(
-    JSON.stringify({ snapshot: await pinnedSnapshot(), locales: LOCALES, builtAt: new Date().toISOString() }),
+    JSON.stringify({
+      snapshot: (await pinnedSnapshot()) ?? null,
+      locales: LOCALES,
+      builtAt: new Date().toISOString(),
+    }),
     { headers: { 'content-type': 'application/json' } },
   );

package/templates/astro/src/styles/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/.env.example

@@ -15,3 +15,13 @@ NEXT_TELEMETRY_DISABLED=1
 # NEXT_PUBLIC_SHAPIO_URL=https://cms.example.com
 # Optional: this site's public origin; pages then carry a canonical URL and og:url.
 # SITE_URL=https://www.example.com
+# Optional: read Shapio's delivery API in this server process instead of over HTTP (@shapio/local), from
+# Shapio's own database. A read-only database role is enough. Previews still use SHAPIO_URL.
+# SHAPIO_MODE=in-process
+# DATABASE_URL=postgres://shapio_site:password@localhost:5432/shapio
+# Optional, development only: drafts mode. Every read shows saved drafts instead of published content, fresh
+# on every request, with a "Drafts" badge on each page. Needs a delivery token whose role grants Read drafts:
+# SHAPIO_DEV_DELIVERY_TOKEN (`npm run seed` writes one), else SHAPIO_DELIVERY_TOKEN. Never put that token or
+# this flag in a production environment.
+# SHAPIO_DRAFTS=true
+# SHAPIO_DEV_DELIVERY_TOKEN=

package/templates/next/README.md

@@ -22,16 +22,26 @@ npm test            # unit tests (path mapping, signature check)
 `next.config.ts` pins the latest one when the build starts); `SHAPIO_SITE` picks the site on a multi-site
 instance. Next.js telemetry is off: `NEXT_TELEMETRY_DISABLED=1` in the npm scripts and `.env.example`.
 
-| File                         | Role                                                                |
-| ---------------------------- | ------------------------------------------------------------------- |
-| `next.config.ts`             | pins the snapshot; `/` redirects to `/en/`; `frame-ancestors`       |
-| `src/lib/shapio.ts`          | reads the delivery API with `@shapio/client` at the pinned snapshot |
-| `src/app/[locale]/…`         | the layout (site settings), pages, articles and the colophon        |
-| `src/components/…`           | sections, articles and responsive images                            |
-| `src/app/preview/`           | draft preview with visual editing (`@shapio/visual`)                |
-| `src/app/api/revalidate/`    | the webhook target: on-demand revalidation of changed pages         |
-| `src/lib/revalidation*.ts`   | the snapshot diff and which pages a change touches                  |
-| `shapio/`, `scripts/seed.ts` | the models and the seed                                             |
+| File                         | Role                                                               |
+| ---------------------------- | ------------------------------------------------------------------ |
+| `next.config.ts`             | pins the snapshot; `/` redirects to `/en/`; `frame-ancestors`      |
+| `src/lib/shapio.ts`          | reads the delivery API at the pinned snapshot                      |
+| `src/lib/shapioClient.ts`    | over HTTP (`@shapio/client`) or in process (`@shapio/local`)       |
+| `src/app/[locale]/…`         | the layout (site settings), pages, articles and the colophon       |
+| `src/components/…`           | sections, articles and responsive images                           |
+| `src/app/preview/`           | draft preview with visual editing (`@shapio/visual`)               |
+| `src/app/api/revalidate/`    | the webhook target: on-demand revalidation of changed pages        |
+| `src/lib/revalidation*.ts`   | the snapshot diff, and which pages and cache tags a change touches |
+| `shapio/`, `scripts/seed.ts` | the models and the seed                                            |
+
+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
+Shapio, reload, and the change is there; publishing still rebuilds the live site. It reads with
+`SHAPIO_DEV_DELIVERY_TOKEN`, the seed's `<site> dev` token, whose delivery role grants Read drafts (a token
+without it fails with `DRAFTS_FORBIDDEN`). Never put that token or the flag in a production environment.
+`npm run smoke:drafts` checks a running drafts-mode dev server
+(http://localhost:3000; 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).
 
 Preview: the seed creates a deployment connection named **Preview** that opens drafts at
 `http://localhost:3000/preview/` (set `SITE_URL` when seeding for another address). Add that origin to Shapio's
@@ -39,6 +49,18 @@ Preview: the seed creates a deployment connection named **Preview** that opens d
 re-render the draft ([visual editing](https://github.com/mybrokengnome/shapio/blob/main/documentation/visual-editing.md)). `NEXT_PUBLIC_SHAPIO_URL` sets the Shapio URL the browser
 calls, when it differs from `SHAPIO_URL`.
 
+## Reading in process
+
+By default the site reads Shapio's delivery API over HTTP. With `SHAPIO_MODE=in-process` and `DATABASE_URL` set
+to Shapio's own database (PostgreSQL or MySQL), it reads the same API as function calls in the Next.js server
+process (`@shapio/local`), with no HTTP hop: the same delivery token, the same answers, the same pages.
+`next.config.ts` lists `@shapio/local` in `serverExternalPackages`, so each server process opens one database
+pool. Previews and the browser still use `SHAPIO_URL`, and the Shapio server keeps running (it applies schema
+changes and sends the revalidation webhook). Install the same `@shapio/local` version as the server's release;
+the scaffolded `package.json` pins it. Reads in process do not go through `fetch`, so the cache tags below do
+not apply to them; `revalidatePath` still refreshes the pages. Guide:
+[in-process delivery](https://github.com/mybrokengnome/shapio/blob/main/documentation/in-process.md).
+
 ## Incremental rebuilds (on-demand revalidation)
 
 With `npm run start`, a publish refreshes only the pages it changed, without a rebuild:
@@ -55,7 +77,11 @@ With `npm run start`, a publish refreshes only the pages it changed, without a r
    changed between the snapshot the site shows and the current one (`/api/snapshots/changes`), and calls
    `revalidatePath` for those pages: an article's page and its locale's list, a page by its slug (`home` is
    `/en/`), the list and every article page for an author, every page for the `siteSettings` singleton or a
-   schema change. A changed slug refreshes the old and the new address.
+   schema change. A changed slug refreshes the old and the new address. Reads are tagged by `@shapio/client` with
+   the site, the model and the entry, so the route also calls `revalidateTag` for each changed model and entry;
+   `site.updated` and a schema change expire the site tag, which every read carries. Content reads are pinned to
+   a snapshot, so they sit in Next's data cache (`force-cache`) regardless; the client sets no cache mode, so
+   `site.get()` stays fresh on every build (the data cache outlives `next build`).
 3. The site moves to the new snapshot: revalidated pages re-render at it, and the snapshot is kept in
    `.next/shapio-revalidate.json` so a restart carries on from it. `next build` empties `.next/`, so a new build
    starts again from its own snapshot.

package/templates/next/next.config.ts

@@ -1,29 +1,31 @@
-import { createClient } from '@shapio/client';
 import type { NextConfig } from 'next';
 import { PHASE_PRODUCTION_BUILD } from 'next/constants.js';
+import { createShapioClient } from './src/lib/shapioClient';
 
 /**
  * Pins one publication snapshot for the whole `next build`: Next renders pages in several worker processes, so
  * the snapshot is read here, once, before any page renders, and handed to every worker as SHAPIO_SNAPSHOT
  * (inlined into the build). A set SHAPIO_SNAPSHOT wins and pins the site for good; otherwise `next start` moves
  * forward from this snapshot as Shapio's webhook calls /api/revalidate (src/lib/liveSnapshot.ts). `next dev` and
- * `next start` do not read Shapio here.
+ * `next start` do not read Shapio here. Drafts mode (SHAPIO_DRAFTS=true) pins nothing: drafts have no
+ * snapshot.
  */
 const pinSnapshot = async (): Promise<string> => {
   if (process.env.SHAPIO_SNAPSHOT) {
     return process.env.SHAPIO_SNAPSHOT;
   }
-  const token = process.env.SHAPIO_DELIVERY_TOKEN;
-  if (!token) {
-    throw new Error('Set SHAPIO_DELIVERY_TOKEN to build the site; `npm run seed` writes one to .env');
+  if (process.env.SHAPIO_DRAFTS === 'true') {
+    return '';
+  }
+  // Over HTTP or in process, as the pages read (SHAPIO_MODE).
+  const client = createShapioClient();
+  try {
+    const { snapshot } = await client.snapshots.current();
+    return String(snapshot);
+  } finally {
+    // An in-process client holds database connections; this process has no further use for them.
+    await client.close?.();
   }
-  const client = createClient({
-    baseUrl: process.env.SHAPIO_URL || 'http://localhost:4300',
-    token,
-    site: process.env.SHAPIO_SITE || undefined,
-  });
-  const { snapshot } = await client.snapshots.current();
-  return String(snapshot);
 };
 
 const originOf = (url: string) => {
@@ -47,6 +49,9 @@ const frameAncestors = () => {
 
 const nextConfig = async (phase: string): Promise<NextConfig> => ({
   trailingSlash: true,
+  // SHAPIO_MODE=in-process: loaded from node_modules once per server process (one database pool), not
+  // bundled into every route.
+  serverExternalPackages: ['@shapio/local'],
   headers: async () => [
     { source: '/:path*', headers: [{ key: 'Content-Security-Policy', value: frameAncestors() }] },
   ],

package/templates/next/package.json

@@ -13,12 +13,14 @@
     "start": "NEXT_TELEMETRY_DISABLED=1 next start",
     "seed": "node --env-file-if-exists=.env --import tsx scripts/seed.ts --site-url http://localhost:3000 --revalidate-path /api/revalidate/",
     "smoke": "node --env-file-if-exists=.env --import tsx scripts/smokeHttp.ts --url http://localhost:3000",
+    "smoke:drafts": "node --env-file-if-exists=.env --import tsx scripts/smokeDrafts.ts --url http://localhost:3000",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run"
   },
   "dependencies": {
-    "@shapio/client": "^0.4.1",
-    "@shapio/visual": "^0.4.1",
+    "@shapio/client": "^0.5.1",
+    "@shapio/local": "0.5.1",
+    "@shapio/visual": "^0.5.1",
     "next": "16.3.8",
     "react": "19.3.0",
     "react-dom": "19.3.0"