docs menu

Site template

create_site starts a hosted site from a template, a Next.js 16 site on the Next.js kit. There are two:

  • starter, for a new project. It works as it is, with its own content model and sample content, and agents or developers shape it from there. The code is in templates/site in the Galerne repository.
  • bare, for a project that already has its content model. It has the same wiring, previews, design browser and tokens, and none of the starter's types or blocks. See Bare template.

A site repo gets a copy, with the Galerne packages under galerne/. Most of this page is about the starter.

What it has#

  • Pages made of blocks. The page with the slug home is the home page of each language.
  • A blog with tags and pagination, people pages, an RSS feed per language, sitemap.xml, robots.txt and llms.txt.
  • English and French under /en/… and /fr/…, one doc per language for pages and posts, hreflang and a language switcher. Missing translations fall back to English.
  • Settings (site name, logo, navigation, footer, social links) and UI strings that editors translate in the studio.
  • Draft previews on any branch, and click to edit in the studio's preview pane.
  • A design browser at /_design.

Blocks#

Each block has its own folder with a schema, a component, its styles and its examples.

BlockFor
heroThe opening of a page: heading, text, two actions, an image side by side, centered or behind the text
textRich text in the reading column, with calls to action, images and quotes embedded in it
mediaOne image or a video file, with a caption, at reading, wide or full width
galleryA grid of images with captions
carouselSlides that scroll sideways, with buttons and a counter
quoteWords from someone, with name, role and portrait
ctaOne clear next step, on the accent color or a quiet background
cardsCards linking to pages, posts, people or URLs
faqQuestions that open in place
statsKey figures
tableRows of facts, scrolling sideways on phones
videoYouTube or Vimeo, loaded only after a click, or a video file
logosPartners or clients in one row
postListThe latest posts, all or with one tag
contactEmail, phone, address, hours and a map link
weatherA forecast from Open-Meteo: the example of an outside API

Posts embed media, quote, cta, video and table in their body.

To add a block: write blocks/<name>/schema.ts, add it to galerne.config.ts and to the page's blocks, write the component (with edit('field') on each field for click to edit), its CSS module and its examples file, and add it to blocks/index.ts. The site's AGENTS.md lists the steps and the rules.

Design tokens#

The whole look comes from theme/tokens.json, checked by theme/tokens.schema.json:

json
{
  "color": { "accent": { "light": "#b0391a", "dark": "#f08a63" }, "…": {} },
  "font": { "body": "system-ui, sans-serif", "heading": "'Iowan Old Style', Georgia, serif", "mono": "ui-monospace, monospace" },
  "text": { "base": "1.0625rem", "4xl": "clamp(2.5rem, 1.6rem + 3.8vw, 4.5rem)" },
  "space": { "4": "1rem", "section": "clamp(3.5rem, 2rem + 6vw, 7rem)" },
  "radius": { "md": "8px" },
  "shadow": { "md": { "light": "…", "dark": "…" } },
  "duration": { "base": "200ms" },
  "ease": { "standard": "cubic-bezier(0.2, 0, 0, 1)" },
  "layout": { "content": "42rem", "wide": "76rem", "gutter": "clamp(1.125rem, 0.6rem + 2.6vw, 2.75rem)" }
}

Each token becomes a CSS variable named after its path: color.accent is --color-accent, space.4 is --space-4. Colors and shadows have a light and a dark value; the site follows the reader's color scheme. Components use the variables only, so changing a token restyles every block.

Change tokens in the studio's design tab, with update_theme, or in the file. The default palette keeps body text at 4.5:1 or more in both schemes.

Web fonts#

The template uses system fonts. A site serves its own web fonts from public/fonts and declares them in the fonts group of the tokens:

json
{
  "fonts": {
    "serif": {
      "family": "Source Serif 4",
      "fallback": "Georgia, 'Times New Roman', serif",
      "display": "swap",
      "files": [
        { "path": "/fonts/source-serif-4.woff2", "weight": "200 900" },
        { "path": "/fonts/source-serif-4-italic.woff2", "weight": "200 900", "style": "italic" }
      ]
    }
  },
  "font": { "heading": "var(--fonts-serif)" }
}

Each family becomes @font-face rules and the variable --fonts-serif (the family, then its fallback). Font tokens use it as var(--fonts-serif). When font.body names a family, the page preloads its upright woff2 file. A path is a .woff2 or .woff file under /fonts, which is public/fonts in the repo; remote URLs are refused, so the site loads no font from another server. weight is a number or a range like "200 900" for a variable font, style is normal, italic or oblique, and display is swap unless set.

Agents add the files with write_files (with encoding: "base64") and the family with update_theme, on the same branch. Fonts under the SIL Open Font License, like most of Google Fonts, can be served by the site. A commercial font needs a licence of the site owner that covers web use; ask before adding one. Keep the licence file next to the fonts (public/fonts/OFL.txt).

Outside APIs#

lib/external.ts is the pattern for calling an API from the server, next to CMS content:

ts
const result = await fetchExternal('https://api.open-meteo.com/v1/forecast?…', {
  tag: 'open-meteo',                                   // cache tag: external:open-meteo
  life: { stale: 300, revalidate: 1800, expire: 86400 }, // seconds
  timeoutMs: 3000,
  parse: parseForecast,                                // checks the JSON, throws to reject it
})
if (!result.ok) return <p>{text.weatherUnavailable}</p>

The answer is cached with "use cache", its own lifetime and its own tag. A failed or slow call is never cached and the page still renders. revalidateExternal('open-meteo') refreshes it from a route handler. Content from Galerne never goes through it: the kit's queries are tagged and purged on publish.

Bare template#

create_site with template: "bare" fits a project imported from Sanity, Contentful or another CMS, or modelled before the site. It is the default when the deployed schema has types the starter does not define. The site starts with:

  • galerne.config.ts, written from the project's deployed schema, so its types and blocks are typed in the code.
  • lib/routes.ts, the project's routes (the site.routes setting), or one route per type with a slug field when none are set: page at /{lang}/{slug}, other types under their name, like /{lang}/case-study/{slug}.
  • One page, app/[lang]/[...slug], that finds the doc of any routed path and shows its title and fields. The home page shows the doc routed at /{lang}, or a list of the site's pages.
  • A fallback block: a block type without a component shows its type and fields readably, so every page works before the blocks exist.
  • The preview, exit and revalidate routes, proxy.ts, sitemap.xml, robots.txt, llms.txt, the design browser with the tokens page, and theme/tokens.json. list_components and update_theme work as with the starter.

The site's AGENTS.md explains how to build the blocks for the project's model: read it with get_schema (with config: true for the config as JSON), look at real blocks with query, then write each block's component, styles and examples and add it to blocks/index.ts. Each block appears in the design browser as soon as it has an examples file. The code is in templates/bare; it shares the rest with templates/site.

Run it#

bash
cp .env.example .env     # GALERNE_PROJECT, GALERNE_PREVIEW_TOKEN, GALERNE_PREVIEW_SECRET…
pnpm install
GALERNE_TOKEN=gal_admin npx galerne schema deploy
GALERNE_ADMIN_TOKEN=gal_admin pnpm seed     # pages with every block, posts, people, both languages
pnpm dev                                    # http://localhost:3100, the design browser at /_design

Set the preview URL and routes in the studio (Settings, General) or with update_site_settings: page → /{lang}/{slug}, post → /{lang}/blog/{slug}, person → /{lang}/people/{slug}. create_site sets these routes for the types the project has, unless routes are already set.

Unknown pages show the not found page with noindex. Next.js streams pages, so the status code of a page that is not found is 200.