Set up the project

Install fontdue-js, wire it into your build, point it at your Fontdue site, and get it running locally.

Setting up a Fontdue site is four moves: install fontdue-js, wire it into your framework’s build, tell it which store to read, and import the stylesheet. The reference template has all four done already, so cloning it is the fastest way to a running site – and the rest of this page takes the four apart so you can also add Fontdue to a project of your own.

Requirements

fontdue-js ships as an ESM-only package11No CommonJS build and no main field – resolution runs entirely through the package’s exports map, so both your bundler and TypeScript resolve its subpaths from there. and supports React 18 and 19. Two things are worth checking before you start: that you’re on a current Node.js, and that your tsconfig.json resolves packages by their exports – set moduleResolution to node16, nodenext, or bundler.

One more requirement applies to the config file itself: it must be next.config.mjs, not .js. The withFontdue wrapper you add below is ESM, so the config has to be a module.

Run the example

The template needs Node.js and a Fontdue site to point at. The only required configuration is the URL of your store.

1 Clone and install 
git clone https://github.com/fontdue/example-next.git

cd example-next

npm install

git clone https://github.com/fontdue/example-astro.git

cd example-astro

npm install

git clone https://github.com/fontdue/example-react-router.git

cd example-react-router

npm install

git clone https://github.com/fontdue/example-tanstack.git

cd example-tanstack

npm install
2 Point it at your site

Create an environment file with your Fontdue URL:

# .env.local

NEXT_PUBLIC_FONTDUE_URL=https://your-site.fontdue.com

# .env

PUBLIC_FONTDUE_URL=https://your-site.fontdue.com

# .env

VITE_FONTDUE_URL=https://your-site.fontdue.com

# .env

VITE_FONTDUE_URL=https://your-site.fontdue.com

Every page reads its data from this one endpoint22The GraphQL endpoint is this URL with /graphql appended. The same variable also tells the codegen step where to read the schema – see Set up GraphQL codegen., so it’s the only setting the template needs to render your store.

3 Run it 
npm run dev

The site runs locally and renders your live catalog at the address your dev server prints in the terminal.33Next.js defaults to http://localhost:3000, Astro to http://localhost:4321, and React Router and TanStack Start to whichever port Vite reports. Add that URL to your Fontdue cross-origin allowlist so the components can reach your store from the browser.44In production you add your live domain to the same allowlist – see Deploy.

The dev script runs two things together: your framework’s dev server, and the GraphQL codegen in watch mode, which regenerates TypeScript types whenever you change a query. It’s already wired into every template, so there’s nothing to configure to run the example. Set up GraphQL codegen covers how it works and how to add it to a project of your own.

What you get

Out of the box the template renders the shape of your catalog:

  • a home page listing your root collections;
  • a detail page per collection, with type testers, a character viewer, and a buy button;
  • the cart and checkout, which live inside the Store Modal and open over any page.

The Next.js template renders more than that, because it’s the code behind the demo template Fontdue serves at your-site.fontdue.com: example-next is that same template packaged for a single site. On top of the three above, it also renders:

  • articles and licenses sections, and a catch-all route for your content pages;
  • a sitemap, robots.txt, and per-page metadata built from your site settings.

That’s the whole surface the example here renders – it’s a minimal starting point, not a complete storefront. The rest of a full site – articles and licenses sections, a catch-all for content pages, a sitemap, robots.txt, and per-page metadata from your site settings – you wire up yourself as you need it. For a worked version of all of it, example-next is the code behind Fontdue’s built-in demo template, so it’s the most complete reference even if you’re not building on Next.js.

Each of those is one template that renders many pages from data. The pages that follow take them apart: how the components render, how the data is fetched, and how the font pages map over your collections.

Build your own

To add Fontdue to a project you already have – rather than starting from the template – the same four steps get you to a working site. Start from your framework’s usual project starter, then add Fontdue.

Install

Add the package:

npm install fontdue-js

Wire up your build

This is the one build-config change – a single addition to your framework’s config.

Next.js needs a single change: wrap your config with withFontdue. It registers the image loader and the rewrites Fontdue’s components rely on, and leaves the rest of your config untouched.

Vite powers the build in Next.js, so the wiring is a single plugin: add fontdue-js/vite. It pre-bundles fontdue-js and smooths over its ESM interop so the package imports cleanly.

// next.config.mjs

import { withFontdue } from "fontdue-js/next/config";



export default withFontdue({

  // your existing Next.js config

});

// astro.config.mjs

import { defineConfig } from "astro/config";

import react from "@astrojs/react";

import fontdueJs from "fontdue-js/vite";



export default defineConfig({

  integrations: [react()],

  vite: { plugins: [fontdueJs()] },

});

// vite.config.ts

import { defineConfig } from "vite";

import { reactRouter } from "@react-router/dev/vite";

import fontdueJs from "fontdue-js/vite";



export default defineConfig({

  plugins: [reactRouter(), fontdueJs()],

});

// vite.config.ts

import { defineConfig } from "vite";

import { tanstackStart } from "@tanstack/react-start/plugin/vite";

import viteReact from "@vitejs/plugin-react";

import fontdueJs from "fontdue-js/vite";



export default defineConfig({

  plugins: [tanstackStart(), viteReact(), fontdueJs()],

});

Point it at your site

Set the environment variable that names your store:

# .env.local

NEXT_PUBLIC_FONTDUE_URL=https://your-site.fontdue.com

# .env

PUBLIC_FONTDUE_URL=https://your-site.fontdue.com

# .env

VITE_FONTDUE_URL=https://your-site.fontdue.com

# .env

VITE_FONTDUE_URL=https://your-site.fontdue.com

Import the stylesheet

Import the component styles once, where your app sets up its global CSS:

import "fontdue-js/fontdue.css";

With the package installed, your build wired, the store URL set, and the stylesheet imported, the last piece is the provider that ties them together.

1 No CommonJS build and no main field – resolution runs entirely through the package’s exports map, so both your bundler and TypeScript resolve its subpaths from there. ↩
2 The GraphQL endpoint is this URL with /graphql appended. The same variable also tells the codegen step where to read the schema – see Set up GraphQL codegen. ↩
3 Next.js defaults to http://localhost:3000, Astro to http://localhost:4321, and React Router and TanStack Start to whichever port Vite reports. ↩
4 In production you add your live domain to the same allowlist – see Deploy. ↩