Keystatic + Astro

Keystatic writes Git-tracked files; Astro reads them via the Content Layer (getCollection, getEntry, render). Do not use createReader.

Match @astrojs/ and @keystatic/ APIs to the versions in the project's package.json / lockfile.

Official docs (check these before guessing APIs):

Do not duplicate upstream Keystatic or Astro API reference in this skill.

When to apply

• Adding or changing a Keystatic collection or singleton
• Wiring keystatic.config.* or src/content.config.ts
• Choosing content vs data vs JSON format, folder layout under src/content/
• Adding MDX custom blocks or image handling
• Fetching external data into Astro collections at build time
• Splitting local CMS content from API-backed content

Config locations

Astro: Content collections · Keystatic: Configuration

Astro config & environment

Copy [examples/astro.config.example.mjs](examples/astro.config.example.mjs) into the project root as astro.config.mjs and extend with site-specific integrations. It covers:

• loadEnv from Vite (.env is not auto-loaded into astro.config.mjs)
• output: 'static' — Astro v5+ removed hybrid; static sites can still use on-demand routes with an adapter (on-demand rendering)
• Conditional keystatic() via ASTROENABLEKEYSTATIC — off for static production CI builds
• Netlify adapter via ASTROUSENETLIFY_ADAPTER
• env.schema for typed env vars used in config and client code

Pair with the matching .env example for each deploy target:

KEYSTATICSTORAGEKIND must be public + client context in env.schema so keystatic.config.* can import it from astro:env/client.

Astro: Environment variables · On-demand rendering · Keystatic & Astro · Configuring Astro

Dual-file pattern (required)

Every content type gets two paired files:

Register both in root configs:

• keystatic.config. → imports all keystaticConfig
• src/content.config.ts → imports all astro*Definition into export const collections

Every Astro collection needs a loader (typically glob() or file() from astro/loaders, or a custom async loader). Import z from astro/zod.

Export naming:

• Keystatic: keystaticFaqsConfig, keystaticItemsConfig
• Astro: astroFaqsDefinition, astroItemsDefinition

Export shared enums and paths from the Keystatic file; import them in Astro:

// faqs.keystatic.ts
export const categoryEnumAndOrder = ['Allgemein', 'Planung & Bau', ...] as const
export const basePath = 'src/content/faqs'

// faqs.astro.ts
import { defineCollection } from 'astro:content'
import { z } from 'astro/zod'
import { basePath, categoryEnumAndOrder } from './faqs.keystatic'
import { loader } from './utils/loader'

export const astroFaqsDefinition = defineCollection({
  loader: loader(basePath, 'mdx'),
  schema: z.object({ category: z.enum(categoryEnumAndOrder), ... }),
})

Astro: Defining build-time collections · Keystatic: Collections · Astro integration

File splitting

All collection and singleton definitions live in cms/ at the project root.

Supporting files per concern

MDX blocks (three layers)

components/{Block}/
├── keystatic.{Block}.config.ts   # block() schema + ContentView preview
├── {Block}.astro                 # frontend render
└── KeystaticPreview.tsx          # optional CMS image preview

Disable built-in MDX images everywhere: fields.mdx({ options: { image: false } }). Use custom block() components for images instead.

Keystatic: MDX field · Content components · Astro: MDX integration

Content structure

Folder layout under src/content/

Paths in Keystatic path must match on-disk layout. Collection key in content.config.ts is camelCase (e.g. homepageFacts → src/content/homepageFacts/).

Singleton multi-file pattern

One logical singleton can produce multiple files in one folder:

src/content/homepage/
├── index.mdx              # frontmatter + bodyBeforeQuotes
├── bodyAfterQuotes.mdx
└── bodyAfterMilestones.mdx

Load each part separately: getEntry('homepage', 'index'), getEntry('homepage', 'bodyaftermilestones').

Relationships

Use fields.relationship({ collection: 'otherCollection' }) in Keystatic. In Astro, relationship values resolve to entry slugs:

apiSyncedItems (JSON, fetch-to-disk)
       ↑ relationship (externalId)
items (MDX)
       ↑ relationship (parent)
itemDetails (MDX)

CMS list ergonomics

• slugField for slug-driven collections (title, name, imageAlt)
• columns: ['title', 'position', 'externalId'] for list view
• entryLayout: 'form' on content-heavy singletons
• [READONLY] labels for API-synced collections editable only via fetch

Keystatic: Collections · Singletons · Relationship field · Astro: Collection references

Astro integration

Loading content

Pass shared MDX components on every render:

import { render } from 'astro:content'

const { Content } = await render(entry)
<Content components={mdxComponentsAstro} />

Loaders

Every collection declares loader in defineCollection. For on-disk Keystatic content, use glob() via the shared helper:

// cms/utils/loader.ts
import { glob } from 'astro/loaders'

export const loader = (contentBase: string, format: 'mdx' | 'json' | 'yaml') => {
  const base = contentBase.startsWith('/') ? `.${contentBase}` : contentBase
  return glob({ base, pattern: `**\/[^_]*.${format}` })
}

Pattern excludes _-prefixed files (partials/drafts). For a single JSON/YAML file with many entries, use file() instead.

Type generation

Run astro sync after schema changes → .astro/content.d.ts.

Astro: Querying collections · Rendering body content · Generating routes · glob() loader · MDX components in content

Remote / fetched collections

Pick a pattern based on CMS visibility, API reliability at build time, and whether editors need a local override.

Remote collections register only in src/content.config.ts, not in keystatic.config.

For implementation details, decision flow, and merge patterns, see [remote-collections.md](references/remote-collections.md).

Astro: Custom build-time loaders · Content Loader API

Images

Astro: Images in content collections · Keystatic: Astro images recipe

Checklist: add a new local collection

1. Create {name}.keystatic.ts — export basePath, enums, keystatic{Name}Config
2. Create {name}.astro.ts — import shared exports, defineCollection with loader(basePath, format) and Zod schema
3. Register in keystatic.config.* (collections or singletons) and src/content.config.ts
4. Add UI navigation entry in keystatic.config.* ui.navigation
5. Create src/content/{name}/ folder (or let Keystatic create on first save)
6. Run astro sync and verify types
7. Consume via getCollection / getEntry / render in pages

Checklist: add a remote collection

1. Create Zod schema ({name}Schema.ts) — validate API response
2. Create {name}Astro.ts with async loader: async () => { fetch → parse → return entries }
3. Register in src/content.config.ts only
4. Decide fail-fast vs fallback (see [remote-collections.md](references/remote-collections.md))
5. If merging with local CMS data: share schema, merge in page via [...local, ...remote]

Anti-patterns

• Using createReader — use Astro Content Layer instead
• Duplicating enums/paths between Keystatic and Astro files — export from .keystatic.ts
• Enabling @keystatic/astro in static production builds
• Native MDX images when using custom blocks — always options: { image: false }
• Adding remote-only collections to Keystatic unless editors need readonly visibility (pattern C)