CMS Configuration
The CMS config file (src/cms.config.ts) holds everything the CMS adds to your content collections: the MDX block components editors can use in entry bodies, options per collection, and links of the admin’s sidebar.
Everything else, such as storage, media and the assistant, is configured in astro.config.ts.
The file is bundled into the admin and loaded on the server to render components, so keep secrets and Node-only imports out of it.
Basic Setup
Section titled “Basic Setup”import { defineComponent } from "astronaut-cms/config";import { z } from "zod";import { TriangleAlert } from "lucide-react";
export const components = { Alert: defineComponent({ props: z.object({ type: z.enum(["info", "warning", "error"]).default("info"), }), component: "@/components/Alert.astro", children: "markdown", label: "Alert", icon: TriangleAlert, }),};Editors insert a component with the insert menu of the body. In the body, a component is a compact block that shows its label and summary and holds its children. Clicking it selects it, and its props are edited in the inspector next to the body.
Collection Options
Section titled “Collection Options”The collections export gives options to collections of src/content.config.ts, keyed by name, as components holds one defineComponent() per component:
import { defineCollection } from "astronaut-cms/config";import { Users } from "lucide-react";
export const collections = { team: defineCollection({ sort: { by: "file" }, label: "Team", description: "The people shown on the about page.", icon: Users, }),};A name that is not a collection of the content config fails the build.
See Entry order for the sort values.
The label (default: the name, title-cased), description and icon are what the admin shows for the collection in its navigation and pages.
Agents read the label and description to learn what the collection is for.
The links export lists pages the admin links to in its sidebar, such as the site itself or a dashboard the site serves next to the CMS:
import { defineLink } from "astronaut-cms/config";import { Globe, LayoutDashboard } from "lucide-react";
export const links = [ defineLink({ label: "Dashboard", href: "/dashboard/", icon: LayoutDashboard }), defineLink({ label: "Website", href: "/", icon: Globe }),];A link opens in place of the admin, and the browser asks before discarding unsaved edits.
The icon defaults to an external link icon.
Component Definition
Section titled “Component Definition”Each component is defined using defineComponent() with the following options:
- Type:
z.ZodType - Default: no props
A Zod schema defining the component’s props. Leave it out for a component that takes none, such as a block that renders a collection. The admin panel generates a form from this schema, shown in the inspector next to the body once the component is selected. Its fields take the same labels and groups as a collection’s, and its lists of objects open in the inspector the same way.
component
Section titled “component”- Type:
string
The .astro component that renders it, written as an import of cms.config.ts, such as "@/components/Alert.astro" or "./components/Alert.astro".
A file that does not exist fails astro sync, astro dev and astro build.
See Rendering Components for how MDX bodies use it.
children
Section titled “children”- Type:
"markdown" | Record<string, ComponentDefinition> - Default:
undefined
Defines what the component accepts as children.
Set to "markdown" for components that wrap markdown content.
Set to an object for components that contain named child components (e.g., tabs with tab items).
- Type:
"flow" | "text" - Default:
"flow"
Where the component is written: "flow" on lines of its own, like a block, and "text" within a line of text, like a badge in a sentence.
Where only a line of text fits, such as a table cell, the insert menu and pasting offer "text" components alone.
- Type:
string - Default: the component key name
A human-readable label shown in the admin panel.
description
Section titled “description”- Type:
string - Default:
undefined
What the component is for, shown when inserting it and in the inspector.
collections
Section titled “collections”- Type:
CollectionName[], a collection name of the content config - Default:
undefined
The collections whose entries the component renders, such as ["projects"] for a block that lists the projects.
The inspector links to each, since that is where the content of the block is edited.
The build fails if one is not a collection of the content config.
summary
Section titled “summary”- Type:
string - Default: the first required text prop with a value, then any text prop with one
The prop whose value names an instance, such as "title".
The body shows it on the component’s block, and the inspector lists structured children by it.
- Type:
ComponentIcon - Default:
undefined
An icon shown in the admin panel, any React component that takes a className, such as a Lucide React icon.
editor
Section titled “editor”- Type:
JsxEditor - Default:
undefined
A React component that edits the element in place of the generated form.
Build it with the primitives of astronaut-cms/editor, which are the admin’s own editor instance:
import { NestedLexicalEditor, type JsxEditorProps } from "astronaut-cms/editor";
function CalloutEditor(_: JsxEditorProps) { return ( <NestedLexicalEditor block getContent={(node) => node.children} getUpdatedMdastNode={(node, children) => ({ ...node, children })} /> );}useMdastNodeUpdater() merges fields into the element, and useLexicalNodeRemove() removes it.
A separate install of @mdxeditor/editor would be a second copy whose hooks find none of the admin’s state.
Nested Components
Section titled “Nested Components”Components can contain named child components. This is useful for container patterns like tabs:
import { defineComponent } from "astronaut-cms/config";import { z } from "zod";
export const components = { Tabs: defineComponent({ props: z.object({}), component: "@/components/Tabs.astro", children: { Tab: defineComponent({ props: z.object({ label: z.string(), }), component: "@/components/Tab.astro", children: "markdown", label: "Tab", }), }, label: "Tabs", }),};In MDX content, this renders as:
<Tabs> <Tab label="First">Content for the first tab.</Tab> <Tab label="Second">Content for the second tab.</Tab></Tabs>In the body, each child is a block of its own inside its parent, and its markdown children stay editable in place. Only the declared child components can be added there, new or pasted from the clipboard. Selecting the parent lists its children in the inspector, where they can be reordered by dragging and opened one by one, with breadcrumbs leading back out.
An MDX body refers to a component by its name alone, so a name may stand for one definition only. Two parents may share a child definition under the same name, but two different definitions with one name fail the build.
Asset Fields
Section titled “Asset Fields”A prop that names a media file is declared with the image() / file() helpers your props
function is handed, the same way a collection schema is handed astro’s image(). Write props as
a function only when you need them; otherwise declare the object directly.
import { defineComponent } from "astronaut-cms/config";import { z } from "zod";
export const components = { Hero: defineComponent({ props: ({ image }) => z.object({ cover: image(), caption: z.string().optional(), }), component: "@/components/Hero.astro", children: "markdown", label: "Hero", }), Download: defineComponent({ props: ({ file }) => z.object({ document: file(), label: z.string(), }), component: "@/components/Download.astro", label: "Download", }), Quote: defineComponent({ // No asset props, so no helpers are needed. props: z.object({ text: z.string(), author: z.string() }), component: "@/components/Quote.astro", label: "Quote", }),};The admin panel renders these as asset pickers connected to the media library.
Asset props are stored as root-absolute path strings.
The generated wrapper resolves every image() prop before the component renders, so a component receives its images as a collection’s image() field arrives: as ImageMetadata, or an object-store URL.
A file() prop arrives as its path, as a collection’s file() field does, and resolveFile() turns it into a URL.
See Asset Handling for how the matching component renders them.
Allowed Body Content
Section titled “Allowed Body Content”Entries are held to a small subset of their format, so neither an editor nor the assistant can put code into the site.
- MDX may use registered components by name, pass them literal props, and use
<div>and<span>with a literalclassas wrappers. Any other element, attribute, directive, expression, spread, import or export is refused.{/* comments */}are allowed. - Markdown and Markdoc may not contain raw HTML.
- Links and images may only point to relative,
http,https,mailtoortelURLs. - URLs in fields may only be stored in a
link()orz.url()field, with the same schemes. Any other string field, in frontmatter, data or component props, refuses a value that would act as a link. - Links to
#idhave to name ananchor()or a Markdown heading of the same entry.
Anything beyond that belongs in a registered component.
astro build fails on committed content outside the subset or its collection schema, and astro dev warns about it, so editors never open an entry they cannot save.
Rendering Components
Section titled “Rendering Components”The integration generates the module astronaut-cms:components from cms.config.ts.
It wraps each component, nested ones included, so that its schema parses the props MDX passes as written, and every .default() and transform applies before the component renders.
Pass mdxComponents to every rendered body, so the body uses each component by name and never imports one:
---import { render } from "astro:content";import { mdxComponents } from "astronaut-cms:components";
const { entry } = Astro.props;const { Content } = await render(entry);---
<Content components={mdxComponents} />The schema stays the only place a default is written.
A page or component that renders a block itself imports its wrapped version from the same module, as in import { Alert } from "astronaut-cms:components", so the defaults apply there too.
See astronaut-cms:components for everything the module exports, how a component types its props, and when the module is regenerated.
