API
The Pro SDK ships as chaipro with purpose-specific entry points. The rule
that keeps imports correct: client APIs come from the root and /registry; server APIs
come from /nextjs/server, /nextjs/render, /payload, and /db/*. Importing the root
package in a server context throws by design.
Entry points
| Entry point | Side | Purpose |
|---|---|---|
chaipro |
client | Builder component + UI extension APIs (panels, slots, hooks, flags) |
chaipro/registry |
client | Block registration - registerChaiBlock, props schemas, fonts |
chaipro/web-blocks |
client | loadWebBlocks() - the built-in block library |
chaipro/types |
shared | All public types |
chaipro/utils |
shared | HTML-to-blocks conversion, binding analysis, design token helpers |
chaipro/styles |
client | The builder's CSS |
chaipro/nextjs |
server | withChaiBuilder next.config wrapper |
chaipro/nextjs/server |
server | Config, context, actions, permissions, MCP tool authoring |
chaipro/nextjs/render |
server | ChaiBlocksRenderer, ChaiPageCss, styles utilities |
chaipro/nextjs/render-client |
client | ChaiPreviewBanner |
chaipro/mcp |
server | createChaiMcpRouteHandlers - the MCP transport. Needs the @modelcontextprotocol/sdk peer |
chaipro/tailwind |
server | The runtime page-CSS compiler |
chaipro/ai/openrouter, chaipro/ai/openai-compatible |
server | AI provider plugins, see AI Setup |
chaipro/db/* |
server | Database adapter factories (postgres, node-pg, libsql, d1, better-sqlite3) |
chaipro/db/schema, /db/schema-pg, /db/schema-sqlite, /db/relations, /db/relations-pg, /db/relations-sqlite |
server | Drizzle schema and relations for your migrations. /db/schema and /db/schema-pg are the same Postgres schema |
chaipro/db/schema-factory |
server | Build the schema with custom table and column names |
chaipro/payload |
server | Payload integration - plugin, schema hook, createChaiPayloadBuilder, payloadMediaPlugin |
chaipro/plugins/server |
server | Every server plugin plus the chaiProServerPlugins() preset |
chaipro/plugins/client |
client | Every client plugin. There is no client preset: name the ones you want |
chaipro/plugins/<name>/server and /client |
per plugin | One plugin at a time, see Built-in Plugins |
chaipro/plugins/animation/render |
client | ChaiAnimationProvider, for pages that use block animations |
chaipro/ui/* |
client | shadcn-based UI primitives for custom panels |
Naming convention
From v0.5.2 every public export follows one convention: the Chai prefix on hooks,
components, functions and types (useChaiActivePage, ChaiPageCss), acronyms written as words
(Css, Html, JsonLd, Db), and one verb per meaning (register* adds to a registry,
get* reads, run* executes). Older names, such as RenderChaiBlocks, ChaiPageCSS,
useFetch, dispatchChaiAction and createPayloadChaiBuilder, are still exported from the
same import paths and marked deprecated, so existing code keeps working and your editor
shows the replacement. Nothing was removed. The full list is in
chaipro v0.5.2.
Client: extending the builder
All registration APIs are client-only and must run at module level before the builder mounts - centralize them in one setup file. The main families:
| API | What it does |
|---|---|
registerChaiBlock(component, config) |
add a custom block (from /registry) |
registerChaiBlockProps(schema) |
define a block's editable props schema |
groupProps({ label, properties, defaultOpen }) |
collect props into a collapsible settings section, see Grouping props |
chaiSlot({ title, accept }) |
declare a named content area on a block (from /registry), see Named slots |
stylesProp(classes), builderProp(schema), defaultChaiStyles(classes) |
props schema helpers (from /registry), see Custom Blocks |
getRegisteredChaiBlock(type), getRegisteredChaiBlocks(), useRegisteredChaiBlocks() |
read the block registry from custom UI (from /registry) |
registerChaiSidebarPanel(id, options) |
add a sidebar panel |
registerChaiSlot(CHAI_SLOT_IDS.X, Component) |
inject UI into a named slot |
registerChaiHook(CHAI_HOOKS.X, fn) |
intercept lifecycle events (before/after save) |
registerChaiFeatureFlag(key, options) |
user-toggleable flags |
registerChaiLibrary(id, options) |
add a browsable block library |
registerChaiAddBlockTab(id, options) |
add a tab to the Add Block drawer |
registerChaiBlockSettingWidget / Field / Template |
custom controls for the block settings form |
registerChaiMediaManagerTab(id, tab) |
add a tab to the media manager |
registerChaiSaveToLibrary(Component) |
replace the Save to Library dialog |
registerChaiPreImportHtmlHook(fn) |
transform HTML before Import HTML converts it |
registerChaiStructureCheckRule(rule) |
add a structure validation rule |
registerChaiFetchInterceptor(name, interceptor) |
add headers to, or observe, every builder action request |
registerChaiPipe(definition) |
add a data binding pipe (from /registry), see Pipes |
registerChaiFont(family, font) |
register a self-hosted font (from /registry), see Custom Fonts |
Components exported for custom UI: ChaiWebsiteBuilder, ChaiImagePicker, ChaiAiPanel,
ChaiLanguageSwitcher, IfChaiPermission, and ChaiJsonInput.
Hooks for reading builder state from custom UI include useChaiAuth,
useChaiUserPermissions, useChaiActivePage, useChaiSavePage, useChaiFeatureFlag,
useChaiPrimaryPages, useChaiSiteSettings, useChaiPageTypes, useChaiSiteGlobalData, and
useChaiActionFetch. With the realtime plugin, useChaiPageLockStatus and useChaiPageLockOwner
report who holds the page; without it they read as unlocked. Full walkthroughs: Extending the UI
and Custom Blocks.
Server: the request-scoped instance
getChaiBuilder (exported from your chaibuilder.server.ts, see
Configuration) returns a request-scoped instance with all
server APIs bound to the caller's context:
const cb = await getChaiBuilder(props) // pages/layouts
const cb = await getChaiBuilder(props, request) // route handlers
| Method | Returns |
|---|---|
cb.getPagePayload(slug) |
full render payload - { page, pageData, settings, pageProps } |
cb.generateMetaData(...) |
a Next.js Metadata object for the page |
cb.getPageData(slug) |
resolved data-provider output for a page |
cb.getSiteSettings() |
site-wide settings |
cb.getSiteGlobalData() |
output of your globalDataProvider |
cb.getPages() |
all pages |
cb.getPageStyles(...), cb.getBlocksStyles(...) |
compiled CSS for a page or a block list |
cb.resolveLink(...), cb.resolveLinksInBlocks(...) |
turn page links into URLs |
cb.runAction(name, input) |
run any registered action in-process; throws on error |
cb.tryAction(name, input) |
the same, returning a result object instead of throwing |
cb.handleHttpAction(body) |
dispatch a builder action from a route handler |
cb.safeQuery(fn) |
run your own Drizzle query against the configured database |
cb.getChaiCollections(), cb.getPageTypes() |
the configured data sources and page types |
cb.config, cb.context |
the resolved config and this request's context, read-only |
Page, asset, library, trash, and revision operations are on the instance too
(createPage, updatePage, getAssets, getLibraryItems, getTrashedItems,
getPageRevisions, ...). Plugin features add namespaces, for example cb.roles.* with the
roles plugin and cb.formSubmissions.* with the form submissions plugin. A namespace whose
plugin is not registered throws when called.
The instance is request-scoped - never cache it or share it across requests.
The action endpoint
All client-to-server builder communication goes through one route, which the starter already includes:
// app/(builder)/api/chai/route.ts
import { getChaiBuilder } from '@/chaibuilder.server'
import { handleChaiActionRequest, type ChaiBuilderRouteProps } from 'chaipro/nextjs/server'
import type { NextRequest } from 'next/server'
export async function POST(request: NextRequest, props: ChaiBuilderRouteProps) {
const cb = await getChaiBuilder(props, request)
return handleChaiActionRequest(request, cb.handleHttpAction)
}
handleChaiActionRequest reads the body for you. Ordinary actions arrive as JSON; actions
that carry a file, such as an image upload, arrive as multipart form data, which a route
that only calls request.json() cannot read. If your route predates this helper, switch to
it so uploads keep working. A malformed body gets a 400 with an error payload rather than
an unhandled exception.
The JSON body is { action: "ACTION_NAME", data: {...} }. Authentication comes from the Payload
auth cookie (builder UI) or an Authorization: Bearer header (programmatic calls), and
each action enforces its required permission before executing. After an action runs, any
cache tags and paths it reports are revalidated automatically - see
Caching & Revalidation.
Custom actions
Add your own actions by extending ChaiBaseAction:
import { ChaiBaseAction } from 'chaipro/nextjs/server'
import { z } from 'zod'
export class GetInventoryAction extends ChaiBaseAction {
protected getValidationSchema() {
return z.object({ productId: z.string() })
}
async execute(data: { productId: string }) {
const { appId, userId } = this.context! // set before execute()
return fetchInventory(appId, data.productId)
}
}
Register it in chaibuilder.config.ts under actions: { GET_INVENTORY: new GetInventoryAction() }, then call it from the builder UI through the action endpoint, or
server-side with runChaiAction("GET_INVENTORY", data) (throws on error) or
tryChaiAction(...) (returns { ok, data | error }).
Rendering
Server components for rendering published pages, from /nextjs/render:
ChaiBlocksRenderer- renders a page payload; accepts optionallinkComponent,imageComponent,buttonComponentoverrides.ChaiPageCss- page CSS (Tailwind output, theme variables, fonts); must be in<head>.ChaiPageJsonLd- structured data for SEO.ChaiSiteTheme- the site theme's CSS variables, for layouts that render outside a page.ChaiCustomHtml,ChaiPageScripts- the custom HTML and scripts set in page and site settings.ChaiLayout- wraps a custom route in a_layoutpage from the builder (needs the layout plugin).getChaiBlocksStyles,getChaiThemeCssVariables,getChaiThemeFontsCssImport,getChaiThemeFontsLinkMarkup,getChaiMergedPartialBlocks- lower-level utilities for custom render pipelines.
From /nextjs/render-client, ChaiPreviewBanner shows the draft-mode banner. Pages using
block animations also need ChaiAnimationProvider from chaipro/plugins/animation/render.
Permissions
The permission catalog is CHAI_PERMISSIONS (core keys) plus keys registered by active
plugins - getChaiPermissionCatalog() returns the runtime set. Check access in custom code
with hasChaiPermission, and resolve a user's effective set with resolveChaiPermissions.
Effective permissions are the user's grants intersected with any credential-level
delegatedPermissions ceiling. See
Roles & Permissions.
Related
- Configuration - the config files these APIs plug into.
- Custom Blocks - the block registration API in depth.
- Extending the UI - panels, slots, and hooks in depth.

