Installation

If you are using shadcn/ui in your project, install the component directly from the registry:

bash
Copy code
1npx shadcn@latest add https://raw.githubusercontent.com/olliethedev/ui-builder/main/registry/block-registry.json

Or start a new Next.js project with UI Builder:

bash
Copy code
1npx shadcn@latest init https://raw.githubusercontent.com/olliethedev/ui-builder/main/registry/block-registry.json --base-color zinc

Optional: Add All Shadcn Components

Install the full shadcn component library with 54 pre-configured components and 124 block templates:

bash
Copy code
1npx shadcn@latest add https://raw.githubusercontent.com/olliethedev/ui-builder/main/registry/shadcn-components-registry.json

See Shadcn Registry for details on using these components and blocks.

Note: You need to use style variables to have page theming working correctly.

Handling Peer Dependencies

If you encounter peer dependency warnings during installation (common with React 19 projects), create a .npmrc file in your project root:

bash
Copy code
1echo "legacy-peer-deps=true" > .npmrc

Then re-run the installation command.

What Gets Installed

After running the installation command, these files are added to your project:

Auto-installed dependencies:

• zustand - State management
• sonner - Toast notifications
• @dnd-kit/* - Drag and drop functionality
• zod - Schema validation
• Various shadcn/ui components (button, card, tabs, etc.)

Basic Setup

Create a new page file and paste this complete example:

tsx
Copy code
1// app/builder/page.tsx - Complete working example
2"use client";
3
4import UIBuilder from "@/components/ui/ui-builder";
5import { primitiveComponentDefinitions } from "@/lib/ui-builder/registry/primitive-component-definitions";
6import { complexComponentDefinitions } from "@/lib/ui-builder/registry/complex-component-definitions";
7
8const componentRegistry = {
9  ...primitiveComponentDefinitions, // div, span, img, etc.
10  ...complexComponentDefinitions,   // Button, Badge, Card, etc.
11};
12
13export default function BuilderPage() {
14  return (
15    <main className="h-screen">
16      <UIBuilder componentRegistry={componentRegistry} />
17    </main>
18  );
19}

Then visit http://localhost:3000/builder to see your editor.

What's included:

• primitiveComponentDefinitions - HTML elements: div, span, h1-h3, p, ul, ol, li, img, iframe, a
• complexComponentDefinitions - React components: Button, Badge, Card, Icon, Flexbox, Grid, Markdown, Accordion, etc.

This gives you a full visual editor with pre-built shadcn/ui components.

Adding State Management

For real applications, you'll want to control the initial state and persist changes:

tsx
Copy code
1import UIBuilder from "@/components/ui/ui-builder";
2import { ComponentLayer, Variable } from "@/components/ui/ui-builder/types";
3
4// Initial page structure
5const initialLayers: ComponentLayer[] = [
6  {
7    id: "welcome-page",
8    type: "div",
9    name: "Welcome Page",
10    props: {
11      className: "p-8 min-h-screen flex flex-col gap-6",
12    },
13    children: [
14      {
15        id: "title",
16        type: "h1",
17        name: "Page Title",
18        props: { 
19          className: "text-4xl font-bold text-center",
20        },
21        children: "Welcome to UI Builder!",
22      },
23      {
24        id: "cta-button",
25        type: "Button",
26        name: "CTA Button",
27        props: {
28          variant: "default",
29          className: "mx-auto w-fit",
30        },
31        children: [{
32          id: "button-text",
33          type: "span",
34          name: "Button Text",
35          props: {},
36          children: "Get Started",
37        }],
38      },
39    ],
40  },
41];
42
43// Variables for dynamic content
44const initialVariables: Variable[] = [
45  {
46    id: "welcome-msg",
47    name: "welcomeMessage",
48    type: "string",
49    defaultValue: "Welcome to UI Builder!"
50  }
51];
52
53export function AppWithState() {
54  const handleLayersChange = (updatedLayers: ComponentLayer[]) => {
55    // Save to database, localStorage, etc.
56    console.log("Layers updated:", updatedLayers);
57  };
58
59  const handleVariablesChange = (updatedVariables: Variable[]) => {
60    // Save to database, localStorage, etc.
61    console.log("Variables updated:", updatedVariables);
62  };
63
64  return (
65    <UIBuilder
66      componentRegistry={componentRegistry}
67      initialLayers={initialLayers}
68      onChange={handleLayersChange}
69      initialVariables={initialVariables}
70      onVariablesChange={handleVariablesChange}
71    />
72  );
73}

TypeScript Types

All types are exported from @/components/ui/ui-builder/types:

tsx
Copy code
1import type {
2  // Core types
3  ComponentLayer,      // Page/layer structure
4  ComponentRegistry,   // Component definitions map
5  RegistryEntry,       // Single component definition
6  
7  // Variables & Binding
8  Variable,            // Variable definition
9  VariableReference,   // { __variableRef: string }
10  VariableValueType,   // 'string' | 'number' | 'boolean' | 'function'
11  DefaultVariableBinding, // Auto-binding configuration
12  
13  // Functions & Blocks
14  FunctionRegistry,    // Event handler functions
15  FunctionDefinition,  // Single function definition
16  BlockRegistry,       // Block templates
17  BlockDefinition,     // Single block definition
18  
19  // Handlers
20  LayerChangeHandler,  // onChange callback type
21  VariableChangeHandler, // onVariablesChange callback type
22  
23  // Field overrides
24  FieldConfigFunction, // Custom form field configuration
25  AutoFormInputComponentProps, // Props for custom field components
26} from "@/components/ui/ui-builder/types";
27
28// Helper functions
29import { 
30  isVariableReference, // Check if value is a variable reference
31  createVariable,      // Type-safe variable creation
32} from "@/components/ui/ui-builder/types";

Rendering Without the Editor

To display pages in production without the editor interface, use LayerRenderer (client) or ServerLayerRenderer (SSR/RSC):

tsx
Copy code
1import LayerRenderer from "@/components/ui/ui-builder/layer-renderer";
2
3// Basic rendering (client component)
4export function MyPage({ page }) {
5  return (
6    <LayerRenderer 
7      page={page}
8      componentRegistry={componentRegistry}
9    />
10  );
11}
12
13// With variables for dynamic content
14export function DynamicPage({ page, userData }) {
15  const variableValues = {
16    "welcome-msg": `Welcome back, ${userData.name}!`
17  };
18  
19  return (
20    <LayerRenderer 
21      page={page}
22      componentRegistry={componentRegistry}
23      variables={variables}
24      variableValues={variableValues}
25    />
26  );
27}

Server-Side Rendering (SSR/RSC)

For React Server Components or SSG, use ServerLayerRenderer:

tsx
Copy code
1import { ServerLayerRenderer } from "@/components/ui/ui-builder/server-layer-renderer";
2
3// Server Component (no 'use client' needed)
4export default async function MyPage() {
5  const page = await fetchPageFromDB();
6  return (
7    <ServerLayerRenderer 
8      page={page}
9      componentRegistry={componentRegistry}
10    />
11  );
12}

🎯 Try it: Check out the Renderer Demo, Variables Demo, and SSR Demo to see the renderers in action.

Troubleshooting

"Module not found" Errors

Problem: Import errors like Cannot find module '@/components/ui/ui-builder'

Solutions:

1. Verify the shadcn CLI completed successfully (check for error messages)
2. Ensure components.json exists in your project root
3. Check that @/ alias is configured in tsconfig.json
4. Try running the installation command again

Styling Issues

Problem: Components look unstyled or broken

Solutions:

1. Ensure Tailwind CSS is configured with CSS variables
2. Check that globals.css includes the shadcn theme variables
3. Verify tailwind.config.js includes the UI Builder paths:

js
Copy code
1content: [
2  './components/**/*.{js,ts,jsx,tsx}',
3  './lib/**/*.{js,ts,jsx,tsx}',
4]

Component Not Rendering

Problem: Added component doesn't appear or shows error

Solutions:

1. Verify the component type exists in your componentRegistry
2. Check browser console for specific error messages
3. Ensure all parent component types referenced in defaultChildren are in the registry

TypeScript Errors

Problem: Type errors when using UI Builder components

Solutions:

1. Import types from @/components/ui/ui-builder/types
2. Use ComponentRegistry type for your registry object
3. Use ComponentLayer[] for initial layers

React 19 Peer Dependency Warnings

Problem: npm warns about peer dependency conflicts

Solution: Create .npmrc with legacy-peer-deps=true (see Installation section)