Configuration

This page is a reference, not a tutorial. For the path through, start with Quickstart.

`caret(options)` shape

import caret from '@caretcms/core';

caret({
  // Mode
  mode: 'embedded' | 'cloud',

  // Routes
  mountPath: '/admin',
  apiBasePath: '/api/cms',

  // Toggles
  enableAdmin: true,
  enableInlineEditor: true,

  // Storage and uploads (embedded mode only)
  storage: filesystemStorage(),
  uploads: localUploads(),

  // Cloud (cloud mode only)
  cloud: {
    endpoint: 'https://cloud.caretcms.com',
    projectId: 'proj_marketing_site',
    contentPath: '/content',
    publicToken: '...',
    environment: 'production',
  },

  // Schemas
  schemas: { /* collection: jsonSchema */ },
})

Options at a glance

Option	Default	Type
`mode`	`'embedded'`	`'embedded' \| 'cloud'`
`mountPath`	`'/admin'`	`string`
`apiBasePath`	`'/api/cms'`	`string`
`enableAdmin`	`true` (embedded), `false` (cloud)	`boolean`
`enableInlineEditor`	`true` (embedded), `false` (cloud)	`boolean`
`storage`	`filesystemStorage()`	`CaretStorageProvider`
`uploads`	`localUploads()`	`CaretUploadProvider`
`cloud`	—	`CaretCloudOptions` (required when `mode: 'cloud'`)
`schemas`	`{}`	`Record<string, JsonSchemaDefinition>`

Mode

Default: 'embedded'
Values: 'embedded' | 'cloud' Alpha

embedded runs the CMS inside your Astro site — middleware, admin UI, API routes, all served from the same origin. This is what you want today.

cloud is alpha. The integration accepts the option and ships a client bootstrap, but the hosted control plane isn’t live yet.

Routes

`mountPath`

Where the admin UI mounts. Login is ${mountPath}, Studio is ${mountPath}/cms.

caret({ mountPath: '/staff' })
// → /staff, /staff/cms

Use this if /admin collides with your app’s existing routes.

`apiBasePath`

Base path for all API routes. Every endpoint hangs off this:

${apiBasePath}/entries
${apiBasePath}/mutate
${apiBasePath}/schema
${apiBasePath}/auth/login
…etc

If your project’s src/pages/api/ already has CMS-adjacent routes, change this to avoid collisions.

Toggles

`enableAdmin`

Whether to inject the admin routes (mountPath, mountPath/cms, mountPath/themes). Set to false to disable Studio entirely while keeping the API surface (e.g. for a pure-headless setup or to disable editing in prod).

`enableInlineEditor`

Whether to inject the inline-editor bootstrap script onto pages. Disable to turn off data-caret click-to-edit while keeping Studio working. Useful in production if you want editing to happen only via the admin UI, not on live pages.

Storage and uploads

`storage`

Where entries, revisions, history, and dynamic-collection metadata live. See Storage Adapters.

import { filesystemStorage } from '@caretcms/core';

filesystemStorage({
  dataRoot: 'src/content/cms',         // optional — default: '.caret/data'
  metaRoot: 'src/content/cms/.meta',   // optional — default: '.caretcms'
})

import { cloudflareStorage } from '@caretcms/cloudflare';

cloudflareStorage({ binding: 'CMS_KV' }) // default binding: 'CMS_KV'

import { defineStorageProvider } from '@caretcms/core';

defineStorageProvider({
  entrypoint: './src/cms/postgres-adapter.ts',
  exportName: 'postgresStorageProvider',
  options: { connectionString: process.env.DATABASE_URL },
})

`uploads`

Where uploaded files (images via <img data-caret>) go. Same shape as storage.

Local (default)
Cloudflare R2

import { localUploads } from '@caretcms/core';

localUploads({ uploadsDir: './public/uploads' }) // default: 'public/uploads'

import { r2Uploads } from '@caretcms/cloudflare';

r2Uploads({ binding: 'CMS_R2' }) // default binding: 'CMS_R2'

Cloud

Required when mode: 'cloud'. Ignored otherwise.

Field	Default	Notes
`endpoint`	—	Hosted control plane URL. Required.
`projectId`	—	Project ID in the hosted control plane. Required.
`contentPath`	`'/content'`	API base path on the hosted endpoint.
`publicToken`	undefined	Public bootstrap token (per-project).
`environment`	undefined	Environment name (`'preview'`, `'production'`).

Schemas

Map of collection name → JSON Schema. Highest priority schema source. See Schemas.

caret({
  schemas: {
    pages: z.toJSONSchema(PageSchema),
    site: z.toJSONSchema(SiteSchema),
  },
})

Environment variables

Variable	Required	Purpose
`CARET_EDIT_PASSWORD`	Yes (for editing)	Editor password — anyone with it can log in
`EDIT_PASSWORD`	Fallback	Same as above; kept for backward compat
`CARET_SESSION_SECRET`	Strongly recommended in prod	HMAC secret for session cookies
`CARET_SESSION_TTL_HOURS`	Optional	Override the default 12h session TTL

See Authentication & Security for how each one is used.

Cloudflare deployments also need bindings declared in wrangler.toml:

Binding	Purpose
`CMS_KV` (or your custom name)	KV namespace for storage
`CMS_R2` (or your custom name)	R2 bucket for uploads

Defaults summary

{
  mode: 'embedded',
  mountPath: '/admin',
  apiBasePath: '/api/cms',
  enableAdmin: true,
  enableInlineEditor: true,
  storage: filesystemStorage(),         // → .caret/data/
  uploads: localUploads(),              // → public/uploads/
  schemas: {},                          // → all collections inferred
}

Common combinations

caret({
  enableAdmin: import.meta.env.PROD === false,
  enableInlineEditor: import.meta.env.PROD === false,
})

caret({
  mountPath: '/cms-admin',
  apiBasePath: '/api/cms-admin',
})

caret({
  storage: cloudflareStorage({ binding: 'CMS_KV' }),
  uploads: r2Uploads({ binding: 'CMS_R2' }),
  schemas: {
    pages: z.toJSONSchema(PageSchema),
  },
})

caret({
  enableAdmin: false,
  enableInlineEditor: false,
})

API routes still mount; everything UI-related is skipped.

Next steps

Storage Adapters Pick the right adapter for your host.

Authentication & Security Production hardening.

Deployment Per-host setup.