Workflow Builder with ReactFlow (XYFlow)

A visual workflow builder built with Next.js and ReactFlow that allows you to create, edit, and execute data processing workflows through an intuitive drag-and-drop interface.

📋 Table of Contents

Overview
Key Technologies
Getting Started
Project Structure
Core Concepts
Node Types
Edge Types
Drag & Drop Implementation
State Management
Workflow Execution
Important Implementation Details

🎯 Overview

This project is a visual workflow builder that demonstrates how to use ReactFlow (XYFlow) to create node-based workflows. Users can:

Drag nodes from a sidebar onto a canvas
Connect nodes to define data flow
Configure each node with specific parameters
Execute workflows and see real-time results
Save and load workflows from a database

What is ReactFlow/XYFlow?
ReactFlow is a library for building node-based editors and interactive diagrams. It provides:

Canvas with pan, zoom, and minimap
Custom node and edge rendering
Connection handling and validation
Built-in controls and utilities

🛠 Key Technologies

Technology	Purpose	Version
Next.js	React framework with App Router	16.x
ReactFlow (@xyflow/react)	Node-based canvas and workflow visualization	12.x
Zustand	Lightweight state management	5.x
Zod	Runtime schema validation	4.x
Tailwind CSS	Styling framework	4.x
Prisma	Database ORM	7.x
shadcn/ui	UI component library	Latest

🚀 Getting Started

Prerequisites

Node.js 18+ or Bun
PostgreSQL (for workflow persistence)

Installation

Clone and install dependencies:
```
bun install
# or npm install
```

Set up environment variables:

cp .env.example .env
# Edit .env with your database URL

Run database migrations:
```
bunx prisma migrate dev
```
Start the development server:
```
bun dev
# or npm run dev
```
Open http://localhost:3000

📁 Project Structure

src/
├── app/                          # Next.js App Router
│   ├── page.tsx                  # Main workflow builder page
│   └── api/workflows/            # API routes for workflow CRUD
├── components/
│   ├── ui/                       # shadcn UI components
│   └── workflow/                 # Workflow builder components
│       ├── index.tsx             # Main WorkflowBuilder component
│       ├── canvas.tsx            # ReactFlow canvas (drag/drop target)
│       ├── nodes.tsx             # Custom node components
│       ├── node-drawer.tsx       # Sidebar with draggable nodes
│       ├── node-editor.tsx       # Right panel for editing nodes
│       └── toolbar.tsx           # Top toolbar with actions
└── lib/
    └── workflow/
        ├── types.ts              # TypeScript types & Zod schemas
        ├── store.ts              # Zustand state management
        ├── executor.worker.ts    # Web Worker for execution
        ├── use-executor.ts       # Hook to run workflows
        └── sample-workflows.ts   # Pre-built example workflows

🧩 Core Concepts

ReactFlow Fundamentals

1. Nodes

Nodes are the building blocks of a workflow. Each node has:

id: Unique identifier
type: Determines appearance and behavior
position: { x, y } coordinates on canvas
data: Custom data specific to the node type

const node: WorkflowNode = {
  id: "node_1",
  type: "httpRequest",
  position: { x: 100, y: 200 },
  data: {
    nodeType: "httpRequest",
    label: "Fetch API",
    url: "https://api.example.com/data",
    method: "GET",
  },
};

2. Edges

Edges define connections between nodes (data flow). Each edge has:

source: ID of the starting node
target: ID of the destination node
sourceHandle: Which output on the source node
targetHandle: Which input on the target node
type: Visual style ("smoothstep", "step", "straight", "bezier")

const edge: WorkflowEdge = {
  id: "edge_1",
  source: "node_1",
  target: "node_2",
  sourceHandle: "output",
  targetHandle: "input",
  type: "step", // Right-angle connections
};

3. Node Types Registration

Custom node components must be registered with ReactFlow:

const nodeTypes = {
  start: StartNode,
  httpRequest: HttpRequestNode,
  transform: TransformNode,
  // ... other node types
};

<ReactFlow nodeTypes={nodeTypes} ... />

4. Handles

Handles are connection points on nodes:

Source handles: Where edges start (outputs)
Target handles: Where edges end (inputs)
Positioned using Position.Top/Right/Bottom/Left

