Configuration Reference
CmsConfig
Section titled “CmsConfig”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.
StorageConfig
Section titled “StorageConfig”A discriminated union defining the storage backend.
Local Storage
Section titled “Local Storage”{ type: "local";}Reads and writes files on disk via the dev server. Only available during development.
GitHub Storage
Section titled “GitHub Storage”{ 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.
GitLab Storage
Section titled “GitLab Storage”{ 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 |
MediaConfig
Section titled “MediaConfig”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.
RepoMediaConfig
Section titled “RepoMediaConfig”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.
S3MediaConfig
Section titled “S3MediaConfig”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.
ImageOptimizationConfig
Section titled “ImageOptimizationConfig”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.
