Skip to content

Configuration Reference

Options passed to the cms() integration function in astro.config.ts.

interface CmsConfig {
config?: string;
mountPoint?: string;
admin?: boolean;
storage?: StorageConfig;
localStorageInDev?: boolean;
media?: MediaConfig;
locale?: "en" | "de";
i18n?: { locales?: string[]; defaultLocale?: string } | false;
previewUrl?: string;
ai?: AiConfig;
webmcp?: WebmcpConfig;
}
Property Type Default Description
config string auto-discovered Path to the CMS config file relative to the project root
mountPoint string "/admin" URL path for the admin panel
admin boolean true for Git storage Ship the admin and its API in astro build, false builds a purely static site. astro dev always serves the admin
storage StorageConfig { type: "local" } Storage backend configuration
localStorageInDev boolean true Edit the working tree during astro dev instead of the configured backend
media MediaConfig {} Media libraries configuration
locale "en" | "de" "en" Default admin panel UI language
i18n ContentI18n | false the site’s astro i18n Content languages
previewUrl string — URL pattern for branch previews from your host
ai AiConfig disabled Built-in assistant, see AI Assistant
webmcp WebmcpConfig disabled Expose the CMS tools to agents in the editor’s browser, see Browser Agents

Content languages, inherited from the site’s own i18n in astro.config.ts. Set it to override them, or to false to disable multilingual editing.

{
locales?: string[];
defaultLocale?: string;
}

See the Multilingual Content guide.

A discriminated union defining the storage backend.

{
type: "local";
}

Reads and writes files on disk via the dev server. Only available during development.

{
type: "github";
repo: string;
branch?: string;
clientId: string;
publishMode?: "direct" | "pull-request";
}
Property Type Default Description
repo string required Repository in owner/repo format
branch string "main" Target branch
clientId string required GitHub App client ID. A classic OAuth App is not supported
publishMode "direct" | "pull-request" "direct" Commit strategy

The client secret goes in ASTRONAUT_CMS_GITHUB_CLIENT_SECRET; see Storage Backends.

{
type: "gitlab";
project: string;
branch?: string;
clientId: string;
instanceUrl?: string;
scopes?: string[];
publishMode?: "direct" | "pull-request";
}
Property Type Default Description
project string required Project in group/project format
branch string "main" Target branch
clientId string required GitLab OAuth application ID
instanceUrl string "https://gitlab.com" GitLab instance URL
scopes string[] ["api"] OAuth scopes (api is required for API writes)
publishMode "direct" | "pull-request" "direct" Commit strategy

The media libraries: the repository library, always present, and optionally an object store beside it. Each one gets its own entry in the admin’s sidebar and decides for itself which files it takes.

interface MediaConfig {
repo?: RepoMediaConfig;
s3?: S3MediaConfig;
}

Every library takes these options:

Property Type Default Description
label string translated The library’s name in the admin
allowedExtensions string[] any file Restricts the library to these extensions (with leading dot)
minFileSize number none Smallest upload in bytes, checked in the admin and again on the server
maxFileSize number see below Largest upload in bytes, checked in the admin, signed into an object-store upload URL, and checked on arrival
optimizeImages ImageOptimizationConfig | false enabled How the browser reshapes an image before uploading it here, or false to upload originals untouched

The sizes are checked against the file as it is uploaded, after optimization where that is enabled. The bounds of the two libraries may overlap.

The library in the repository. Its uploads are commits on the draft branch, published with content.

Property Type Default Description
directory string "src/assets" Media directory relative to the project root
prune boolean automatic Whether a build deletes the library files nothing delivered links

Its uploads pass through the CMS route, which holds each one in memory, so maxFileSize is also that route’s body limit. It defaults to 100 MiB, the largest file GitHub accepts, while the object store has none, except for its devDirectory in astro dev, whose uploads also pass through the CMS route.

A build emits the whole library and then deletes unlinked copies whose source can be identified. Astro image originals without source metadata remain in the output. By default it keeps the whole library when on-demand code can reach content or library media, since such a page may link any file at request time. On-demand routes with no path to either allow pruning by default. true prunes anyway, false always keeps every file. See Asset Handling for the details.

An object store beside the repository library. It is independent of storage: content lives in Git either way.

type S3MediaConfig =
| {
provider?: "s3";
bucket: string;
endpoint: string;
publicUrl: string;
region?: string;
prefix?: string;
forcePathStyle?: boolean;
devDirectory?: string | false;
}
| {
provider: "r2";
bucket: string;
publicUrl: string;
accountId: string;
prefix?: string;
devDirectory?: string | false;
};
Property Provider Description
provider both "s3" (default) for any S3-compatible store, "r2" for Cloudflare R2
bucket both Bucket holding the library
endpoint s3 API endpoint, e.g. https://s3.eu-central-1.amazonaws.com
publicUrl both Public base URL the library is served under. Content stores each file’s URL under it. Required
region s3 Signing region (default: inferred from endpoint on AWS, R2 and Backblaze B2, otherwise "us-east-1")
prefix both Key prefix the library is rooted at (default: the bucket root)
forcePathStyle s3 Address objects as <endpoint>/<bucket>/<key>
accountId r2 Cloudflare account id, for the S3 API endpoint
devDirectory both Where astro dev keeps the library instead of the bucket (default: ".astronaut-cms/s3"), false for the bucket

See the Media Library guide for the setup an object store needs.

How an image is reshaped in the browser before it is uploaded. See Media Library for what it is for and when to turn it off.

interface ImageOptimizationConfig {
maxWidth?: number;
maxHeight?: number;
maxFileSize?: number;
format?: "jpeg" | "png" | "webp" | "avif";
quality?: number;
minQuality?: number;
}
Property Type Default Description
maxWidth number 2048 Widest an upload may be, in pixels. Wider images are scaled down, aspect ratio intact
maxHeight number 2048 Tallest an upload may be, in pixels
maxFileSize number 8388608 (8 MiB) Size in bytes above which an image is re-encoded even when its dimensions already fit
format "jpeg" | "png" | "webp" | "avif" keep the original Convert every upload into one format
quality number 0.92 Encoder quality for lossy formats, between 0 and 1
minQuality number 0.5 Lowest quality the maxFileSize ladder descends to

maxFileSize is a threshold rather than a guarantee: the image is encoded at quality, then at steadily lower ones down to minQuality, and the first result that fits is uploaded. An image that will not compress that far is uploaded at minQuality anyway, still smaller than the original. PNG output ignores the ladder entirely, since a canvas has no lossy PNG encoder.

It is distinct from a library’s own maxFileSize: that one refuses an upload, this one shrinks it first.