Config Helpers
These functions and types are exported from astronaut-cms/config, except for the generated astronaut-cms:components module.
defineCollection()
Section titled “defineCollection()”Types one entry of the collections export of cms.config.ts, keyed by collection name like content.config.ts.
function defineCollection(options: CollectionOptions): CollectionOptions;
interface CollectionOptions { sort?: { by: "id" | "natural" | "file" } | { by: "field"; field: string }; // default: { by: "id" } label?: string; // default: the name, title-cased description?: string; icon?: ComponentIcon;}The label, description and icon name and explain the collection in the admin, and agents read the label and description too.
defineLink()
Section titled “defineLink()”Types one entry of the links export of cms.config.ts, a link of the admin’s sidebar.
function defineLink(options: LinkOptions): LinkOptions;
interface LinkOptions { label: string; href: string; // a path of the site or a full URL icon?: ComponentIcon; // default: an external link icon}defineComponent()
Section titled “defineComponent()”A type-safe wrapper for component definitions, which returns the definition as it is.
function defineComponent<T extends z.ZodType, C extends ChildrenConfig>( def: ComponentDefinition<T, C>,): ComponentDefinition<T, C>;import { defineComponent } from "astronaut-cms/config";import { z } from "zod";
const Alert = defineComponent({ props: z.object({ type: z.enum(["info", "warning", "error"]), }), component: "@/components/Alert.astro", children: "markdown", label: "Alert",});Schema helpers (image, file, link, anchor, localized, reference)
Section titled “Schema helpers (image, file, link, anchor, localized, reference)”A component’s props may be written as a function, which receives the asset, link, anchor, localized and reference helpers:
type SchemaHelpers = { image: () => z.ZodType<ResolvedImage, string>; // written as a path, rendered resolved file: () => z.ZodString; link: () => z.ZodString; anchor: () => z.ZodString; localized: <T extends z.ZodType>(schema: T) => z.ZodRecord<z.ZodString, T>; reference: (collection: CollectionName) => z.ZodString;};
props: T | ((helpers: SchemaHelpers) => T);image() and file() create Zod strings tagged with x-cms-image / x-cms-file metadata, which
the admin renders as pickers connected to the media library. The stored value is a root-absolute
path string. The component wrapper resolves an image() prop before the component renders, and a
file() prop is resolved with resolveFile() (see Asset Handling).
import { defineComponent } from "astronaut-cms/config";import { z } from "zod";
const Hero = defineComponent({ props: ({ image }) => z.object({ cover: image() }), component: "@/components/Hero.astro", children: "markdown",});
const Download = defineComponent({ props: ({ file }) => z.object({ document: file(), label: z.string() }), component: "@/components/Download.astro",});link() creates a Zod string tagged with x-cms-link metadata.
It accepts relative, http, https, mailto and tel URLs, and it is the only way to store a URL.
Every other string field, z.url() aside, refuses a value that would act as a link, such as https://example.com, //host, mailto:a@b.c or javascript:alert(1).
z.url() works too, but it only takes absolute URLs, and the CMS limits it to the same schemes.
const CallToAction = defineComponent({ props: ({ link }) => z.object({ label: z.string(), href: link() }), component: "@/components/CallToAction.astro",});anchor() declares the prop that renders an element id, such as the id of a section.
Its value is the id without # and without spaces.
A link to #id, in a link() field or a Markdown link, has to name an anchor of the same entry, a Markdown heading of it by the id astro derives from its text, or #top.
Each anchor may occur only once in an entry.
Saving refuses a link that matches none, astro build fails on one and astro dev warns about it.
A prop that points at an anchor, such as the target of a jump navigation, is a link() holding #id.
Links to another page, such as /services/#heating, are not checked, since the routes of the site decide which entry a URL renders.
const Section = defineComponent({ props: ({ anchor }) => z.object({ id: anchor().optional(), title: z.string() }), component: "@/components/Section.astro", children: "markdown",});reference(collection) stores the id of an entry in another collection, which the admin offers as a picker and checks on save.
The component receives the id and can look the entry up with getEntry().
CollectionName is the union of the collection names of the content config, generated like astronaut-cms:components, so a misspelled name is a type error.
const TeamMember = defineComponent({ props: ({ reference }) => z.object({ member: reference("team") }), component: "@/components/TeamMember.astro",});cms.config.ts is bundled into the browser admin and loaded by the component wrappers on the server, so it cannot import content.config.ts or anything from astro:content.
Keep values both configs use, such as a shared z.enum() of colours, in a module of their own that each imports.
image is deliberately not importable. A collection field takes astro’s own ({ image }) and a
component prop takes the one its props function is handed, so there is no spelling that resolves in
one place and silently fails in the other.
file(), link(), anchor() and localized()
Section titled “file(), link(), anchor() and localized()”The helpers that are exported, because astro’s collection schema has no counterpart for them.
Use them for a non-image asset, a URL, an element id or a value per language in a content.config.ts field:
import { file, link, localized } from "astronaut-cms/config";
const pages = defineCollection({ loader: glob({ pattern: "**/*.mdx", base: "src/content/pages" }), schema: ({ image }) => z.object({ cover: image(), // astro's helper: resolved into entry.data brief: file().optional(), // the CMS's: a path string, resolved with resolveFile() website: link().optional(), // the only kind of field that may hold a URL tagline: localized(z.string()), // { de: "…", en: "…" }, read with pickLocale() }),});See Localized fields for localized().
Inside a cms.config.ts props function, take file, link, anchor and localized from the helpers instead of importing them.
astronaut-cms:components
Section titled “astronaut-cms:components”A module the integration generates from cms.config.ts.
astro sync, astro dev and astro build regenerate it and its types, and so does every change to cms.config.ts during astro dev.
declare module "astronaut-cms:components" { /** The props each component renders with, every schema default applied and every image resolved, nested children included. */ export type ComponentProps = { [Name in ComponentName]: z.output<Schema[Name]> };
/** Every component by name, for `<Content components={mdxComponents} />`. */ export const mdxComponents: { [Name in ComponentName]: Wrapper<Name> };
/** Each component on its own, under its name. */ export const Alert: Wrapper<"Alert">;}A wrapper parses the props it receives with the component’s schema, so every .default() and transform applies, resolves every image() prop to ImageMetadata or an object-store URL, and renders the component of the definition’s component with the result.
It keeps attributes the schema does not declare, such as class, and throws an error naming the component for invalid props.
It takes the props as MDX writes them, where a prop with a .default() is optional.
Type each component with ComponentProps, which holds the props as the component receives them, with every default applied.
A component without props gets an empty type, so it can add props a page passes it directly:
---import type { ComponentProps } from "astronaut-cms:components";
type Props = ComponentProps["Alert"];
const { type } = Astro.props;---
<div class={`alert alert-${type}`}> <slot /></div>See Rendering Components for passing mdxComponents to a body.
ComponentDefinition
Section titled “ComponentDefinition”The interface for a single component definition.
interface ComponentDefinition<T extends z.ZodType = z.ZodType> { props?: T | ((helpers: SchemaHelpers) => T); component: string; children?: "markdown" | Record<string, ComponentDefinition>; kind?: "flow" | "text"; label?: string; description?: string; collections?: CollectionName[]; summary?: string; icon?: ComponentIcon; // a React component taking `className` editor?: JsxEditor;}