Live Demo | Documentation | npm | Website

Workflow Builder

Apache 2.0 React SDK for embedding visual workflow editors.

Drag-and-drop workflow builder UI with a reference back-end and an execution engine swappable by design, proven with Temporal. Back-end agnostic. Built on React Flow and Temporal. Reference stack for AI workflows and automations in digital products.

Try it live ->

Used in production by teams including Vercom, Athena Intelligence, Plura AI, and others.

🎉 Workflow Builder 2.0 is here.

A best-in-class SDK for embedding workflow editors, now paired with a dedicated reference backend and a fully modular plugin surface. Building products on top of a workflow editor has never been easier.

Starting with 2.0, this repository is the home of Workflow Builder. Previously we worked in a private monorepo and only partially mirrored changes here. From now on, every commit lands here directly.

See the CHANGELOG for everything that's changed since the last release.

Get started

Three onboarding paths. Pick one based on what you want to evaluate.

Goal	Path	Setup time	Docker
Use the SDK inside your own React app	A. Embed the SDK	~1 min	no
See the editor running in your browser	B. Try the demo	~2 min	no
Run the full reference stack (editor + execution + AI)	C. Run the full stack demo	~10 min	yes

Don't want to install or clone anything yet? Try the live demo in your browser, or open the runnable starter below:

Path A. Embed the SDK

Use Workflow Builder inside your own React app. No clone, no Docker. Install the SDK and its peer dependencies from npm:

npm install @workflowbuilder/sdk @xyflow/react zustand

Requires React 18 or 19.

Render the editor:

import { WorkflowBuilder } from '@workflowbuilder/sdk';

import '@workflowbuilder/sdk/style.css';

export function App() {
  return <WorkflowBuilder.Root name="my-workflow" />;
}

It mounts the default layout (top bar, palette, canvas, properties panel) and persists to localStorage out of the box. The palette is empty until you pass nodeTypes.

Full guide (props, persistence strategies, theming, plugins, and the API reference): React Component on the docs site.

The two paths below run this repository locally (demo and full stack). They share the requirements and preflight check that follow. Path A needs neither.

Requirements

Node 22.12.0 and pnpm 10.9.0. Both pinned in package.json. Use nvm, fnm, or corepack to match.
Docker Desktop. Only required for Path C.

Works the same on macOS, Linux, and Windows. No platform-specific steps.

Preflight check

Run this once after cloning. It verifies Node, pnpm, Docker, port availability, and required .env files.

pnpm install
pnpm preflight

Expected output:

Workflow Builder preflight

✅ node                        22.12.0
✅ pnpm                        10.9.0
✅ docker                      running
✅ port_3001                   free (backend)
✅ port_4200                   free (demo)
✅ port_4201                   free (ai-studio)
✅ port_5432                   free (postgres)
✅ port_5433                   free (temporal-db)
✅ port_7233                   free (temporal)
✅ port_8233                   free (temporal-ui)
⚠️  apps/backend/.env           missing — copy from apps/backend/.env.example
⚠️  apps/execution-worker/.env  missing — copy from apps/execution-worker/.env.example

Ready to go. Pick a path in README.md "Get started".

The two .env warnings are expected on a fresh clone. They are only required for Path C and get created by pnpm setup:env in step 1 of that path. After that they switch to ✅ present.

Fix any red (❌) items before continuing. The script also has a --json mode for tooling: pnpm preflight --json.

Path B. Try the demo

UI only. No backend, no Docker. The fastest way to see the editor in action.

pnpm dev:demo

Expected output:

[1]   VITE vX.Y.Z  ready in NNN ms
[1]
[1]   ➜  Local:   http://localhost:4200/
[0] Found 0 errors. Watching for file changes.

Open http://localhost:4200. The editor loads with the default plugin set and a starter template. That's it.

Path C. Run the full stack demo

Full reference product: editor, Hono backend, Temporal worker, Postgres. The frontend on port 4201 is the AI Studio reference product (apps/ai-studio). Demonstrates end-to-end workflow execution.

1. Create .env files. First time only. Copies the .env.example templates into place; existing .env files are left untouched.

pnpm setup:env

2. Start infrastructure.

pnpm infra:up

Expected output (first run):

 Network backend_default            Created
 Volume "backend_temporal-db-data"  Created
 Volume "backend_app-db-data"       Created
 Container backend-app-db-1         Started
 Container backend-temporal-db-1    Started
 Container backend-temporal-1       Started
 Container backend-temporal-ui-1    Started

Verify: open http://localhost:8233 (Temporal UI). The default namespace appears.

3. Run migrations. First time, or after pulling schema changes.

pnpm -F backend db:migrate

Expected output:

> drizzle-kit migrate

Using 'postgres' driver for database querying
[✓] migrations applied successfully!

4. Start the stack.

pnpm dev:ai-studio

Expected output (three interleaved streams):

Temporal ready
[backend]    Backend running on http://127.0.0.1:3001
[worker]     Execution worker started on task queue: workflow-execution
[ai-studio]    VITE vX.Y.Z  ready in NNN ms
[ai-studio]    ➜  Local:   http://127.0.0.1:4201/

Open http://localhost:4201. Pick the "Sales Inquiry" template, click Play. The Temporal UI at http://localhost:8233 shows the running execution.

To stop: Ctrl+C, then pnpm infra:down.

Connect a real LLM (optional)

AI Studio works with stub responses out of the box. To use a real model, add to both apps/backend/.env and apps/execution-worker/.env:

OPENROUTER_API_KEY=sk-or-v1-...
AI_MODEL=anthropic/claude-3.5-haiku

If the key is missing the worker fails to start with OPENROUTER_API_KEY is required. If the model id is wrong the first AI node fails at runtime and the error surfaces in the UI log panel.

Troubleshooting

Symptom	Cause	Fix
`EADDRINUSE` on 3001, 4200, 4201, 5432, 5433, 7233, or 8233	Another process holds the port	`pnpm preflight` shows the conflict. Stop the other process or change the port
Temporal UI loads but the `default` namespace is missing	Migrations not run	`pnpm -F backend db:migrate`
Worker exits with `OPENROUTER_API_KEY is required`	Real LLM env var missing	Set it in `apps/execution-worker/.env`. Optional unless you want a real LLM call
`pnpm dev:demo` shows TypeScript errors but the dev server still starts	`concurrently` runs typecheck alongside Vite. TS errors are non-fatal	Fix the errors or ignore them temporarily
Vite acts up after a dependency change	Stale `node_modules/.vite`	`rm -rf node_modules/.vite` and rerun

For the full command reference, see the table in CLAUDE.md or the documentation site.

Key Features

Plugin-first architecture - optional features can be added or removed without breaking the app
Schema-driven properties panels - configure node inputs declaratively
JSON-serializable workflows - plug into any backend; execution stays yours
Design System Kit - theming and white-label support out of the box
Configurable and extensible node system
Visual workflow editor (nodes, edges, layout, validation)

Plugins

Workflow Builder uses a plugin-first architecture. Plugins are optional features that can be added or removed without breaking the app. For details on how the plugin system works, see the plugins guide.

Plugin	Description
Avoid Nodes Edges	Orthogonal edge routing using Web Workers and WASM
Copy Paste	Cut, copy, and paste operations for nodes and edges
Download PDF	Export diagrams to PDF
ELK Layout	Automatic node and edge arrangement using the ELK layout engine
Flow Runner	Example JSON parser that converts workflow diagrams into callable flow functions
Reshapable Edges	Manual reshaping of orthogonal edges using drag handles
Undo Redo	Local session history for undo/redo operations
Widgets	Optional node widgets displayed directly on the diagram

Typical Use Cases

Workflow Builder is commonly used to:

embed workflow editors into B2B SaaS products
build visual rule engines and configuration tools
design AI agent and automation workflow platforms
serve as a foundation for workflow-driven products and standalone apps

Repository Structure

Monorepo of Workflow Builder - a frontend-first SDK and foundation for building workflow-driven applications.

Using pnpm workspaces, Workflow Builder is split into runnable apps under apps/ and reusable libraries under packages/:

packages/sdk - @workflowbuilder/sdk, the embeddable React library (public API, types, build)
packages/types - @workflow-builder/types, shared TypeScript types used by the SDK and the bundled backend/worker
packages/execution-core - Pure domain layer (ports, graph runner, node executors) shared by the bundled backend and worker
apps/demo - Reference SPA that consumes the SDK with the full plugin set (also the source of truth for example node types, templates, and plugins)
apps/docs - Documentation site
apps/icons - Lazy-loadable, extensible icons consumed by the SDK

The repo also ships an example AI workflow execution backend used by the AI Studio plugin. This is not part of the frontend SDK — it is a reference implementation showing one way to pair the editor with an execution engine:

backend - Hono HTTP server, workflow CRUD, SSE streaming; hexagonal — depends on WorkflowEnginePort
execution-worker - Temporal worker executing workflow activities

Technical choices are documented in *.decision-log.md files that live alongside the code they relate to. See the decision logs list.

⚠️ Reference Backend — Local Development Only

The bundled execution backend (apps/backend, apps/execution-worker) is a reference implementation of the AI Studio plugin's execution layer. It has no authentication, no authorization, no user/tenant isolation, and no CORS restrictions. By default it binds only to 127.0.0.1 and the docker-compose stack does the same — nothing in the reference setup is reachable from the local network.

Do not expose this backend to the internet, a shared LAN, or any environment with untrusted users without first adding proper authn/authz. Anyone who can reach the port can read, modify, and execute every workflow.

For production deployments, see Workflow Builder Enterprise or build your own backend against WorkflowEnginePort.

License

Workflow Builder is available in two editions:

Community Edition - Open source, Apache 2.0 licensed, this repository
Enterprise Edition - Commercial license with long-term support, advanced features, and professional services. Learn more at workflowbuilder.io

Support

For companies that need end-to-end implementations or any other support, we offer professional consulting services.

Our team has delivered 200+ custom workflow tools across 20+ industries and brings 15+ years of experience building enterprise-class diagramming and automation tools. We can help with:

backend execution engines
custom integrations
enterprise-grade customization and scaling
accelerating time-to-market with proven architecture patterns

Talk to the team →