npm - fontdue-js - Versions diffs - 2.28.0 → 3.0.0-alpha10 - Mend

fontdue-js 2.28.0 → 3.0.0-alpha10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (499) hide show

package/README.md CHANGED Viewed

@@ -1,62 +1,83 @@
 # fontdue-js
-This package exports [Fontdue.js](https://docs.fontdue.com/fontduejs) components for React projects.
+React components for [Fontdue](https://fontdue.com) sites. Framework-agnostic: works in Next.js, Astro, React Router 7, TanStack Start, Vike, Remix, and any other React SSR or client-only environment.
 ## Requirements
-- `react` >= 18
-- `node` >= 16
-If using TypeScript, update to >= 4.7 and change your `tsconfig.json` moduleResolution setting to `node16`:
-``` json
+- `react` 18 or 19
+- `node` >= 18
+- TypeScript (if used) with `moduleResolution` set to `node16`, `nodenext`, or `bundler` so the package's `exports` map resolves:
+```json
 {
   "compilerOptions": {
-    "moduleResolution": "node16",
+    "moduleResolution": "nodenext"
   }
 }
 ```
+`fontdue-js` is published ESM-only.
 ## Installation
-``` shell
+```shell
 npm install fontdue-js@latest
 ```
-## Usage
+## Configuration
+Point fontdue-js at your Fontdue URL via an environment variable. Pick the one your framework already uses for public env vars:
+| Framework | Variable |
+| --- | --- |
+| Astro | `PUBLIC_FONTDUE_URL` |
+| React Router 7 / TanStack Start / Vike / Remix (Vite) | `VITE_FONTDUE_URL` |
+| Next.js | `NEXT_PUBLIC_FONTDUE_URL` |
+| Other / framework-less SSR | `FONTDUE_URL` |
+A single variable covers both server and client in every supported framework — Vite exposes `import.meta.env.PUBLIC_*` / `VITE_*` on both sides, and Next inlines `NEXT_PUBLIC_*` on both sides.
-1. Wrap the root of your project with the [`FontdueProvider`](#fontdueprovider) component. For example in a Next.js app, add it to your `app/layout.tsx` or `pages/_app.tsx`.
-2. If using Next.js, add an environment variable to your app `NEXT_PUBLIC_FONTDUE_URL` pointing to your Fontdue store URL. Otherwise, you can include the `url` prop on the `FontdueProvider`.
-3. Render the [`StoreModal`](#storemodal) component so that is it available on every page.
-4. Import the `fontdue-js/fontdue.css` CSS file. (This example uses Next.js)
+## Setup
-### Example
+Pick the section that matches your framework. All four examples below have a working repo linked at the bottom.
+The general pattern in every framework:
-``` shell
-# .env.local
-NEXT_PUBLIC_FONTDUE_URL=https://example.fontdue.com
+1. Mount `<FontdueProvider>` once at the layout level — it sets up the Relay environment + Redux store and renders auxiliary UI (theme config, test-mode banner, consent banner, analytics tracking).
+2. Mount `<StoreModal />` once, alongside the provider — opens when a `<BuyButton>` or `<CartButton>` is clicked.
+3. (SSR only.) Preload in the layout with `loadFontdueProviderQuery()` and pass it as `<FontdueProvider preloadedQuery={…}>`. This ensures the page hydrates with preloaded data.
+4. (SSR only.) Preload per-page components with their `load{Component}Query()` helpers in route loaders / frontmatter / server components.
+The shape of step 3 and 4 is the only thing that changes between frameworks.
+<details>
+<summary><b>Next.js (App Router)</b></summary>
+No Vite plugin needed — wrap your Next config with [`withFontdue`](#nextjs-adapter) instead:
+```js
+// next.config.mjs
+import { withFontdue } from "fontdue-js/next/config";
+export default withFontdue({
+  // your Next config
+});
 ```
+The simplest setup omits the layout preload — with React Server Components, each fontdue-js component preloads its own query internally on the server and streams to the client.
 ```tsx
 // app/layout.tsx
 import FontdueProvider from "fontdue-js/FontdueProvider";
 import StoreModal from "fontdue-js/StoreModal";
 import "fontdue-js/fontdue.css";
-export default async function RootLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
+export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
     <html lang="en">
       <body>
         <FontdueProvider>
           {children}
           <StoreModal />
         </FontdueProvider>
       </body>
@@ -65,183 +86,708 @@ export default async function RootLayout({
 }
 ```
-For details on integrating into your Next.js app, read our [Next.js guide](https://docs.fontdue.com/nextjs)
+```tsx
+// app/fonts/[slug]/page.tsx — no explicit preload needed.
+import TypeTester from "fontdue-js/TypeTester";
-## IDs
+export default function FontPage() {
+  return <TypeTester familyName="Example" styleName="Regular" />;
+}
+```
+Beyond the components, Next.js projects get a few extra entry points — config wrapping, cache revalidation, and helpers for your own GraphQL fetches. See [Next.js adapter](#nextjs-adapter).
+Example repo: [`fontdue/fontdue-example-next`](https://github.com/fontdue/fontdue-example-next)
+</details>
+<details>
+<summary><b>Astro</b></summary>
+Add the Vite plugin to `astro.config.mjs`:
+```ts
+import { defineConfig } from "astro/config";
+import react from "@astrojs/react";
+import fontdueJs from "fontdue-js/vite";
+export default defineConfig({
+  integrations: [react()],
+  vite: { plugins: [fontdueJs()] },
+});
+```
+In Astro, every `client:*` component is its own React island — `<FontdueProvider>` doesn't form a React parent of your page components. Instead, it's a sibling island that sets up Fontdue's core on your site. Per-page components (`<TypeTester>`, etc.) self-wrap their own context when no parent provider is in scope.
+Because of this, there's **no global config** in Astro: `config` set on `<FontdueProvider>` doesn't reach your page components. Pass `config` to each component instead — see [UI config](#ui-config).
+```astro
+---
+// src/layouts/Layout.astro
+import FontdueProvider, { loadFontdueProviderQuery } from "fontdue-js/FontdueProvider";
+import StoreModal from "fontdue-js/StoreModal";
+import "fontdue-js/fontdue.css";
+const fontduePreload = await loadFontdueProviderQuery();
+---
+<html lang="en">
+  <body>
+    <FontdueProvider client:load preloadedQuery={fontduePreload} />
+    <StoreModal client:load />
+    <slot />
+  </body>
+</html>
+```
+Per-page preload runs in frontmatter:
+```astro
+---
+// src/pages/fonts/[slug].astro
+import Layout from "../../layouts/Layout.astro";
+import TypeTester, { loadTypeTesterQuery } from "fontdue-js/TypeTester";
+const preloaded = await loadTypeTesterQuery({
+  familyName: "Example",
+  styleName: "Regular",
+});
+---
+<Layout>
+  <TypeTester client:load preloadedQuery={preloaded} content="The quick brown fox" fontSize={64} />
+</Layout>
+```
+Example repo: [`fontdue/example-astro`](https://github.com/fontdue/example-astro)
+</details>
+<details>
+<summary><b>React Router 7</b></summary>
+Add the Vite plugin to `vite.config.ts`:
+```ts
+import { defineConfig } from "vite";
+import { reactRouter } from "@react-router/dev/vite";
+import fontdueJs from "fontdue-js/vite";
+export default defineConfig({
+  plugins: [reactRouter(), fontdueJs()],
+});
+```
+Preload in the root route's loader, pass the result through `loaderData`:
+```tsx
+// app/root.tsx
+import { Outlet } from "react-router";
+import FontdueProvider, { loadFontdueProviderQuery } from "fontdue-js/FontdueProvider";
+import StoreModal from "fontdue-js/StoreModal";
+import "fontdue-js/fontdue.css";
+import type { Route } from "./+types/root";
+export async function loader() {
+  return { fontduePreload: await loadFontdueProviderQuery() };
+}
+export default function App({ loaderData }: Route.ComponentProps) {
+  return (
+    <FontdueProvider preloadedQuery={loaderData.fontduePreload}>
+      <Outlet />
+      <StoreModal />
+    </FontdueProvider>
+  );
+}
+```
+Per-page preload mirrors the same shape:
+```tsx
+// app/routes/fonts.$slug.tsx
+import TypeTester, { loadTypeTesterQuery } from "fontdue-js/TypeTester";
+export async function loader() {
+  return {
+    preloadedQuery: await loadTypeTesterQuery({
+      familyName: "Example",
+      styleName: "Regular",
+    }),
+  };
+}
+export default function FontPage({ loaderData }) {
+  return <TypeTester preloadedQuery={loaderData.preloadedQuery} content="…" fontSize={64} />;
+}
+```
+Example repo: [`fontdue/example-react-router`](https://github.com/fontdue/example-react-router)
+</details>
+<details>
+<summary><b>TanStack Start</b></summary>
+Add the Vite plugin to `vite.config.ts` (alongside TanStack's plugin). Preload in the root route's `loader`:
+```tsx
+// src/routes/__root.tsx
+import { Outlet, createRootRoute } from "@tanstack/react-router";
+import FontdueProvider, { loadFontdueProviderQuery } from "fontdue-js/FontdueProvider";
+import StoreModal from "fontdue-js/StoreModal";
+import "fontdue-js/fontdue.css";
+export const Route = createRootRoute({
+  loader: async () => ({ fontduePreload: await loadFontdueProviderQuery() }),
+  component: RootComponent,
+});
+function RootComponent() {
+  const { fontduePreload } = Route.useLoaderData();
+  return (
+    <FontdueProvider preloadedQuery={fontduePreload}>
+      <Outlet />
+      <StoreModal />
+    </FontdueProvider>
+  );
+}
+```
+Per-page preload uses each route's `loader`:
+```tsx
+// src/routes/fonts.$slug.tsx
+import { createFileRoute } from "@tanstack/react-router";
+import TypeTester, { loadTypeTesterQuery } from "fontdue-js/TypeTester";
+export const Route = createFileRoute("/fonts/$slug")({
+  loader: async () => ({
+    preloadedQuery: await loadTypeTesterQuery({
+      familyName: "Example",
+      styleName: "Regular",
+    }),
+  }),
+  component: FontPage,
+});
+function FontPage() {
+  const { preloadedQuery } = Route.useLoaderData();
+  return <TypeTester preloadedQuery={preloadedQuery} content="…" fontSize={64} />;
+}
+```
+Example repo: [`fontdue/example-tanstack`](https://github.com/fontdue/example-tanstack)
+</details>
+<details>
+<summary><b>Other Vite-based frameworks (Vike, Remix, plain Vite SSR)</b></summary>
+Add `fontdueJs()` to your Vite plugins. Run `loadFontdueProviderQuery()` wherever your framework loads layout-level data (Vike's `+data.ts`, Remix's root `loader`, etc.) and pass the result to `<FontdueProvider preloadedQuery>`. The component-level `load*Query()` helpers work the same way for per-page data.
+Vike example — `+data.ts` for the layout, plus a per-page data loader. Re-export `Data = Awaited<ReturnType<typeof data>>` from each `+data.ts` so `useData<Data>()` gets a proper type without restating the shape:
+```ts
+// pages/+data.ts
+import { loadFontdueProviderQuery } from "fontdue-js/FontdueProvider";
+export const data = async () => ({
+  fontduePreload: await loadFontdueProviderQuery(),
+});
+export type Data = Awaited<ReturnType<typeof data>>;
+```
+```tsx
+// pages/+Layout.tsx
+import { useData } from "vike-react/useData";
+import FontdueProvider from "fontdue-js/FontdueProvider";
+import StoreModal from "fontdue-js/StoreModal";
+import "fontdue-js/fontdue.css";
+import type { Data } from "./+data";
+export default function Layout({ children }: { children: React.ReactNode }) {
+  const { fontduePreload } = useData<Data>();
+  return (
+    <FontdueProvider preloadedQuery={fontduePreload}>
+      {children}
+      <StoreModal />
+    </FontdueProvider>
+  );
+}
+```
+```ts
+// pages/fonts/@slug/+data.ts
+import { loadTypeTesterQuery } from "fontdue-js/TypeTester";
+export const data = async () => ({
+  preloadedQuery: await loadTypeTesterQuery({
+    familyName: "Example",
+    styleName: "Regular",
+  }),
+});
+export type Data = Awaited<ReturnType<typeof data>>;
+```
+```tsx
+// pages/fonts/@slug/+Page.tsx
+import { useData } from "vike-react/useData";
+import TypeTester from "fontdue-js/TypeTester";
+import type { Data } from "./+data";
+export default function FontPage() {
+  const { preloadedQuery } = useData<Data>();
+  return <TypeTester preloadedQuery={preloadedQuery} content="…" fontSize={64} />;
+}
+```
+Remix follows the same shape with root `loader` / route `loader` + `useLoaderData()`. We don't ship an example repo for these yet — open an issue if you'd like one.
+</details>
+<details>
+<summary><b>Client-only / no SSR</b></summary>
+Mount `<FontdueProvider>` (no `preloadedQuery`) and render components with their lazy props (`{collectionId}`, `{familyName, styleName}`, etc.). They fetch on mount.
+```tsx
+import FontdueProvider from "fontdue-js/FontdueProvider";
+import StoreModal from "fontdue-js/StoreModal";
+import TypeTester from "fontdue-js/TypeTester";
+import "fontdue-js/fontdue.css";
+export default function App() {
+  return (
+    <FontdueProvider>
+      <TypeTester familyName="Example" styleName="Regular" />
+      <StoreModal />
+    </FontdueProvider>
+  );
+}
+```
+</details>
+## Next.js adapter
+Next.js App Router projects get a few extra entry points beyond the components. The [example repo](https://github.com/fontdue/fontdue-example-next) wires up all of them.
+### `withFontdue` — next.config wrapper
+```js
+// next.config.mjs
+import { withFontdue } from "fontdue-js/next/config";
+export default withFontdue({
+  // your Next config
+});
+```
+What it installs:
+- **Image settings** — `images.remotePatterns` entries for Fontdue's image hosts (plus `dangerouslyAllowSVG`, since font specimens are often SVGs), merged with your own `images` config.
+- **Correct 404 statuses** — Next's streamed metadata locks in a `200` response before a `notFound()` thrown during `generateMetadata` can take effect ([vercel/next.js#82041](https://github.com/vercel/next.js/issues/82041)). `withFontdue` sets `htmlLimitedBots` to match every user agent so metadata rendering blocks the response and missing pages come out as real 404s.
+The rest of your config — `rewrites` included — passes through unchanged.
+#### Optional: image optimization on Cloudflare
+If you have a Cloudflare zone with [image transformations](https://developers.cloudflare.com/images/transform-images/) enabled, set:
+```shell
+NEXT_PUBLIC_FONTDUE_IMAGE_HOST=img.your-domain.com
+NEXT_PUBLIC_FONTDUE_IMAGE_ORIGINS=cdn.fontdue.com
+```
+`next/image` optimization then moves to the Cloudflare edge, and your deployment needs neither the `/_next/image` endpoint nor sharp. `NEXT_PUBLIC_FONTDUE_IMAGE_ORIGINS` (comma-separated hostnames) should mirror the transformation host's allowed source origins — sources on other hosts are served as originals rather than as transform URLs Cloudflare would refuse. Both variables must be present when `next build` runs (the loader is inlined into the client bundle), not just at serve time.
+### Updating content: `/api/revalidate`
+fontdue-js's server-side fetches are cached by Next and tagged `graphql`. Re-export the deploy-hook route handler:
+```ts
+// app/api/revalidate/route.ts
+export { POST } from "fontdue-js/next/revalidate";
+```
+and set the Deploy hook URL in your Fontdue admin (Settings → Website settings) to `https://your-site.example/api/revalidate`. Fontdue calls it whenever your site's content changes, purging everything tagged `graphql` so the next request renders fresh.
+fontdue-js's own server-side fetches opt into Next's data cache (and the `graphql` tag) automatically — static pages revalidated by the deploy hook is the intended way to run a Fontdue site, not dynamic rendering. Give your own fetches the same treatment; `currentFontdueEndpoint()` below shows how.
-⚠️ Some components accept a `collectionId` prop. Note this is the `id` returned from the [GraphQL API](https://docs.fontdue.com/graphql-api).
+### Your own GraphQL fetches
-You may alternatively specify a `collectionSlug` for these components, which can be useful if you are not consuming the GraphQL API. However, we recommend using `collectionId` when possible.
+`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`:
+```ts
+import { currentFontdueEndpoint } from "fontdue-js/next";
+export async function fetchGraphql(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 },
+  });
+  return (await response.json()).data;
+}
+```
+The shape is exported as `type FontdueEndpoint`.
+## Migrating a Next.js site from v2
+For a site built on the [example repo](https://github.com/fontdue/example-next) (App Router), v3 is a small, mechanical upgrade — component imports, props, and `NEXT_PUBLIC_FONTDUE_URL` all stay the same. Work through this checklist:
+1. **Install the v3 line:**
+   ```shell
+   npm install fontdue-js@alpha
+   ```
+   v3 is ESM-only and needs `react` 18/19 and `node` >= 18. If TypeScript can't resolve the imports, set `moduleResolution` to `"bundler"` (or `node16`/`nodenext`) in `tsconfig.json` — see [Requirements](#requirements).
+2. **Wrap your Next config with `withFontdue`.** It installs the Fontdue image settings (`remotePatterns`, `dangerouslyAllowSVG`) and the `htmlLimitedBots` workaround for correct 404 statuses, so you can delete those from your own config — for many sites the whole file shrinks to:
+   ```js
+   // next.config.mjs (replaces next.config.js — the package is ESM)
+   import { withFontdue } from "fontdue-js/next/config";
+   export default withFontdue({});
+   ```
+3. **Replace your `/api/revalidate` handler with the re-export.** v3 caches and tags its own server-side fetches, and the shared handler purges everything carrying the `graphql` tag:
+   ```ts
+   // app/api/revalidate/route.ts
+   export { POST } from "fontdue-js/next/revalidate";
+   ```
+   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).
+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.
+6. **Rename `useFontStyle` to `useFont`** if you use it (the old name still works as an alias).
+What you get for it: server components now render the embeds' full HTML on the server (v2 hydrated some of them empty and fetched client-side), every fontdue-js fetch is cached and purged per-site by the deploy hook, and the optional [Cloudflare image loader](#optional-image-optimization-on-cloudflare) can replace the in-process optimizer entirely.
+If you're starting fresh instead of migrating, fork the example repo — it ships in this shape already.
+## 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).
+There are two places to set it.
+**On the provider.** `<FontdueProvider config={…}>` configures every Fontdue component rendered _inside_ it. This is the normal way wherever your components are React descendants of the provider — Next.js, React Router 7, TanStack Start, Vike, Remix, and client-only setups.
+```tsx
+<FontdueProvider config={{ typeTester: { selectable: true } }}>
+  <TypeTester familyName="Example" styleName="Regular" />
+</FontdueProvider>
+```
+**Per component.** Every component below also accepts an optional `config` prop with the same shape. It's the way to configure a component used as a standalone island (see Astro, below).
+```tsx
+<TypeTester preloadedQuery={preloaded} config={{ typeTester: { selectable: true } }} />
+```
+The config type is exported from the package root, so you can type a shared object: `import type { Config } from "fontdue-js"`.
+How the two compose:
+- **Standalone** — a component with no `<FontdueProvider>` ancestor uses its own `config` prop in full.
+- **Inside a provider** — the component's `config` deep-merges onto the provider's: the component's keys win, everything else is inherited.
+- **Next.js App Router is the exception.** There, components render through React Server Components and read config from the `<FontdueProvider>` only — a per-component `config` prop is ignored. Set config on the provider.
+### Astro and other per-island frameworks: there is no global config
+In Astro, Vike, and any framework that hydrates each `client:*` component as its own React island, `<FontdueProvider>` is a _sibling_ island, not a React ancestor of your page components. **Config set on the provider does not reach them**, and there is no global config to set.
+Pass `config` to each island instead. Define it once and reuse it so every island agrees:
+```astro
+---
+import type { Config } from "fontdue-js";
+import TypeTester, { loadTypeTesterQuery } from "fontdue-js/TypeTester";
+// One source of truth for this page's testers.
+const fontdueConfig = { typeTester: { selectable: true } } satisfies Config;
+const regular = await loadTypeTesterQuery({ familyName: "Example", styleName: "Regular" });
+const italic = await loadTypeTesterQuery({ familyName: "Example", styleName: "Italic" });
+---
+<TypeTester client:load preloadedQuery={regular} config={fontdueConfig} />
+<TypeTester client:load preloadedQuery={italic} config={fontdueConfig} />
+```
+`config` affects the server-rendered HTML, so keeping a single source of truth is also what keeps SSR and client hydration in agreement. To share config across many pages, export it from a module (e.g. `src/lib/fontdue.ts`) and import it wherever you mount a component.
+## IDs
+> Some components accept a `collectionId`. This is the `id` returned from the [GraphQL API](https://docs.fontdue.com/graphql-api). You can alternatively pass `collectionSlug`, which is useful when you aren't consuming the GraphQL API directly. Prefer `collectionId` when possible.
 ---
 # Components
+Every component below has a default export and (where applicable) a `load{Component}Query` named export for the SSR preload path. Both share a single entry point per component. Every component also accepts an optional `config` prop — see [UI config](#ui-config).
+## Lazy vs. preloaded props
+Most components accept their data in one of two shapes:
+- **Lazy props** — the identifying inputs the component needs to look up its own data: `collectionId` / `collectionSlug` for collection-bound components, `familyName` + `styleName` for the standalone `<TypeTester>`, nothing at all for forms like `<NewsletterSignup>` or `<TestFontsForm>`. The component fetches on mount, on the client, and shows nothing in the meantime.
+- **`preloadedQuery`** — the result of calling the corresponding `load{Component}Query(…)` helper on the server. The component skips its own fetch, renders synchronously from the payload, and hydrates on the client without a re-fetch.
+Both shapes are mutually exclusive on each component. You can mix them across the page — e.g. preload a `<TypeTester>` on a font-detail route while using a lazy `<BuyButton>` on the same page — and you can mix them across pages, since the choice is per-render.
+```tsx
+// Lazy — fetches on the client.
+<TypeTester familyName="Example" styleName="Regular" />
+// Preloaded — server-rendered, hydrates without a fetch.
+const preloadedQuery = await loadTypeTesterQuery({
+  familyName: "Example",
+  styleName: "Regular",
+});
+<TypeTester preloadedQuery={preloadedQuery} />
+```
+**Which to use?**
+- If you're in Next.js's App Router, use the lazy props — React Server Components takes care of the preload internally for you.
+- If you're in any other framework with SSR (Astro, RR7, TanStack, Vike, Remix), prefer `preloadedQuery`. Otherwise the page hydrates with a flash of empty content while each component fetches.
+- If your site is client-only (no SSR), lazy props are the only option.
+A few components don't accept `preloadedQuery`:
+- **`StoreModal`** and **`CartButton`** still render server-side, but without a preloaded query — their fetch always happens on the client after hydration, and the SSR output is the empty Suspense fallback. The reason: their data is per-customer-session (cart contents, modal-open state) and a build-time / CDN-cached SSR call would just cache an empty cart and delay the real one. `<CartButton>` reflects the right count as soon as the post-hydration fetch resolves; `<StoreModal>` renders nothing visible until opened, so there's nothing to flash.
+- **`CustomerLoginForm`** has no preload helper today — it's a thin form with no upfront data needs.
 ## `FontdueProvider`
-The FontdueProvider provides necessary context for all the other Fontdue.js components, so it must be an ancestor of all other components. See example in our [guide](https://docs.fontdue.com/nextjs).
+Provides the Fontdue context (Relay environment, Redux store, config, components map) and renders auxiliary UI (theme, test-mode banner, consent banner, tracking). Render once at the layout level.
 ```tsx
-import FontdueProvider from 'fontdue-js/FontdueProvider';
+import FontdueProvider, { loadFontdueProviderQuery } from "fontdue-js/FontdueProvider";
 ```
 | Prop | Description |
 | --- | --- |
-| `url` | `string` Your Fontdue store URL, in the form `https://your-site.fontdue.com`. |
-| `config` | `object` Config object. Refer to the [Fontdue.js docs site](https://docs.fontdue.com/fontduejs#b3dec49aa08240bba2b4c71a67c08333) for available config options. |
-| `components` | `object` Component view overrides. This API will likely change. |
+| `preloadedQuery` | (Recommended) Result of `loadFontdueProviderQuery()`. Warms aux UI synchronously. |
+| `config` | `object` UI config applied to everything in the provider's tree. See [UI config](#ui-config). |
 ## `StoreModal`
-Renders the Fontdue cart + checkout experience as a modal. This appears when a user clicks on a [`BuyButton`](#buybutton) or the buy button within [`TypeTesters`](#typetesters)
+The cart and checkout UI, rendered as a modal. Mount once at the layout level. Opens when a `BuyButton` is clicked or when navigated to from another component.
 ```tsx
-import StoreModal from 'fontdue-js/StoreModal';
+import StoreModal from "fontdue-js/StoreModal";
 ```
-## `BuyButton`
+`StoreModal` doesn't accept `preloadedQuery` — its content is per-customer-session (cart contents, modal-open state), which isn't safe to resolve at SSR time. The component still renders server-side, but its data fetch always runs on the client after hydration. The modal is closed by default, so there's nothing visible to flash.
-A button which when clicked opens the Cart to the relevant collection, and selects the collection.
+## `BuyButton`
-Renders a button with the text `Buy {collectionName}`
+A button that opens `StoreModal` to the relevant collection.
 ```tsx
-import BuyButton from 'fontdue-js/BuyButton';
+import BuyButton, { loadBuyButtonQuery } from "fontdue-js/BuyButton";
 ```
 | Prop | Description |
 | --- | --- |
-| `collectionId` or `collectionSlug` | (Required) `string` Collection identifier |
-| `collectionName` | (Optional) `string` The name to render in the button: `Buy {collectionName}` |
-| `label` | (Optional) `string` Label for the button (defaults to `Buy {collectionName}`) |
+| `collectionId` or `collectionSlug` | (Required, lazy) `string` Collection identifier. Omit if passing `preloadedQuery`. |
+| `preloadedQuery` | (Required, SSR) Result of `loadBuyButtonQuery({ collectionId })` or `loadBuyButtonQuery({ collectionSlug })`. |
+| `collectionName` | (Optional) `string` Name to render in the default label: `Buy {collectionName}`. |
+| `label` | (Optional) `string` Override the button label entirely. |
 ## `CartButton`
-A button to open the Store Modal. If the user has items in their cart, the button will navigate straight to the Cart screen. Otherwise it opens the fonts index.
+Opens `StoreModal`, jumping straight to the cart screen if there are items in it.
 ```tsx
-import CartButton from 'fontdue-js/CartButton';
+import CartButton from "fontdue-js/CartButton";
 ```
+No `preloadedQuery` (same reason as `StoreModal`). Renders server-side with an empty Suspense fallback, then fetches the cart on the client after hydration and updates with the live count. Render anywhere; safe with or without an explicit `<FontdueProvider>` ancestor.
 | Prop | Description |
 | --- | --- |
-| `buttonStyle` | (Optional) `'icon' \| 'inline'` Button style. If left blank, the button is unstyled. |
-| `label` | (Optional) `string` For non-icon style buttons, the text to render inside the button. Defaults to "Cart" |
+| `buttonStyle` | (Optional) `string` Pass `'icon'` to render the cart icon instead of a text label. The value is also surfaced as `data-button-style` on the rendered `<button>` so you can target other styles via CSS. |
+| `label` | (Optional) `string` Text content. Defaults to `"Cart"`. Ignored when `buttonStyle="icon"`. |
+| `suffix` | (Optional) `string` Template appended to the label. Substitutions: `{count}`, `{subtotal}`. Hidden when the cart is empty. |
+| `children` | (Optional) `ReactNode` Custom button contents. Replaces the default label / icon entirely. |
 ## `CharacterViewer`
-An interactive character/glyph explorer.
+An interactive character / glyph explorer.
 ```tsx
-import CharacterViewer from 'fontdue-js/CharacterViewer';
+import CharacterViewer, { loadCharacterViewerQuery } from "fontdue-js/CharacterViewer";
 ```
 | Prop | Description |
 | --- | --- |
-| `collectionId` or `collectionSlug` | (Required) `string` Identifier for collection |
+| `collectionId` or `collectionSlug` | (Required, lazy) `string` Collection identifier. |
+| `preloadedQuery` | (Required, SSR) Result of `loadCharacterViewerQuery({ collectionId })` or `loadCharacterViewerQuery({ collectionSlug })`. |
 ## `CustomerLoginForm`
-A form for customers to log in and retrieve their order history. When they enter
-their email address, they receive a link to a Fontdue-hosted page to view orders.
+A form for customers to look up their order history. Submitting an email address sends a link to a Fontdue-hosted orders page.
 ```tsx
-import CustomerLoginForm from 'fontdue-js/CustomerLoginForm';
+import CustomerLoginForm from "fontdue-js/CustomerLoginForm";
 ```
 | Prop | Description |
 | --- | --- |
-| `submitLabel` | `string` Label for the submit button, defaults to "Submit" |
+| `submitLabel` | (Optional) `string` Submit button label. Defaults to `"Submit"`. |
 ## `TypeTesters`
-A group of type tester components for a collection. You must first add content for the collection's type testers through the Fontdue dashboard.
+Group of type testers configured through the Fontdue dashboard.
 ```tsx
-import TypeTesters from 'fontdue-js/TypeTesters';
+import TypeTesters, { loadTypeTestersQuery } from "fontdue-js/TypeTesters";
 ```
 | Prop | Description |
 | --- | --- |
-| `collectionId` or `collectionSlug` | (Required) `string` Identifier for collection |
-| `defaultMode` | (Optional) `'local' \| 'global'` The mode refers to the toggle in the UI: Affect all styles. `local` mode has this toggle turned off by default, `global` turns it on |
-| `autofit` | (Optional) `boolean` Set to `true` to make the sentences fit on one line. It will adjust to the width of the tester as the user changes their browser window. If the user changes the font size or edits content, autofitting is turned off for that tester |
-| `tags` | (Optional) `string[]` Will render only type testers that include any of these tags |
-| `excludeTags` | (Optional) `string[]` Will exclude type testers that include any of these tags |
-| `onFocus` | (Optional) `() => void` when any type tester is focused |
-| `onBlur` | (Optional) `() => void` when any type tester is blurred |
-| `onToolbarOpenClose` | (Optional) `(open: boolean) => void` Callback when toolbar is opened/closed |
+| `collectionId` or `collectionSlug` | (Required, lazy) `string` Collection identifier. |
+| `preloadedQuery` | (Required, SSR) Result of `loadTypeTestersQuery({ collectionId, tags?, excludeTags? })` or `loadTypeTestersQuery({ collectionSlug, tags?, excludeTags? })`. |
+| `defaultMode` | (Optional) `'group' \| 'local'` Whether the "Affect all styles" toggle starts on (`group`) or off (`local`). |
+| `autofit` | (Optional) `boolean` Make sentences fit on one line, adjusting size as the container resizes. Disables when the user changes font size or content. |
+| `tags` | (Optional) `string[]` Render only testers tagged with any of these. |
+| `excludeTags` | (Optional) `string[]` Exclude testers tagged with any of these. |
+| `features` | (Optional) `string[]` OpenType feature codes to expose to users across all testers in the group (e.g. `['ss01', 'ss02']`). |
+| `onFocus` | (Optional) `() => void` Fired when any tester gains focus. |
+| `onBlur` | (Optional) `() => void` Fired when any tester loses focus. |
+| `onToolbarOpenClose` | (Optional) `(open: boolean) => void` Fired when the toolbar opens or closes. |
 ## `TypeTester` (standalone)
-Standalone version of the type tester, which does not query the Fontdue CMS for content. You supply the content instead. Does not support the "Affect all styles" feature of the TypeTesters component.
+Standalone tester driven by props rather than dashboard content. Doesn't support the "Affect all styles" toggle.
 ```tsx
-import TypeTester from 'fontdue-js/TypeTester';
+import TypeTester, { loadTypeTesterQuery } from "fontdue-js/TypeTester";
 ```
 | Prop | Description |
 | --- | --- |
-| `familyName` | (Required) `string` Font family name (must have been already uploaded to your Fontdue admin) |
-| `styleName` | (Required) `string` The name of the style from the family to display. |
+| `familyName` and `styleName` | (Required, lazy) `string` Identify the font style to render. The family/style must already be uploaded to your Fontdue admin. |
+| `preloadedQuery` | (Required, SSR) Result of `loadTypeTesterQuery({ familyName, styleName })`. |
 | `fontSize` | (Optional) `number` Initial font size in pixels. |
-| `lineHeight` | (Optional) `number` Line-height as a proportional value where `1 == fontSize`. |
-| `content` | (Optional) `string` The initial content to display. |
-| `direction` | (Optional) `'ltr' \| 'rtl'` Writing direction |
-| `alignment` | (Optional) `'left' \| 'center' \| 'right'` Text alignment |
-| `features` | (Optional) `string[]`  List of opentype feature codes to expose as options to users. (e.g. `['ss01', 'ss02']`) |
-| `axes` | (Optional) `string[]`  List of variable axes to expose. (e.g. `['wdth', 'ital']`). You must provide the relevant `variableSettings` for each axis |
-| `autofit` | (Optional) See `TypeTesters.autofit` above |
-| `featureSettings` | (Optional) `{ feature: string, value: string }[]` List of features already selected, the `value` should be `"1"` to mark the feature as selected. The shape of this data is consistent with the `TypeTester.featureSettings` field in the GraphQL API. e.g. `[{ feature: 'ss01', value: '1' }]` |
-| `variableSettings` | (Optional) `{ axis: string, value: number }[]` List of variable settings selected, consistent with the `TypeTester.variableSettings` field. e.g. `[{ axis: 'wdth', value: 600 }, { axis: 'ital', value: 0.5 }]` |
+| `lineHeight` | (Optional) `number` Proportional line height (`1` == `fontSize`). |
+| `letterSpacing` | (Optional) `number` Letter spacing. |
+| `content` | (Optional) `string` Initial content. |
+| `direction` | (Optional) `'ltr' \| 'rtl'` Writing direction. |
+| `alignment` | (Optional) `'left' \| 'center' \| 'right'` Text alignment. |
+| `features` | (Optional) `string[]` OpenType feature codes to expose to users (e.g. `['ss01', 'ss02']`). |
+| `featuresSelected` | (Optional) `string[]` Subset of `features` to mark as initially selected. |
+| `axes` | (Optional) `string[]` Variable axes to expose (e.g. `['wdth', 'ital']`). Pair with `variableSettings`. |
+| `featureSettings` | (Optional) `{ feature: string, value: string }[]` Pre-selected features. Shape matches `TypeTester.featureSettings` in the GraphQL API. |
+| `variableSettings` | (Optional) `{ axis: string, value: number }[]` Pre-selected axis values. Shape matches `TypeTester.variableSettings` in the GraphQL API. |
+| `autofit` | (Optional) See `TypeTesters.autofit` above. |
+| `onFocus` / `onBlur` | (Optional) `() => void` |
 ## `TestFontsForm`
-Displays a form for users to enter their information and download test fonts. Make sure you have configured [Test Fonts](https://docs.fontdue.com/test-fonts) for this to work.
+A form that lets visitors download test fonts after entering their details. Requires [Test Fonts](https://docs.fontdue.com/test-fonts) to be configured.
 ```tsx
-import TestFontsForm from 'fontdue-js/TestFontsForm';
+import TestFontsForm, { loadTestFontsFormQuery } from "fontdue-js/TestFontsForm";
 ```
 | Prop | Description |
 | --- | --- |
-| `agreementLabel` | (Optional) `string` Label for required checkbox. Defaults to the field "EULA agreement text" in your Fontdue Labels settings |
-| `downloadLabel` | (Optional) `string` Download button label. Defaults to "Download test fonts" |
-| `newsletterCheckboxChecked` | (Optional) `boolean` Set the newsletter opt-in checkbox checked by default |
+| `preloadedQuery` | (Optional, SSR) Result of `loadTestFontsFormQuery()`. Lazy if omitted. |
+| `agreementLabel` | (Optional) `string` Label for the required agreement checkbox. Defaults to the "EULA agreement text" field in your Fontdue Labels settings. |
+| `downloadLabel` | (Optional) `string` Submit button label. Defaults to `"Download test fonts"`. |
+| `newsletterCheckboxChecked` | (Optional) `boolean` Pre-check the newsletter opt-in. |
 ## `NewsletterSignup`
-A newsletter signup form. Customers entering their information here simply adds them as a Customer in the Fontdue CMS.
+A signup form that adds the visitor as a Customer in Fontdue.
 ```tsx
-import NewsletterSignup from 'fontdue-js/NewsletterSignup';
+import NewsletterSignup, { loadNewsletterSignupQuery } from "fontdue-js/NewsletterSignup";
 ```
 | Prop | Description |
 | --- | --- |
-| `optInLabel` | (Required) `string` Label that appears with the checkbox required to be checked. |
-| `buttonLabel` | (Optional) `string` Label for the button. Defaults to "Subscribe" |
-| `optInCheckboxChecked` | (Optional) `boolean` Set the checkbox checked by default. |
+| `preloadedQuery` | (Optional, SSR) Result of `loadNewsletterSignupQuery()`. Lazy if omitted. |
+| `title` | (Optional) `string` Heading rendered above the form. |
+| `intro` | (Optional) `string` Paragraph rendered between the title and the form. |
+| `optInLabel` | (Optional) `string` Label rendered next to the opt-in checkbox. Defaults to the "Newsletter opt-in label" field in your Fontdue Labels settings. |
+| `buttonLabel` | (Optional) `string` Submit button label. Defaults to `"Subscribe"`. |
+| `successLabel` | (Optional) `string` Message shown after a successful submission. Defaults to the "Newsletter success label" field in your Fontdue Labels settings. |
+| `optInCheckboxChecked` | (Optional) `boolean` Pre-check the opt-in box. |
+---
+# Hooks
 ## `useFont`
-A hook to load and render a web font. Pass `webfontSources` to load fonts directly via the FontFace API (no CSS `@font-face` required). The `webfontSources` data is available from the `FontStyle.webfontSources` field in the GraphQL API.
+Loads and renders a webfont. Pass `webfontSources` (available as `FontStyle.webfontSources` in the GraphQL API) to load via the FontFace API directly — no CSS `@font-face` needed.
 ```tsx
-import useFont from 'fontdue-js/useFont';
+import useFont from "fontdue-js/useFont";
 const FontStyle = ({ familyName, styleName, webfontSources }) => {
   const { style, loaded } = useFont({
     fontFamily: `${familyName} ${styleName}`,
     webfontSources,
   });
   return <span style={style}>The quick brown fox</span>;
 };
 ```
-If `webfontSources` is omitted, the hook falls back to detecting fonts loaded by CSS `@font-face` rules.
+If `webfontSources` is omitted, the hook falls back to detecting fonts loaded by your CSS `@font-face` rules.
+Also available as `fontdue-js/useFontStyle` for backwards compatibility.
+## `useConsent`
+Returns `true` when the visitor has granted consent for a given category. Re-renders when the consent state changes (e.g. the visitor accepts the consent banner).
+```tsx
+import { useConsent } from "fontdue-js/useConsent";
+const analyticsConsent = useConsent("analytics");
+```
+## `useAutofit`
+Measures a string against a container and returns a font size that fits on one line. Used internally by `TypeTester`'s `autofit` prop; exported for custom layouts.
+```tsx
+import useAutofit from "fontdue-js/useAutofit";
+const { ref, fontSize, ready } = useAutofit({
+  text: "The quick brown fox",
+  fontFamily: "Tonka Regular",
+  fontSize: 200,
+});
+```
+---
+# Examples
+Working repos for each supported framework, all hitting the same `example.fontdue.xyz` store and exercising every preloadable component:
-Also available as `fontdue-js/useFontStyle` for backward compatibility.
+- Next.js — [`fontdue/fontdue-example-next`](https://github.com/fontdue/fontdue-example-next)
+- Astro — [`fontdue/example-astro`](https://github.com/fontdue/example-astro)
+- React Router 7 — [`fontdue/example-react-router`](https://github.com/fontdue/example-react-router)
+- TanStack Start — [`fontdue/example-tanstack`](https://github.com/fontdue/example-tanstack)