Configuration

createCMS(definition) builds a configured CMS instance. The definition is typed as CMSDefinition (see packages/cms/src/core/types/definitions.ts).

import { createCMS } from '@createcms/core';

export const cms = createCMS({
  db,
  collections,
  media,
  authMiddleware,
});

Options

media

MediaConfig is a discriminated union on provider. These base fields apply to every provider:

Each provider adds its own fields:

• provider: 'aws': region (required), forcePathStyle (default false).
• provider: 'digitalOcean': region (required), forcePathStyle (default true).
• provider: 'cloudflare': accountId (required), jurisdiction, forcePathStyle (default true).
• provider: 'custom': hostname (required), region (required), secure (default true), forcePathStyle (default true).

const media = {
  provider: 'cloudflare',
  accountId: process.env.R2_ACCOUNT_ID!,
  bucketName: process.env.R2_BUCKET!,
  accessKeyId: process.env.R2_KEY!,
  secretAccessKey: process.env.R2_SECRET!,
  publicUrl: process.env.R2_PUBLIC_URL!,
};

authMiddleware

A function that receives the request context and returns a result object. userId is optional (anonymous requests omit it); any extra fields you return extend the context available to scoping and hooks.

import { defineAuthMiddleware } from '@createcms/core';

const authMiddleware = defineAuthMiddleware(async (ctx) => {
  // ctx.operation, ctx.request (a curated request; the raw Request is at
  // ctx.request?.request), and ctx.collection (collection-scoped calls only).
  return { userId: await resolveUser(ctx) };
});

realtime

Enables live server-to-client delivery — notification push and A/B live results — over Server-Sent Events. Upstash-only: pass your Upstash Redis credentials. @upstash/realtime and @upstash/redis are optional peer dependencies. See Realtime.

const realtime = {
  url: process.env.UPSTASH_REDIS_REST_URL!,
  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
};

Requires authMiddleware to resolve the user from the request cookie — the realtime route authenticates each connection by session, so it must be same-origin with your app. Omit realtime to disable; notifications stay available through the listNotifications poll.

notifications

Set false to fully disable the notifications feature. When disabled, the notification tables are not generated (regenerate your schema after toggling), the routes never register, and client.notifications plus cms.notify are absent from the inferred types. Default: enabled. Use a literal false — a widened boolean keeps the types enabled. Independent of realtime.

const cms = createCMS({ /* … */ notifications: false });

dataRetention

The whole object is optional, but when you provide it, keepDays and keepMinCommits are required.

branchProtection

Governance for published content and the merge/publish approval gates. Every field is opt-in; an empty config preserves current behavior. Each field can be overridden per collection via the collection's own branchProtection (a Partial<BranchProtectionConfig>): a collection's value wins over this global one field-by-field, and unset fields inherit the global value. For example a reusableBlock collection can set branchProtection: { protectPublishedBranches: false } to stay directly editable while pages keep the global protection.

user

Return value

createCMS returns: