fontdue-js 3.0.0-alpha11 → 3.0.0-alpha12

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 3.0.0
+
+In alpha on the `alpha` dist-tag — install with `npm install fontdue-js@alpha`.
+
+- **Framework-agnostic.** fontdue-js now works in any React SSR or client-only environment — Astro, React Router 7, TanStack Start, Vike, Remix, and the existing Next.js App Router — not just Next.js. Each supported framework has a worked example repo (see the README "Examples"). The package is now ESM-only and ships an `exports` map, so TypeScript consumers need `moduleResolution` set to `bundler`, `node16`, or `nodenext`.
+- **Admin preview for every framework.** A preview toolbar — rendered by `<FontdueProvider>` and shown only to logged-in admins — reveals hidden (unpublished) fonts site-wide. New entry points implement a portable contract:
+  - `fontdue-js/preview` — `handlePreviewRequest` (a Web-standard enter/exit route handler), `readPreviewToken`, `previewAuthHeaders`, and the cookie/endpoint constants.
+  - `fontdue-js/preview/server` — `runWithPreview`, which holds the preview token in `AsyncLocalStorage` for the duration of a request so every server fetch and preload forwards it automatically, and forces preview responses out of shared/CDN caches so an admin's render is never served to the public.
+
+  On Next.js (which has no app-installable ambient context) the adapter's `prepareFontdueRender` folds the draft-mode token into the per-render config instead — the same effect, so the embedded components reveal hidden fonts server-side. See the README "Admin preview".
+- **One server fetch for every framework.** `fontdue-js/server` exports `createFontdueFetch({ url?, headers?, cacheTags? })` — a ready-made server-side GraphQL fetcher with URL resolution, error handling, `FontdueNotFoundError`, and automatic preview-token forwarding. Each input resolves per call from the explicit option, the per-render config (`runWithPreview` or the Next adapter), then the environment, and passing `cacheTags` opts the fetch into Next's data cache + `/api/revalidate` (inert in other runtimes) — so Next and the other frameworks now share the same fetcher rather than Next hand-rolling its own. See the README "Server-side GraphQL fetches".
+- **Server-rendered embeds.** Components now render their full HTML on the server where the framework supports it (v2 hydrated some empty and fetched on the client), via the `load{Component}Query()` preload helpers.
+- **Migrating from v2 (Next.js)** is a small, mechanical upgrade — see the README "Migrating a Next.js site from v2". `useFontStyle` is renamed to `useFont` (the old name still works as an alias).
+
 ## 2.28.0
 
 - Checkout now captures the buyer's **analytics consent and ad attribution** on the order. When the cart or store-modal checkout opens, fontdue-js sends the consent-banner state, anonymous ID, Meta browser IDs (the `_fbp`/`_fbc` cookies), and the page URL to the server, where they're stored on the order. This lets Fontdue emit a server-side *purchase* conversion event (Facebook Conversions API, Google Ads) when the order completes — completion happens in a Stripe webhook, outside the browser — while respecting the buyer's cookie-consent choice: if consent was declined, no identifiers are sent and nothing is forwarded to ad platforms. The call is fire-and-forget and never affects checkout.

package/README.md

