Configuration

A ChaiBuilder project is configured in four files, each with one job. Environment variables (database, secrets, license) are covered separately in Environment & License.

File Job
next.config.ts Next.js integration
chaibuilder.config.ts The builder's server config - plain data, importable anywhere
chaibuilder.server.ts Per-request context - auth, tenant, draft state
payload.config.ts Payload CMS + the ChaiBuilder Payload plugin

next.config.ts

Wrap your Next.js config with the ChaiBuilder wrapper (the Payload starter composes it with withPayload):

import { withChaiBuilder } from 'chaipro/nextjs'
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {}

export default withChaiBuilder(nextConfig)

The wrapper takes no options. Earlier releases accepted collections, actions, importMapPath, and watch here and generated an import map at startup; that step is gone. Collections, actions, and page types are now passed directly to buildChaiBuilderConfig, so there is no generated file to keep in sync. Extra options left in an old config are ignored.

chaibuilder.config.ts

The main server config, created with buildChaiBuilderConfig. It is deliberately plain data with no framework imports, so scripts, CI, and the Payload CLI can import it.

import 'server-only'
import { buildChaiBuilderConfig } from 'chaipro/nextjs/server'

export default buildChaiBuilderConfig({
  db,                         // required - database connection (see adapters below)
  plugins: chaiProServerPlugins(), // registered plugins define the feature set
  globalDataProvider,         // data merged into every page render
  pageTypes: [...],           // dynamic page types (blog posts, docs, ...)
  chaiCollections: [...],     // data sources for repeaters and collection blocks
  blockDataProviders: {},     // per-block-type server data
  actions: {},                // custom server actions
  ai: { models: [...] },      // AI models and provider
  features: { darkMode: true }, // switch core editor features on or off
  debugLevel: 0,              // 0 = off | 1 = DB+HTTP | 2 = full timing+SQL
})

Options

Field Required Description
db yes Database connection from an adapter factory
plugins - Feature set: a registered plugin turns its feature on; plugin options carry its config. Nothing is auto-installed
globalDataProvider - Async provider merged into every render ({ lang, draft, inBuilder })
pageTypes - Page types with data providers; on Payload, adapt a collection directly
chaiCollections - Data sources for repeaters and collection blocks, with declarative filter, sort, and limit
collections, repeaterData - Deprecated. Both are merged into chaiCollections; move them over when convenient
blockDataProviders - { BlockType: async provider } resolved per block instance
actions - Custom actions keyed by UPPER_SNAKE_CASE name. builderActions is the deprecated spelling and still works; when both name the same action, actions wins
ai - models, defaultModelId, actionModels (models per AI action), provider, providers, and logging. See AI Customization
features - Switch core editor features on or off, see Features below
roles - Where roles come from: omit for the built-in roles, pass a role map, or { source: 'custom' } with the roles plugin. See Roles and Permissions
defaultRoleGrants - Extra grants added to the built-in roles, { editor: ['redirects:*'] }. Ignored once roles come from a map or the database
trash - Extra trashable entities, on top of the ones plugins contribute
mediaManager - Which media manager tabs the core shows. Plugin tabs are configured through plugin options
onPageNotFound - Last say over a path that matched no page and no stored redirect: return { redirect } to send the visitor elsewhere, or nothing to keep the 404
resolveDynamicTemplateTie - Picks a winner when several dynamic page templates match one URL. Omit to keep registration order
upstreamPageSource - Where linked pages fetch their upstream page from, when features.upstreamPages is on. See Linked Pages
transformSiteSettings - Reshape the stored site settings row before it is cached
contextResolver - A process-wide request context resolver. An explicit createChaiBuilder context wins over it
debugLevel - 0, 1, or 2 - server-side cache/DB/HTTP logging

Plugins also contribute schemaFragments, requestMiddlewares, and setupHooks to the resolved config. You rarely set those by hand; see Developing Plugins.

A second argument accepts onInit (runs once on the first getChaiBuilder call in the process, e.g. migrations) and extend (arbitrary values merged into the resolved config).

Features

features switches parts of the editor on and off. Every key is optional; omitted keys use the default. These are the core flags only. Plugin features (redirects, revisions, animation, the library, ...) are turned on by registering the plugin, and cannot be set here.

Key Default Controls
ai on when any AI models are configured Every builder AI feature: AI panel, Ask AI, AI theme, SEO, alt text, image tools. Off also refuses model-calling actions on the server. MCP tools are unaffected
trash on when trash entities exist The trash panel and soft delete
copyPaste on Copy and paste of blocks and classes
darkMode off Dark mode toggle in the canvas top bar and theme panel
dataBinding on Data binding widgets and the canvas binding switcher
importHtml on The Import HTML entry in the Add Blocks panel
importTheme on The Import Theme entry in the theme panel
partialBlocks on Global blocks in the editor: "Create global block" in the block menu, the Create button in the pages manager, the Global Blocks tab and search results in Add Blocks, and a placed global block's settings and styles. Off hides them all; existing global blocks keep rendering
gotoSettings off "Go to settings" on the block floating actions
dragAndDrop on Drag and drop on the canvas and in Add Blocks
validateStructure on Live structure-rule validation while editing
designTokens on The design token picker in the classes panel
resetSeoToDefault off "Reset to default" in the SEO panel
pagesManager on The pages manager and its top bar trigger
chaiBranding off ChaiBuilder name, version, and docs links in the editor (console banner, page type help). Turn on only if you want them shown
siteLayout off The "Site layout" select in the theme panel. See Theming
upstreamPages off Linked pages that render a host-supplied upstream page. See Linked Pages
buildChaiBuilderConfig({
  db,
  features: { darkMode: true, importHtml: false },
})

Database adapters

Import the factory matching your database and pass its result as db:

Adapter Import Use
Postgres (postgres.js) chaipro/db/postgres hosted/self-managed Postgres
Postgres (node-pg pool) chaipro/db/node-pg share one pg.Pool with Payload
libSQL / Turso chaipro/db/libsql remote SQLite
SQLite (file) chaipro/db/better-sqlite3 local development, single server
Cloudflare D1 chaipro/db/d1 Workers deployments

The Payload starter uses createNodePgDb({ pool }) with a shared pool so Payload and the builder use one connection pool - see Database Setup.

Plugins

Features ship as plugins - redirects, revisions, trash, multilingual, media, roles, and more. Nothing is installed by default: a registered plugin turns its feature on, and its options carry the config. chaiProServerPlugins() returns the standard set; spread it and add the opt-in plugins you want:

import { chaiProServerPlugins, mcpPlugin } from 'chaipro/plugins/server'

plugins: [
  ...chaiProServerPlugins(),   // redirects, trash, library, revisions, multilingual, ...
  mcpPlugin(),                 // opt-in: MCP server for AI agents
]

mcpPlugin, rolesPlugin, and a media plugin are deliberately not in the preset. Register client counterparts on the builder component. Without any plugins the server logs a warning that pro features are off. The full list, with what each one adds: Built-in Plugins.

chaibuilder.server.ts

Creates the request-scoped entry point every server file imports. On Payload, one line derives the whole request context (identity, tenant, draft, site URL) from Payload:

import config from '@/chaibuilder.config'
import { createChaiPayloadBuilder } from 'chaipro/payload'

export const { getChaiBuilder } = createChaiPayloadBuilder(config)

Builder access comes from the user's app membership - a Payload login by itself grants no builder access. For non-Payload auth, use createChaiBuilder(config, { context }) and resolve { appId, userId, permissions, draft, siteUrl } yourself - see API for the context contract.

payload.config.ts

Standard Payload config plus two ChaiBuilder touch points:

import { chaiBuilderPlugin, chaiBuilderSchemaHook } from 'chaipro/payload'
// SQLite Payload adapters use chaiBuilderSchemaHookSqlite

export default buildConfig({
  db: postgresAdapter({
    beforeSchemaInit: [chaiBuilderSchemaHook],  // merges ChaiBuilder tables into
    // Payload's schema so one migration pipeline covers both
  }),
  plugins: [
    chaiBuilderPlugin({
      menus: true,                            // show the Menus collection in the admin nav
      revalidateCollections: ['blog'],        // publish here revalidates pages
      appCollections: ['blog', 'media'],      // collections scoped per app/tenant
    }),
  ],
})
chaiBuilderPlugin option Description
menus show the Menus collection in the Payload admin navigation. The collection is always registered; default false
revalidateCollections collection slugs that back page types; their changes revalidate dependent pages - see Caching & Revalidation
appCollections collections that get the ChaiBuilder fields, the app field, and app-scoped access
appField name of the multi-app scoping field added to those collections. Default app
getAppId resolves the current app id. Defaults to the CHAIBUILDER_APP_KEY environment variable
mediaSlug slug of the media collection behind the builder's asset manager

Media on Payload is plugin-owned: register payloadMediaPlugin() in your ChaiBuilder plugins for the Payload-backed asset manager.

© ChaiBuilder. All rights reserved.

ChaiBuilderMade withChaiBuilder