Extend from an outside directory

Add header and footer content, blocks, collections, CMS editors and routes to one or many sites from a directory that lives outside their repositories.

  1. Create the directory and add the files you need from the table below.

  2. Point STOMME_SLOTS_DIR at it when you run the site.

    STOMME_SLOTS_DIR=../extensions pnpm dev
  3. Read the log. The routes line names each slot that was found as slot:<name>, plus every route the directory added, and stomme cms lists the blocks it added as addon blocks.

A file that is not there changes nothing, and without STOMME_SLOTS_DIR the site builds exactly as it would with none of them.

File What it adds
header-start.astro, header-nav-end.astro, header-end.astro markup at that place in the header
footer-end.astro, footer-legal-end.astro markup at that place in the footer
blocks.mjs export const blocks = { type: Component }, components the renderer dispatches by type. The engine's block of the same type gives way to yours, and the site's own registry wins over both
block-catalog.mjs export const BLOCKS = [...], catalog entries for those blocks; a type the site's own catalog already has is skipped. stomme cms warns about a file it cannot read and goes on without its blocks
collections.mjs export const collections = { … }, content collections added beside the engine's. They reach the site only when its src/content.config.ts spreads ...stommeAddonCollections() from @gronare/stomme/addon-collections into its collections
cms.mjs export const collections, a list of { feature, yaml } entries or a function returning one: CMS editors added when that feature flag is on. The function is called with { routes, features, blocks, fields }: the site's routes and feature flags, blocks(indent) returning the YAML of the site's block list, and fields.button(name, label, indent = 8, hint) and fields.link(name, label, indent = 8, hint) returning the YAML of a button or a link field. panelFiles, an object or a function of the same argument, maps an existing collection's name to { feature, yaml } files added to it the same way
routes.mjs export const routes, a list or a function of { routes, features } returning { feature, pattern, entrypoint }: a route injected when that feature flag is on, and under every language prefix on a translated site
preview.astro what /preview?kind=<kind> renders for a kind the engine does not know, so your CMS editors can preview their own entries. It gets the props kind, draft (the entry being edited) and config (the resolved site config)
previews.js CMS preview templates, copied to public/admin/stomme-addon-previews.js and loaded by /admin

An entry in cms.mjs without a feature or a yaml, or in routes.mjs without a feature, a pattern starting with / or an existing entrypoint, is skipped with a warning. A cms.mjs or routes.mjs that fails to load stops the build with its path.