@digiform/builder

React form builder for creating and managing configurable multi-step forms.

Installation

npm install @digiform/builder

Requires React 18+, XState 5+, TanStack Form 1+, TanStack Query 5+, Zod 3+, dnd-kit, and Radix UI components as peer dependencies. See peerDependencies in package.json for exact versions.

CSS Import

Required. The builder will not render correctly without the stylesheet.

import '@digiform/builder/styles';

Add this import once at your app entry point before rendering any builder component.

Quick Start

import { FormBuilderView } from '@digiform/builder';
import '@digiform/builder/styles';

export function MyBuilder() {
  return (
    <FormBuilderView
      projectId="my-project"
      formId="my-form"
      onSave={async (config) => {
        /* persist config to your storage */
      }}
    />
  );
}

Export Paths

| Import path | Contents | | ------------------------------ | -------------------------------------------------------------------------------- | | @digiform/builder | Main export — all components. Auto-selects client/server behavior as appropriate. | | @digiform/builder/client | Explicit client-side import. Use when your bundler requires a clear client boundary. | | @digiform/builder/server | Node.js storage providers (e.g., FilesystemStorageProvider). Node.js only. |

Server-Side Storage (Next.js)

Node.js only — import storage providers from @digiform/builder/server.

The builder ships a FilesystemStorageProvider that stores form configs as JSON files on disk. Use it in a Next.js App Router route handler to back the builder with real persistence.

// app/api/forms/[formId]/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { FilesystemStorageProvider } from '@digiform/builder/server';

const storage = new FilesystemStorageProvider({
  basePath: process.env.FORMS_DATA_PATH ?? './data/forms',
});

export async function GET(
  _req: NextRequest,
  { params }: { params: { formId: string } }
) {
  const config = await storage.load(params.formId);
  if (!config) {
    return NextResponse.json({ error: 'Form not found' }, { status: 404 });
  }
  return NextResponse.json(config);
}

export async function POST(
  req: NextRequest,
  { params }: { params: { formId: string } }
) {
  const config = await req.json();
  await storage.save(params.formId, config);
  return NextResponse.json({ ok: true });
}

Set the FORMS_DATA_PATH environment variable to the directory where form configs will be stored.

Framework Notes

Vite

1. Import styles in src/main.tsx:

   import '@digiform/builder/styles';

2. Render FormBuilderView directly — no 'use client' directive needed (Vite has no RSC boundary).

Next.js

1. Import styles in app/layout.tsx:

   import '@digiform/builder/styles';

2. Mark the page or component using FormBuilderView with the 'use client' directive:

   'use client';
   
   import { FormBuilderView } from '@digiform/builder';
   
   export default function BuilderPage() {
     return (
       <FormBuilderView
         projectId="my-project"
         formId="my-form"
         onSave={async (config) => {
           await fetch('/api/forms/my-form', {
             method: 'POST',
             body: JSON.stringify(config),
           });
         }}
       />
     );
   }

Related

Use @digiform/wizard to render the forms built with this package.