ChaiBuilder SDK

ChaiBuilder is a visual page builder SDK for React applications that provides several core capabilities:

• Visual Page Builder: A drag-and-drop interface for page construction.
• Custom Blocks: Ability to register your own custom block types.
• Theme System: Configurable themes including support for presets and dark mode.
• Extensibility: Support for adding custom panels, media managers, and libraries.
• Permissions: Fine-grained control over user permissions.
• i18n Support: Built-in internationalization capabilities.
• Undo/Redo: Full history management for builder actions.

Chai Builder is an open-source React-based website builder designed for visual drag-and-drop page creation. It is built using React and Tailwind CSS, offering seamless integration into existing web projects. It supports Next.js 16 and Tailwind CSS v3+ out-of-the-box.

Key capabilities include:

• Visual Drag & Drop: Create pages without writing code.
• Extensibility: Add custom blocks, components, and panels.
• Data Control: Full control over data persistence and binding.
• Flexible Modes: Can be used as a core builder component or as a complete Next.js website builder solution.

ChaiBuilder provides several registration APIs to extend the editor's functionality. You can add custom UI elements, modify asset management, integrate external libraries, and customize block settings.

Available registration APIs include:

• registerChaiSidebarPanel: Add custom sidebar panels.
• registerChaiMediaManager: Custom asset/media picker.
• registerChaiLibrary: External block libraries.
• registerChaiTopBar: Custom top toolbar.
• registerChaiSaveToLibrary: Save blocks to library UI.
• registerChaiAddBlockTab: Custom "Add Block" tabs.
• registerChaiFont: Register custom fonts.
• registerChaiPreImportHTMLHook: Pre-process imported HTML.
• registerBlockSettingWidget: Custom form widgets.
• registerBlockSettingField: Custom form fields.
• registerBlockSettingTemplate: Custom form templates.

ChaiBuilder is a front-end SDK for building visual website editors using React and Tailwind CSS. It provides the UI for visual page building, including block management, drag-and-drop editing, and styling controls.

Important Note: ChaiBuilder is a client-side SDK. It does not provide a backend. You are responsible for implementing storage (saving the JSON), authentication, and data persistence.

The AI Panel uses a context-based architecture to avoid prop drilling. When AiPanelContent is rendered, it initializes an AIConfigProvider which distributes the configuration to all sub-components (like ModelSelectorDropdown and AiPromptInput).

Event Lifecycle: When an AI request is initiated, events are triggered in this order:

1. stream_start: Fired when the AI stream begins.
2. completion: Fired when the AI successfully completes (the success path).
3. error: Fired if an error occurs (the error path).

Users can listen to these via specific callbacks (onSuccess, onError, onComplete) or a single unified handler (onAIEvent).

Design tokens are named collections of Tailwind CSS classes that act as reusable style definitions. Instead of applying individual utility classes to every block, you define a token once (e.g., a specific button style) and apply that token to any block. This ensures visual consistency and allows you to update styles globally by changing the token definition in a single place.

Example Token Mapping:

Blocks are the fundamental building units in ChaiBuilder. Every element on a page (containers, text, images, etc.) is represented as a block. Each block is a JSON object containing core properties that define its identity and position in the hierarchy.

{
  "_id": "abc123",
  "_type": "Box",
  "_parent": null,
  "_name": "Box",
  "styles": "#styles:,p-4 bg-white rounded-lg shadow"
}

The ChaiBuilder integration follows a four-step lifecycle:

1. Input: You provide an array of blocks in JSON format to the editor.
2. Edit: The user performs visual manipulations (drag & drop, styling) within the ChaiBuilder Editor component.
3. Output: When the user saves, the editor triggers an onSave callback containing the modified blocks JSON and theme data.
4. Render: You use the SDK's rendering APIs to display those blocks on your live website.

This architecture allows you to use any backend of your choice to persist the emitted JSON.

ChaiBuilder uses different components depending on whether you are in an editing context or a production environment:

• Editor Context: Use ChaiBuilderEditor for the full editing experience, including drag-and-drop, side panels, and state management.
• Production Context: Use RenderBlocks for a lightweight, render-only experience that excludes all editor UI and overhead.

The ChaiBlock is the fundamental building block of the ChaiBuilder SDK. It represents a single element (like a Box, Text, or Image) within the builder's tree structure. Every block must have a unique _id, a _type, and can optionally have a _parent ID to establish hierarchy.

type ChaiBlock<T = Record<string, any>> = {
  _id: string; // Unique identifier
  _type: string; // Block type (e.g., "Box", "Text", "Image")
  _name?: string; // Optional display name
  _parent?: string | null | undefined; // Parent block ID
  _libBlock?: string; // Library block reference
  partialBlockId?: string; // Partial block reference
} & T; // Additional block-specific properties

ChaiBuilder can be configured for different use cases via its props:

• Single-page mode: Best for landing pages, email templates, or simple single-page editors.
• Multi-page mode: Best for full-scale website builders that require page management.

The specific mode is determined by the props passed to the editor component.