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 optional linkComponent, imageComponent, buttonComponent overrides.
  • 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 _layout page 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.

© ChaiBuilder. All rights reserved.

ChaiBuilderMade withChaiBuilder