@@ -417,27 +417,26 @@ fontdue-js's own server-side fetches opt into Next's data cache (and the `graphq
 
 ### Your own GraphQL fetches
 
-`currentFontdueEndpoint()` (from `fontdue-js/next`) describes the endpoint your own server-side [GraphQL](https://docs.fontdue.com/graphql-api) fetches should use — the base origin, required headers, and the cache tags that tie them into `/api/revalidate`:
+Use the same [`createFontdueFetch`](#server-side-graphql-fetches) as every other framework, and give it the current render's endpoint so it ties into Next's data cache and `/api/revalidate`. `currentFontdueEndpoint()` (from `fontdue-js/next`) describes that endpoint — the base origin, required headers, and the per-site cache tags:
 
 ```ts
+import { createFontdueFetch } from "fontdue-js/server";
 import { currentFontdueEndpoint } from "fontdue-js/next";
 
-export async function fetchGraphql(query: string, variables?: unknown) {
+export async function fetchGraphql<Q>(name: string, query: string, variables?: unknown) {
   const endpoint = currentFontdueEndpoint();
-  const response = await fetch(`${endpoint.origin}/graphql`, {
-    method: "POST",
-    body: JSON.stringify({ query, variables }),
-    headers: { "content-type": "application/json", ...endpoint.headers },
-    // Cache explicitly (Next 15 doesn't cache fetch by default), tagged so
-    // the deploy hook purges this too.
-    cache: "force-cache",
-    next: { tags: endpoint.tags },
+  const fetchFontdue = createFontdueFetch({
+    url: endpoint.origin,
+    headers: endpoint.headers,
+    // Opts the fetch into Next's data cache (force-cache) and tags it so the
+    // deploy hook purges it. Drop cacheTags (pass `[]`) on a preview render.
+    cacheTags: endpoint.tags,
   });
-  return (await response.json()).data;
+  return fetchFontdue<Q>(name, query, variables);
 }
 ```
 
-The shape is exported as `type FontdueEndpoint`.
+`currentFontdueEndpoint()` resolves the per-render tenant in multi-tenant mode (after `prepareFontdueRender`) or the `NEXT_PUBLIC_FONTDUE_URL` site otherwise; the shape is exported as `type FontdueEndpoint`. Route handlers render outside React, so pass the endpoint they got from `prepareFontdueRender` explicitly. For preview, see [Admin preview → Next.js](#nextjs).
 
 ## Migrating a Next.js site from v2
 
@@ -469,7 +468,7 @@ For a site built on the [example repo](https://github.com/fontdue/example-next)
 
    Keep the Deploy hook URL in your Fontdue admin pointed at it.
 
-4. **Delete caching workarounds you no longer need.** `export const fetchCache = "default-cache"` in the layout (if you added it) is obsolete — fontdue-js opts its own fetches into the data cache now. Your app's own GraphQL fetches should pass `cache: "force-cache"` and `next: { tags: endpoint.tags }` explicitly — see [Your own GraphQL fetches](#your-own-graphql-fetches).
+4. **Delete caching workarounds you no longer need.** `export const fetchCache = "default-cache"` in the layout (if you added it) is obsolete — fontdue-js opts its own fetches into the data cache now. For your app's own GraphQL fetches, move the transport to `createFontdueFetch` and pass it `cacheTags: endpoint.tags` so caching and `/api/revalidate` are handled for you — see [Your own GraphQL fetches](#your-own-graphql-fetches).
 
 5. **Remove the `url` prop from `<FontdueProvider>` if you passed one.** It never configured server-side fetches (server components have no context); v3 resolves everything from `NEXT_PUBLIC_FONTDUE_URL`. The prop still works as a client-side runtime override, but with the env var set you don't need it.
 
@@ -479,6 +478,159 @@ What you get for it: server components now render the embeds' full HTML on the s
 
 If you're starting fresh instead of migrating, fork the example repo — it ships in this shape already.
 
+## Server-side GraphQL fetches
+
+Beyond the preload helpers, you'll often run your own [GraphQL](https://docs.fontdue.com/graphql-api) queries server-side — page chrome, metadata, custom sections. `fontdue-js/server` exports a ready-made fetcher so you don't hand-roll the transport:
+
+```ts
+import { createFontdueFetch } from "fontdue-js/server";
+
+// One fetcher for the whole app. Resolves the Fontdue URL from the environment
+// (FONTDUE_URL / PUBLIC_FONTDUE_URL / VITE_FONTDUE_URL).
+export const fetchGraphql = createFontdueFetch();
+
+// In a loader / frontmatter / server component:
+const data = await fetchGraphql<IndexQuery>("Index", indexQuery, { slug });
+```
+
+`createFontdueFetch({ url?, headers?, cacheTags? })` returns `fetchGraphql(operationName, query, variables?)`. It POSTs to `/graphql`, unwraps `data`, throws on GraphQL errors, and throws `FontdueNotFoundError` when the host doesn't resolve to a site — catch it to render your framework's 404. It's the same fetcher in every framework; each input resolves per call from the explicit option, then the per-render config (set by `runWithPreview` or the Next adapter), then the environment:
+
+- **url** — option → per-render tenant URL → `FONTDUE_URL` / `PUBLIC_FONTDUE_URL` / `VITE_FONTDUE_URL`.
+- **headers** — merged ambient + explicit (explicit wins); this is how the [admin preview](#admin-preview) token is forwarded automatically.
+- **cacheTags** — when present, the fetch opts into Next's data cache (`force-cache` + tags) so `/api/revalidate` can purge it; absent/empty leaves it uncached. The Next hints are inert in other runtimes, where HTML is cached at the response/CDN layer instead.
+
+**Upgrading a hand-rolled fetch.** If you already have something like this:
+
+```ts
+// Before — hand-rolled.
+async function fetchGraphql(name, query, variables) {
+  const res = await fetch(`${import.meta.env.PUBLIC_FONTDUE_URL}/graphql`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ query, variables }),
+  });
+  const json = await res.json();
+  if (json.errors) throw new Error(json.errors[0].message);
+  return json.data;
+}
+```
+
+replace it with:
+
+```ts
+// After.
+import { createFontdueFetch } from "fontdue-js/server";
+export const fetchGraphql = createFontdueFetch();
+```
+
+You get URL resolution, error handling, `FontdueNotFoundError`, and automatic preview-token forwarding for free.
+
+> **Next.js:** the same `createFontdueFetch` — pass it the endpoint's `cacheTags` so it ties into Next's data cache and the `/api/revalidate` deploy hook. See [Your own GraphQL fetches](#your-own-graphql-fetches) under the Next adapter.
+
+## Admin preview
+
+Logged-in Fontdue admins get a preview toolbar — rendered automatically by `<FontdueProvider>`, hidden for everyone else — that reveals **hidden (unpublished) fonts** across the whole site. The toolbar brokers a short-lived admin token and POSTs it to a small preview route on your own origin; from then on, server renders forward the token so GraphQL returns the unpublished content. The public never has the cookie, so their renders stay sessionless and cacheable.
+
+Two entry points cover this: `fontdue-js/preview` (the portable cookie contract) and `fontdue-js/preview/server` (the ambient wiring).
+
+**1. Add the preview route** at `/api/preview` — the toolbar POSTs to enter preview and DELETEs to exit. `handlePreviewRequest` is a Web-standard `Request → Response` handler, so it drops into any Fetch-API framework:
+
+```ts
+// Astro — src/pages/api/preview.ts
+import { handlePreviewRequest } from "fontdue-js/preview";
+export const ALL = ({ request }) => handlePreviewRequest(request);
+export const prerender = false;
+```
+
+```ts
+// React Router 7 — app/routes/api.preview.ts
+import { handlePreviewRequest } from "fontdue-js/preview";
+export const action = ({ request }) => handlePreviewRequest(request);
+```
+
+The path is configurable via `config.preview.endpoint` on `<FontdueProvider>` (default `/api/preview`) — mount the route to match.
+
+**2. Forward the token on server renders.** The recommended way is ambient: wrap each request in `runWithPreview` (from `fontdue-js/preview/server`) in your framework's middleware. While it's active, every `createFontdueFetch` call and every `load*Query()` preload forwards the token automatically — no per-call plumbing — and preview responses are forced out of any shared/CDN cache so an admin's render is never served to the public.
+
+```ts
+// Astro — src/middleware.ts
+import { runWithPreview } from "fontdue-js/preview/server";
+export const onRequest = (ctx, next) => runWithPreview(ctx.request, next);
+```
+
+```ts
+// React Router 7 — root route (with future.v8_middleware enabled)
+import { runWithPreview } from "fontdue-js/preview/server";
+export const middleware = [({ request }, next) => runWithPreview(request, next)];
+```
+
+`runWithPreview` uses `AsyncLocalStorage`, so it works wherever middleware shares a runtime with the render — Node (the default SSR target on Netlify/Vercel), Deno, Bun.
+
+**Explicit alternative.** Where the ambient context can't propagate (e.g. middleware running in a separate runtime from the render, such as Astro's `edgeMiddleware: true`), read the token yourself and pass it as the `{ headers }` option, which always overrides the ambient context:
+
+```ts
+import { readPreviewToken, previewAuthHeaders } from "fontdue-js/preview";
+
+const headers = previewAuthHeaders(readPreviewToken(request.headers.get("cookie")));
+const fetchGraphql = createFontdueFetch({ headers });
+const preload = await loadTypeTesterQuery(vars, { headers });
+```
+
+`previewAuthHeaders` returns `{}` when there's no token, so it's always safe to pass.
+
+### Next.js
+
+Next uses [draft mode](https://nextjs.org/docs/app/building-your-application/configuring/draft-mode) rather than ambient context. The route layers `draftMode()` on top of `handlePreviewRequest`:
+
+```ts
+// app/api/preview/route.ts
+import { draftMode } from "next/headers";
+import { handlePreviewRequest } from "fontdue-js/preview";
+
+export async function POST(request: Request) {
+  const response = await handlePreviewRequest(request);
+  if (response.ok) (await draftMode()).enable();
+  return response;
+}
+
+export async function DELETE(request: Request) {
+  const response = await handlePreviewRequest(request);
+  (await draftMode()).disable();
+  return response;
+}
+```
+
+Two things then forward the token on a Next render:
+
+- **`prepareFontdueRender`** — the call you already make at the top of every page folds the draft-mode token into the per-render config, so the embedded components (type testers, store) reveal hidden fonts server-side automatically. This is the Next counterpart to `runWithPreview`.
+- **Your own fetch** reads draft mode and hands the token to `createFontdueFetch`, dropping the cache tags so the render stays live:
+
+```ts
+import { draftMode, cookies } from "next/headers";
+import { createFontdueFetch } from "fontdue-js/server";
+import { currentFontdueEndpoint } from "fontdue-js/next";
+import { PREVIEW_TOKEN_COOKIE, previewAuthHeaders } from "fontdue-js/preview";
+
+export async function fetchGraphql<Q>(name: string, query: string, variables?: unknown) {
+  const endpoint = currentFontdueEndpoint();
+  // draftMode()/cookies() are request-scoped — guard build-time static
+  // generation, where they throw, as "not preview".
+  const isPreview = (await draftMode()).isEnabled;
+  const token = isPreview ? (await cookies()).get(PREVIEW_TOKEN_COOKIE)?.value : undefined;
+
+  const fetchFontdue = createFontdueFetch({
+    url: endpoint.origin,
+    headers: { ...endpoint.headers, ...previewAuthHeaders(token) },
+    // Public renders are tagged + cached; preview renders pass no tags so they
+    // stay live and reveal hidden fonts.
+    cacheTags: isPreview ? [] : endpoint.tags,
+  });
+  return fetchFontdue<Q>(name, query, variables);
+}
+```
+
+The example repos wire this up end to end for each framework.
+
 ## UI config
 
 Most components accept a `config` object that controls UI behavior — type-tester options (`selectable`, `priceBar`, size ranges, OpenType-feature UI…), store-modal layout, form styling, analytics tracking, and more. See the [full config reference](https://docs.fontdue.com/fontduejs#b3dec49aa08240bba2b4c71a67c08333).

package/dist/__tests__/createFontdueFetch.test.js

@@ -1,9 +1,19 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { createFontdueFetch, FontdueNotFoundError } from '../server/index.js';
+import { registerAmbientConfigResolver } from '../relay/serverConfig.js';
 beforeEach(() => {
   vi.unstubAllEnvs();
   vi.unstubAllGlobals();
 });
+
+// Several tests inject a per-render config through the ambient resolver seam
+// (the same seam runWithPreview and the Next slot use). Always clear it.
+afterEach(() => {
+  registerAmbientConfigResolver(() => undefined);
+});
+function withConfig(config) {
+  registerAmbientConfigResolver(() => config);
+}
 function mockFetch(impl) {
   const fetchMock = vi.fn(async (url, init) => impl(url, init));
   vi.stubGlobal('fetch', fetchMock);
@@ -98,7 +108,115 @@ describe('createFontdueFetch', () => {
     await fetchGraphql('Q', 'query Q { __typename }');
     expect(fetchMock.mock.calls[0][0]).toBe('https://env.fontdue.com/graphql?query=Q');
   });
-  it('throws a helpful error when no URL is configured', () => {
-    expect(() => createFontdueFetch()).toThrow(/no Fontdue URL configured/);
+  it('throws a helpful error when no URL is configured (resolved per call)', async () => {
+    mockFetch(() => ({
+      status: 200,
+      json: async () => ({
+        data: {}
+      })
+    }));
+    const fetchGraphql = createFontdueFetch();
+    await expect(fetchGraphql('Q', 'query Q { __typename }')).rejects.toThrow(/no Fontdue URL configured/);
+  });
+  describe('Next data cache tags', () => {
+    it('opts into force-cache + tags when cacheTags are given', async () => {
+      var _init$next;
+      const fetchMock = mockFetch(() => ({
+        status: 200,
+        json: async () => ({
+          data: {}
+        })
+      }));
+      const fetchGraphql = createFontdueFetch({
+        url: 'https://acme.fontdue.com',
+        cacheTags: ['graphql:acme.fontdue.com']
+      });
+      await fetchGraphql('Q', 'query Q { __typename }');
+      const init = fetchMock.mock.calls[0][1];
+      expect(init.cache).toBe('force-cache');
+      // The global `graphql` tag is prepended automatically.
+      expect((_init$next = init.next) === null || _init$next === void 0 ? void 0 : _init$next.tags).toEqual(['graphql', 'graphql:acme.fontdue.com']);
+    });
+    it('leaves the fetch uncached when no cacheTags are given', async () => {
+      const fetchMock = mockFetch(() => ({
+        status: 200,
+        json: async () => ({
+          data: {}
+        })
+      }));
+      const fetchGraphql = createFontdueFetch({
+        url: 'https://acme.fontdue.com'
+      });
+      await fetchGraphql('Q', 'query Q { __typename }');
+      const init = fetchMock.mock.calls[0][1];
+      expect(init.cache).toBeUndefined();
+      expect(init.next).toBeUndefined();
+    });
+    it('treats an empty cacheTags list as uncached (preview renders)', async () => {
+      const fetchMock = mockFetch(() => ({
+        status: 200,
+        json: async () => ({
+          data: {}
+        })
+      }));
+      const fetchGraphql = createFontdueFetch({
+        url: 'https://acme.fontdue.com',
+        cacheTags: []
+      });
+      await fetchGraphql('Q', 'query Q { __typename }');
+      const init = fetchMock.mock.calls[0][1];
+      expect(init.cache).toBeUndefined();
+      expect(init.next).toBeUndefined();
+    });
+  });
+  describe('per-render config (the Next slot / ambient resolver)', () => {
+    it('resolves url, headers and cacheTags from the config', async () => {
+      var _init$next2;
+      const fetchMock = mockFetch(() => ({
+        status: 200,
+        json: async () => ({
+          data: {}
+        })
+      }));
+      withConfig({
+        url: 'https://tenant.fontdue.com',
+        headers: {
+          'x-forwarded-host': 'tenant.fontdue.com'
+        },
+        cacheTags: ['graphql:tenant.fontdue.com']
+      });
+
+      // No options: a module-level fetcher picks up the current render's config.
+      const fetchGraphql = createFontdueFetch();
+      await fetchGraphql('Q', 'query Q { __typename }');
+      const [url, init] = fetchMock.mock.calls[0];
+      expect(url).toBe('https://tenant.fontdue.com/graphql?query=Q');
+      expect(init.headers['x-forwarded-host']).toBe('tenant.fontdue.com');
+      expect(init.cache).toBe('force-cache');
+      expect((_init$next2 = init.next) === null || _init$next2 === void 0 ? void 0 : _init$next2.tags).toEqual(['graphql', 'graphql:tenant.fontdue.com']);
+    });
+    it('explicit options override the config (url and cacheTags)', async () => {
+      const fetchMock = mockFetch(() => ({
+        status: 200,
+        json: async () => ({
+          data: {}
+        })
+      }));
+      withConfig({
+        url: 'https://tenant.fontdue.com',
+        cacheTags: ['graphql:tenant.fontdue.com']
+      });
+
+      // Explicit url + empty cacheTags (e.g. a preview render) win.
+      const fetchGraphql = createFontdueFetch({
+        url: 'https://explicit.fontdue.com',
+        cacheTags: []
+      });
+      await fetchGraphql('Q', 'query Q { __typename }');
+      const [url, init] = fetchMock.mock.calls[0];
+      expect(url).toBe('https://explicit.fontdue.com/graphql?query=Q');
+      expect(init.cache).toBeUndefined();
+      expect(init.next).toBeUndefined();
+    });
   });
 });

package/dist/__tests__/nextAdapter.test.js

@@ -26,11 +26,30 @@ vi.mock('next/navigation', () => ({
     throw new Error('NEXT_NOT_FOUND');
   }
 }));
+
+// Draft mode + the preview token cookie, controllable per test. Default: not
+// previewing, so prepareFontdueRender takes the public (cached) path.
+const draft = vi.hoisted(() => ({
+  enabled: false,
+  token: undefined
+}));
+vi.mock('next/headers', () => ({
+  draftMode: async () => ({
+    isEnabled: draft.enabled
+  }),
+  cookies: async () => ({
+    get: name => name === 'fontdue_preview_token' && draft.token ? {
+      value: draft.token
+    } : undefined
+  })
+}));
 beforeEach(() => {
   vi.resetModules();
   revalidateTag.mockClear();
   vi.unstubAllEnvs();
   vi.restoreAllMocks();
+  draft.enabled = false;
+  draft.token = undefined;
 });
 function stubSingleTenant() {
   let url = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'https://acme.fontdue.com';
@@ -196,6 +215,51 @@ describe('prepareFontdueRender', () => {
       slug: 'sans'
     }))).rejects.toThrow('NEXT_NOT_FOUND');
   });
+
+  // React.cache doesn't memoize outside an RSC render (see configureFontdueRender
+  // above), so the slot write is a no-op here — capture what prepareFontdueRender
+  // passes to setFontdueServerConfig instead.
+  async function captureRenderConfig(params) {
+    let captured;
+    vi.doMock('../relay/serverConfig', async importActual => ({
+      ...(await importActual()),
+      setFontdueServerConfig: c => {
+        captured = c;
+      }
+    }));
+    const {
+      prepareFontdueRender
+    } = await importTenant();
+    await prepareFontdueRender(props(params));
+    vi.doUnmock('../relay/serverConfig');
+    return captured;
+  }
+  it('public render: sets the tenant config with cache tags and no token', async () => {
+    var _config$headers;
+    stubMultiTenant({
+      origin: 'http://app:4000'
+    });
+    const config = await captureRenderConfig({
+      domain: 'acme.fontdue.com'
+    });
+    expect(config.cacheTags).toEqual(['graphql:acme.fontdue.com']);
+    expect((_config$headers = config.headers) === null || _config$headers === void 0 ? void 0 : _config$headers.authorization).toBeUndefined();
+  });
+  it('preview render: folds the token into headers and drops cache tags', async () => {
+    var _config$headers2;
+    stubMultiTenant({
+      origin: 'http://app:4000'
+    });
+    draft.enabled = true;
+    draft.token = 'admin-tok';
+    const config = await captureRenderConfig({
+      domain: 'acme.fontdue.com'
+    });
+    // Embeds (createNetworkFetch) and the app's fetch (createFontdueFetch) both
+    // read this, so both reveal hidden fonts; no tags keeps the render live.
+    expect((_config$headers2 = config.headers) === null || _config$headers2 === void 0 ? void 0 : _config$headers2.authorization).toBe('Bearer admin-tok');
+    expect(config.cacheTags).toBeUndefined();
+  });
 });
 describe('currentFontdueEndpoint', () => {
   it('multi-tenant: throws when no render config was set', async () => {

package/dist/next/tenant.js

@@ -25,7 +25,9 @@
 // NEXT_PUBLIC_FONTDUE_URL at all.
 
 import { notFound } from 'next/navigation';
+import { cookies, draftMode } from 'next/headers';
 import { setFontdueServerConfig, getFontdueServerConfig } from '../relay/serverConfig.js';
+import { PREVIEW_TOKEN_COOKIE, previewAuthHeaders } from '../preview/index.js';
 export const isMultiTenant = process.env.FONTDUE_MULTI_TENANT === '1';
 const singleTenantUrl = process.env.NEXT_PUBLIC_FONTDUE_URL;
 const internalOrigin = process.env.FONTDUE_ORIGIN;
@@ -127,6 +129,12 @@ export function configureFontdueRender(domain) {
 // on every pass. Forgetting it is loud, not subtle: currentFontdueEndpoint
 // throws in multi-tenant mode when no render config was set.
 //
+// When the admin has entered preview (Next draft mode is on), it also folds
+// the preview token into the render config and drops the cache tags, so the
+// whole render — the app's own fetches AND the embedded fontdue-js components'
+// server preloads — reveals hidden fonts and stays live (uncached). This is
+// the Next counterpart to runWithPreview for the SSR frameworks.
+//
 // Route handlers are not React renders — the render-scoped store doesn't
 // exist there, so use the returned endpoint explicitly instead of relying
 // on currentFontdueEndpoint.
@@ -134,9 +142,37 @@ export async function prepareFontdueRender(props) {
   const {
     domain
   } = await props.params;
-  const endpoint = typeof domain === 'string' ? configureFontdueRender(domain) : null;
-  if (!endpoint) notFound();
-  return endpoint;
+  if (typeof domain !== 'string' || !isValidDomain(domain)) notFound();
+  const config = fontdueServerConfig(domain);
+  const previewHeaders = await readPreviewHeaders();
+  setFontdueServerConfig(previewHeaders ? {
+    ...config,
+    headers: {
+      ...config.headers,
+      ...previewHeaders
+    },
+    // Live render: no tags means createNetworkFetch/createFontdueFetch
+    // leave the fetch uncached so preview never lands in a shared cache.
+    cacheTags: undefined
+  } : config);
+  return fontdueEndpoint(domain);
+}
+
+// The admin preview token for this render, as Authorization headers, or
+// undefined when not previewing. Draft mode gates it: reading draftMode().
+// isEnabled is static-safe (it only forces dynamic rendering when actually
+// enabled), and the token cookie is only read in the preview branch. Outside
+// a request scope (build-time static generation) draftMode()/cookies() throw,
+// which we treat as "not preview".
+async function readPreviewHeaders() {
+  try {
+    var _await$cookies$get;
+    if (!(await draftMode()).isEnabled) return undefined;
+    const token = (_await$cookies$get = (await cookies()).get(PREVIEW_TOKEN_COOKIE)) === null || _await$cookies$get === void 0 ? void 0 : _await$cookies$get.value;
+    return token ? previewAuthHeaders(token) : undefined;
+  } catch {
+    return undefined;
+  }
 }
 
 // Endpoint for the app's own GraphQL fetches in this render pass: whatever

package/dist/relay/environment.js

@@ -4,7 +4,7 @@ import { getFontdueServerConfig } from './serverConfig.js';
 
 // `__FONTDUE_JS_VERSION__` is replaced by an inline babel plugin
 // (defineVersionPlugin in .babelrc.cjs) with the literal package.json#version.
-const version = "3.0.0-alpha11";
+const version = "3.0.0-alpha12";
 const IS_SERVER = typeof window === typeof undefined;
 
 // Read env from either process.env (Node/Next.js) or import.meta.env (Vite/Astro).

package/dist/server/index.d.ts

@@ -5,16 +5,28 @@ export declare class FontdueNotFoundError extends Error {
 export interface CreateFontdueFetchOptions {
     /**
      * GraphQL base URL (without the trailing /graphql), e.g.
-     * https://acme.fontdue.com. Defaults to FONTDUE_URL / PUBLIC_FONTDUE_URL /
-     * VITE_FONTDUE_URL from the environment.
+     * https://acme.fontdue.com. Falls back to the per-render config
+     * (getFontdueServerConfig().url, set by the Next adapter for the current
+     * tenant) and then to FONTDUE_URL / PUBLIC_FONTDUE_URL / VITE_FONTDUE_URL
+     * from the environment.
      */
     url?: string;
     /**
-     * Extra headers sent with every fetch from this fetcher. Pass
+     * Extra headers sent with every fetch from this fetcher, merged over the
+     * ambient per-render headers (explicit winning). Pass
      * `previewAuthHeaders(token)` (from fontdue-js/preview) to reveal hidden
      * fonts while an admin is in preview.
      */
     headers?: Record<string, string>;
+    /**
+    * Next.js data-cache tags. When present — passed here or via the per-render
+    * config — the fetch is opted into Next's data cache so the revalidate
+    * handler can purge it. The global `graphql` tag is always included (and
+    * deduped), so pass the per-site tags alone or the full `endpoint.tags`.
+    * Omit (or pass `[]`) to leave the fetch uncached, which is what preview
+    * renders want. Inert outside Next.
+    */
+    cacheTags?: string[];
 }
 export type FontdueFetch = <Q, V = void>(queryName: string, query: string, variables?: V) => Promise<Q>;
 /**

package/dist/server/index.js

@@ -2,32 +2,46 @@
 //
 // Every framework example ships a near-identical `fetchGraphql` — resolve the
 // Fontdue URL, POST the query, unwrap `data`, throw on errors. This exports
-// that transport once so apps don't re-implement it, and so the preview
-// Authorization header is forwarded in one place instead of being wired into
-// each app's data layer.
+// that transport once so apps don't re-implement it, so the preview
+// Authorization header is forwarded in one place, and so the same fetcher
+// works in every server runtime. It is the sibling of the Relay network layer
+// (relay/environment.ts) that powers the embedded components: both read the
+// per-render config from getFontdueServerConfig() and apply it the same way.
 //
-// The per-request input — the admin preview token — can come from two places,
-// resolved per call:
+// All three per-request inputs — the base URL, the admin preview token, and
+// the Next cache tags — are resolved per call from two sources, so a single
+// module-level fetcher serves every render:
 //
-//   1. Ambient context: wrap requests in runWithPreview (fontdue-js/preview/
-//      server) and a single module-level fetcher forwards the token
-//      automatically — no binding, no per-call plumbing:
+//   1. Ambient context (preferred): whatever set the per-render config.
+//      - Astro / React Router etc.: runWithPreview (fontdue-js/preview/server)
+//        rides the token through AsyncLocalStorage.
+//      - Next: prepareFontdueRender (fontdue-js/next) writes the tenant URL,
+//        cache tags, and preview token into the render-scoped slot.
+//      Either way:
 //
 //        const fetchGraphql = createFontdueFetch();           // once, at module scope
 //        const data = await fetchGraphql('Index', indexQuery, vars);
 //
-//   2. Explicit headers: bind a fetcher per request, for frameworks/runtimes
-//      where ambient context can't propagate (see runWithPreview's notes):
+//   2. Explicit options: bind a fetcher with a url/headers/cacheTags, for
+//      runtimes where the ambient context can't propagate (route handlers,
+//      Astro edgeMiddleware — see runWithPreview's notes):
 //
 //        const fetchGraphql = createFontdueFetch({
+//          url: endpoint.origin,
 //          headers: previewAuthHeaders(token),                // from fontdue-js/preview
+//          cacheTags: [`graphql:${endpoint.domain}`],
 //        });
 //
-// Explicit `headers` override the ambient context, so the two compose.
+// Explicit options override the ambient context (headers merge, explicit
+// winning), so the two compose.
 //
-// Caching is intentionally left to the host: these frameworks cache HTML at
-// the CDN/response-header layer, not on the fetch. (The Next adapter layers
-// its own force-cache + tag handling on top of the same idea.)
+// Caching: when the resolved config carries cacheTags (the Next adapter sets
+// them per render; supply them explicitly elsewhere) the fetch is opted into
+// Next's data cache (`force-cache` + tags) so /api/revalidate can purge it.
+// With no tags the fetch is left uncached, which is what preview renders and
+// the CDN-cached frameworks (Astro/RR7 cache HTML at the response layer) want.
+// The Next fetch hints are inert in other runtimes: Node's fetch accepts and
+// ignores the cache mode, and `next` is just an unknown init property.
 
 import { getFontdueServerConfig } from '../relay/serverConfig.js';
 function readEnv(name) {
@@ -65,17 +79,26 @@ export class FontdueNotFoundError extends Error {
  */
 export function createFontdueFetch() {
   let options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
-  const base = options.url ?? resolveFontdueUrl();
-  if (!base) {
-    throw new Error('fontdue-js: no Fontdue URL configured. Set FONTDUE_URL / ' + 'PUBLIC_FONTDUE_URL / VITE_FONTDUE_URL, or pass { url } to ' + 'createFontdueFetch.');
-  }
   return async function fetchGraphql(queryName, query, variables) {
-    var _getFontdueServerConf, _json$errors, _json$errors$;
-    // Ambient preview headers (from a runWithPreview context), overridden by any
-    // explicit per-fetcher headers. Resolved per call so a module-level fetcher
-    // still picks up the current request's preview token.
-    const ambientHeaders = (_getFontdueServerConf = getFontdueServerConfig()) === null || _getFontdueServerConf === void 0 ? void 0 : _getFontdueServerConf.headers;
-    const response = await fetch(`${base}/graphql?query=${queryName}`, {
+    var _json$errors, _json$errors$;
+    // Per-render config (a runWithPreview AsyncLocalStorage store, or the Next
+    // render-scoped slot). Resolved per call so a single module-level fetcher
+    // picks up the current request's tenant URL, preview token, and cache tags.
+    const config = getFontdueServerConfig();
+
+    // URL: explicit option, then the per-render tenant URL, then the env.
+    const base = options.url ?? (config === null || config === void 0 ? void 0 : config.url) ?? resolveFontdueUrl();
+    if (!base) {
+      throw new Error('fontdue-js: no Fontdue URL configured. Set FONTDUE_URL / ' + 'PUBLIC_FONTDUE_URL / VITE_FONTDUE_URL, pass { url } to ' + 'createFontdueFetch, or set it on the per-render config.');
+    }
+
+    // Cache tags: explicit option wins, else the per-render config's. A
+    // non-empty list opts the fetch into Next's data cache (inert elsewhere);
+    // an empty/absent list leaves it uncached (preview + CDN-cached frameworks).
+    const cacheTags = options.cacheTags ?? (config === null || config === void 0 ? void 0 : config.cacheTags);
+
+    // `next` is a Next.js-only fetch extension, ignored by other runtimes.
+    const init = {
       method: 'POST',
       body: JSON.stringify({
         query,
@@ -83,10 +106,21 @@ export function createFontdueFetch() {
       }),
       headers: {
         'content-type': 'application/json',
-        ...ambientHeaders,
+        // Ambient headers (e.g. tenant + preview token), overridden by any
+        // explicit per-fetcher headers.
+        ...(config === null || config === void 0 ? void 0 : config.headers),
         ...options.headers
       }
-    });
+    };
+    if (Array.isArray(cacheTags) && cacheTags.length > 0) {
+      init.cache = 'force-cache';
+      // The global `graphql` tag is always present; dedupe so callers can pass
+      // the per-site tags alone or the full `endpoint.tags` (which include it).
+      init.next = {
+        tags: Array.from(new Set(['graphql', ...cacheTags]))
+      };
+    }
+    const response = await fetch(`${base}/graphql?query=${queryName}`, init);
     if (response.status === 404) throw new FontdueNotFoundError(queryName);
     if (response.status !== 200) {
       throw new Error(`Fontdue request failed: ${response.status}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fontdue-js",
-  "version": "3.0.0-alpha11",
+  "version": "3.0.0-alpha12",
   "type": "module",
   "scripts": {
     "build": "npm run relay && run-p build-js build-css build-ts",

package/types/next-headers.d.ts

@@ -0,0 +1,9 @@
+// Minimal declaration so src/next/tenant.ts type-checks without `next`
+// installed (it's the host app's dependency; this package only ever runs the
+// import inside a Next.js server).
+declare module 'next/headers' {
+  export function draftMode(): Promise<{ isEnabled: boolean }>;
+  export function cookies(): Promise<{
+    get(name: string): { value: string } | undefined;
+  }>;
+}