@bdmakers/visual-builder

Build React component trees visually. Bring your own components and design tokens — export real JSX you can ship.

A headless visual builder for React component trees. Drag, drop, and export production-ready JSX & Storybook stories. Plug in your own design system.

⚠️ Pre-alpha (v0.1.0). First public preview. API surfaces may change between minor versions until 1.0 — pin to an exact version and check CHANGELOG on upgrades. See Roadmap for status.

Why

Most visual builders ship with their own component library, baked-in tokens, or hosted backend. That's great if you're starting from zero, but it doesn't fit teams who already have a design system and want a builder that renders their components.

@bdmakers/visual-builder is the opposite: it's headless and bring-your-own-everything. You supply the component catalog, the design tokens, and the storage layer. The library handles the canvas, the property panel, the drag-drop, the undo history, and the JSX export.

It's the visual builder that produces code your team can actually read and merge.

Features (planned)

• Headless React — composable <VisualBuilderProvider> + panel components (<Canvas />, <Palette />, <PropertiesPanel />, <Layers />, <CodePanel />).
• Bring your own design system — register your components with a typed ComponentRegistry.
• Bring your own tokens — optional TokenRegistry for spacing / typography / color / custom groups.
• Bring your own storage — StorageAdapter interface. Built-in adapters: memory, S3 (Cognito Unauth).
• Real JSX export — generateFullSource, generateStorybookStorySource produce readable, importable code.
• React Native Web friendly — the core has no DOM-only assumptions.
• Undo/redo, drag-reorder, spacing handles, resize handles, palette drop, tree reorder — all included.
• TypeScript-first, ESM + CJS dual build, sub-entry imports for tree-shaking.

Install

npm install @bdmakers/visual-builder react
# or
pnpm add @bdmakers/visual-builder react
# or
yarn add @bdmakers/visual-builder react

S3 storage is optional. Install AWS SDK only if you use storage-s3:

npm install @aws-sdk/client-s3 @aws-sdk/credential-provider-cognito-identity

Quick start

import {
  VisualBuilderProvider,
  Canvas,
  Palette,
  PropertiesPanel,
} from "@bdmakers/visual-builder/react";
import { createMemoryStorage } from "@bdmakers/visual-builder/storage-memory";
import type { ComponentRegistry } from "@bdmakers/visual-builder/core";

import { Button } from "./components/Button";

const components: ComponentRegistry = {
  defs: [
    {
      type: "Button",
      label: "Button",
      category: "Inputs",
      icon: "□",
      acceptsChildren: false,
      hasTextContent: true,
      defaultProps: { variant: "primary" },
      defaultTextContent: "Click me",
      propDefs: [
        {
          key: "variant",
          label: "Variant",
          type: "select",
          options: [
            { value: "primary", label: "Primary" },
            { value: "ghost", label: "Ghost" },
          ],
          defaultValue: "primary",
        },
      ],
    },
  ],
  resolve: (type) => ({ Button })[type],
  imports: {
    Button: { path: "./components/Button", isDefault: false },
  },
  noOnPressTypes: new Set(),
};

export default function App() {
  return (
    <VisualBuilderProvider
      components={components}
      storage={createMemoryStorage()}
    >
      <div style={{ display: "grid", gridTemplateColumns: "240px 1fr 320px", height: "100vh" }}>
        <Palette />
        <Canvas />
        <PropertiesPanel />
      </div>
    </VisualBuilderProvider>
  );
}

Use with S3 storage

import { createS3Storage } from "@bdmakers/visual-builder/storage-s3";

// Option A — env auto-fallback
//   VISUAL_BUILDER_S3_BUCKET, _REGION, _COGNITO_POOL_ID, _S3_PUBLIC_BASE_URL
const storage = createS3Storage();

// Option B — explicit options (recommended for libraries)
const storage = createS3Storage({
  bucket: "my-bucket",
  region: "us-east-1",
  identityPoolId: "us-east-1:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  publicBaseUrl: "https://my-bucket.s3.amazonaws.com",
});

Runnable end-to-end demo: examples/with-s3-storage — same builder UI as minimal-react, swapped storage adapter, plus the Cognito Identity Pool + IAM policy snippets needed for browser-side client credentials.

Exporting code

The builder produces real JSX you can drop into your codebase:

<VisualBuilderProvider
  components={components}
  storage={storage}
  onExport={({ jsx, fullSource, storySource }) => {
    // jsx:         <Button variant="primary">Click</Button>
    // fullSource:  import lines + functional component + default export
    // storySource: Storybook .stories.tsx with optional decorators
    navigator.clipboard.writeText(fullSource);
  }}
>
  {/* ... */}
</VisualBuilderProvider>

Package layout

Single npm package with multiple sub-entries. Import only what you need:

| Sub-entry | What's inside | Peer deps | |---|---|---| | @bdmakers/visual-builder/core | Types, algorithms, codeGenerator (React-free) | — | | @bdmakers/visual-builder/react | Provider, panels, hooks, renderer | react | | @bdmakers/visual-builder/storage-s3 | S3 + Cognito storage adapter | @aws-sdk/client-s3, @aws-sdk/credential-provider-cognito-identity (optional) | | @bdmakers/visual-builder/storage-memory | In-memory / localStorage adapters | — |

The root @bdmakers/visual-builder re-exports everything except storage-s3 (to keep AWS SDK out of bundles that don't need it).

How does it compare?

| | This | Craft.js | GrapesJS | Builder.io | |---|---|---|---|---| | Headless | ✅ | ✅ | ❌ | ❌ (hosted) | | BYO components | ✅ | ✅ | partial | ✅ | | React-native-web friendly | ✅ | ❌ | ❌ | ❌ | | JSX code export | ✅ | ❌ (own format) | HTML/CSS | ❌ | | Storybook story export | ✅ | ❌ | ❌ | ❌ | | Self-hosted | ✅ | ✅ | ✅ | ❌ | | MIT | ✅ | MIT | MIT (with paid tiers) | proprietary |

The niche this fills: a React/RN-Web component-tree visual builder that produces real, readable JSX and Storybook stories — fully self-hosted, design-system-agnostic.

Roadmap

• 0.1 (current) — core + react + storage-memory + storage-s3, minimal-react + with-s3-storage examples, 101 tests.
• 0.2 — CLI scanner (npx @bdmakers/visual-builder scan) to auto-generate ComponentRegistry from a directory of components via react-docgen-typescript.
• 0.3 — Storybook integration (autoRegisterFromStorybook to pick up existing stories' argTypes).
• 0.4 — @bdmakers/visual-builder/react-native for true RN target (not just RN-Web).
• 1.0 — API contracts frozen, semver enforced.

Status

Pre-alpha. The library is in active extraction from a production codebase. With 0.1 shipped:

• ✅ all four sub-entries land runtime code (no more placeholders),
• ✅ examples/minimal-react + examples/with-s3-storage work end-to-end,
• ✅ 101 unit tests cover the core algorithms, storage adapters, and the React state/renderer surface,
• ⚠ breaking changes are still expected between minor versions until 1.0.

See CHANGELOG.md for what landed in each release.

Development

git clone https://github.com/bd-makers/visual-builder.git
cd visual-builder
npm install
npm run typecheck
npm run build
npm test

Contributing

Issues and PRs welcome once 0.1 ships. Until then the code is being moved over from upstream — open an issue if you want to discuss API shape early.

License

MIT © 2026 bd-makers.

Developed and maintained by Logan ([email protected], GitHub).