<Handle
  type="source"
  position={Position.Right}
  id="output"
/>

🎨 Node Types

Node Type	Icon	Purpose	Key Properties
Start	▶️	Workflow entry point	`inputData` - Initial data
HTTP Request	🌐	API calls	`method`, `url`, `headers`, `body`
Transform	💻	Data transformation	`expression` - JavaScript code
Condition	🔀	Conditional branching	`condition` - Boolean expression
Delay	⏰	Pause execution	`duration` - Milliseconds
Output	📄	Display results	`format` - "json" or "text"
Merge	🔄	Combine multiple inputs	`strategy` - How to merge
Set Variable	📝	Store data	`variableName`, `value`

Node Handles Configuration

Start, HTTP, Transform, Delay, Output: 1 input (left), 1 output (right)
Condition: 1 input (left), 2 outputs (right) - "true" (green) and "false" (red)
Merge: Multiple inputs (left), 1 output (right)

🔗 Edge Types

ReactFlow supports multiple edge visual styles:

Type	Appearance	Use Case
smoothstep	Smooth curved lines	Default, clean look
step	Right-angle (90°) lines	Technical diagrams
straight	Direct lines	Simple connections
bezier	Classic curves	Similar to smoothstep

Change edge type in workflow definitions:

edges: [
  {
    id: "edge_1",
    source: "start",
    target: "http",
    type: "step", // Try: "smoothstep", "straight", "bezier"
  },
];

🖱 Drag & Drop Implementation

How It Works

The drag-and-drop system uses the HTML5 Drag & Drop API:

1. Making Nodes Draggable (node-drawer.tsx)

const handleDragStart = (event: DragEvent) => {
  // Store node type in dataTransfer
  event.dataTransfer.setData(
    "application/reactflow-nodetype",
    nodeType
  );
  event.dataTransfer.effectAllowed = "move";
};

<div draggable onDragStart={handleDragStart}>
  {/* Node tile */}
</div>

Key Point: "application/reactflow-nodetype" is a custom MIME type (just a string key) used to identify what's being dragged. It's NOT a TypeScript type or a pre-defined standard—you can use any unique string.

2. Drop Target Setup (canvas.tsx)

const handleDragOver = (event: DragEvent) => {
  event.preventDefault(); // Required to allow dropping
  event.dataTransfer.dropEffect = "move";
};

const handleDrop = (event: DragEvent) => {
  event.preventDefault();

  // Retrieve the node type
  const nodeType = event.dataTransfer.getData("application/reactflow-nodetype");

  // Convert screen position to flow position
  const position = screenToFlowPosition({
    x: event.clientX,
    y: event.clientY,
  });

  // Create new node
  addNode(nodeType, position);
};

3. Non-Modal Sheet for Drawer

Problem: By default, shadcn's Sheet component uses a modal overlay that blocks the canvas, preventing drops.

Solution: Use modal={false} and showOverlay={false}:

<Sheet modal={false}>
  <SheetContent showOverlay={false}>
    {/* Draggable nodes */}
  </SheetContent>
</Sheet>

This allows the drawer to stay open while you drag-and-drop onto the canvas!

🗂 State Management

Zustand Store (store.ts)

The workflow state is managed with Zustand, a simple and efficient state library:

Key State:

interface WorkflowState {
  // Workflow data
  nodes: WorkflowNode[];
  edges: WorkflowEdge[];
  workflowName: string;
  workflowDescription: string;

  // UI state
  isDrawerOpen: boolean;
  selectedNodeId: string | null;

  // Execution state
  executionStatus: ExecutionStatus;
  nodeResults: Map<string, NodeExecutionResult>;

  // Actions
  addNode: (nodeType, position) => void;
  updateNode: (nodeId, data) => void;
  deleteNode: (nodeId) => void;
  // ... more actions
}

Using the Store:

function MyComponent() {
  const nodes = useWorkflowStore((state) => state.nodes);
  const addNode = useWorkflowStore((state) => state.addNode);

  // Use state and actions...
}

ReactFlow Providers

ReactFlow requires two providers:

<ReactFlowProvider>
  <TooltipProvider>
    <WorkflowBuilder />
  </TooltipProvider>
</ReactFlowProvider>

ReactFlowProvider: Enables useReactFlow() hook
TooltipProvider: For shadcn tooltips (optional)

