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.
Related
- Environment & License - the env var reference.
- API - the package entry points and server instance methods.
- Project Setup - how these files fit a fresh project.