⚙️ Workflow Execution

Execution Flow

User clicks "Run" → Store dispatches executeWorkflow()
State transitions: idle → running
Web Worker spawned (keeps UI responsive)
Nodes executed in order (topological sort)
Results stored in nodeResults Map
UI updates in real-time as each node completes

Validation

Before execution, workflows are validated:

✅ Must have exactly one Start node
✅ All nodes must be reachable from Start
✅ No cycles (infinite loops)
✅ All required node properties filled

Node Data Access

During execution, each node receives data from its inputs:

// In a Transform node expression:
const result = data.email.toLowerCase();
// 'data' = output from previous node

For Condition nodes:

condition: "data.age >= 18";
// Evaluates to true or false → routes to correct output

💡 Important Implementation Details

1. ReactFlow Must Be Inside Providers

// ✅ Correct
<ReactFlowProvider>
  <MyComponent />  {/* Can use useReactFlow() */}
</ReactFlowProvider>

// ❌ Wrong - useReactFlow() will fail
<MyComponent />

2. Custom Node Components Receive Props

type CustomNodeProps = {
  id: string;
  data: YourNodeData;
  selected: boolean;
};

function CustomNode({ id, data, selected }: CustomNodeProps) {
  // Your node UI
}

3. Handle IDs Must Match

// Node 1 (source)
<Handle type="source" id="output" />

// Node 2 (target)
<Handle type="target" id="input" />

// Edge connecting them
{ sourceHandle: "output", targetHandle: "input" }

4. Position Conversion for Drops

Always convert screen coordinates to flow coordinates:

const position = screenToFlowPosition({
  x: event.clientX,
  y: event.clientY,
});

This accounts for canvas pan/zoom.

5. Zod for Runtime Validation

All node data is validated with Zod schemas:

const result = HttpRequestNodeDataSchema.safeParse(data);
if (!result.success) {
  console.error(result.error);
}

6. Immer for Immutable Updates

Zustand uses Immer middleware for clean state updates:

// Without Immer (complex)
set((state) => ({
  nodes: state.nodes.map((n) =>
    n.id === id ? { ...n, data: { ...n.data, ...newData } } : n,
  ),
}));

// With Immer (simple)
set((state) => {
  const node = state.nodes.find((n) => n.id === id);
  if (node) node.data = { ...node.data, ...newData };
});

📚 Learn More

ReactFlow Resources

Next.js Resources

🚢 Deployment

The easiest way to deploy is using Vercel:

vercel deploy

Make sure to:

Set up PostgreSQL database
Configure environment variables
Run migrations: bunx prisma migrate deploy

Built with ❤️ using ReactFlow, Next.js, and Zustand

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
prisma		prisma
public		public
src		src
.gitignore		.gitignore
README.md		README.md
bun.lock		bun.lock
components.json		components.json
diagram.excalidraw		diagram.excalidraw
eslint.config.mjs		eslint.config.mjs
globals.d.ts		globals.d.ts
next.config.ts		next.config.ts
package.json		package.json
postcss.config.mjs		postcss.config.mjs
prisma.config.ts		prisma.config.ts
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Workflow Builder with ReactFlow (XYFlow)

📋 Table of Contents

🎯 Overview

🛠 Key Technologies

🚀 Getting Started

Prerequisites

Installation

📁 Project Structure

🧩 Core Concepts

ReactFlow Fundamentals

1. Nodes

2. Edges

3. Node Types Registration

4. Handles

🎨 Node Types

Node Handles Configuration

🔗 Edge Types

🖱 Drag & Drop Implementation

How It Works

1. Making Nodes Draggable (node-drawer.tsx)

2. Drop Target Setup (canvas.tsx)

3. Non-Modal Sheet for Drawer

🗂 State Management

Zustand Store (store.ts)

ReactFlow Providers

⚙️ Workflow Execution

Execution Flow

Validation

Node Data Access

💡 Important Implementation Details

1. ReactFlow Must Be Inside Providers

2. Custom Node Components Receive Props

3. Handle IDs Must Match

4. Position Conversion for Drops

5. Zod for Runtime Validation

6. Immer for Immutable Updates

📚 Learn More

ReactFlow Resources

Next.js Resources

🚢 Deployment

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages