React Workflow Editor

A React-based workflow editor compatible with n8n, built using ReactFlow and modern React patterns.

🎯 Features

• ✅ n8n Compatible: Uses n8n's workflow format and can integrate with n8n's node ecosystem
• ✅ React Context Architecture: Hierarchical state management mirroring n8n's design patterns
• ✅ ReactFlow Integration: Modern canvas with zoom, pan, minimap, and controls
• ✅ Dynamic Parameter Forms: Auto-generated forms using react-hook-form + zod validation
• ✅ TypeScript Support: Full type safety with n8n interfaces
• ✅ Tailwind CSS: Utility-first styling with responsive design
• ✅ Sample Nodes: Manual Trigger and Set nodes for demonstration

🏗️ Architecture

Context Hierarchy

WorkflowProvider    # Main workflow state and n8n data management
    ↓
ReactFlowProvider   # ReactFlow functionality
    ↓  
NodeProvider        # Individual node state and operations
    ↓
UI Components       # Parameter panels, node components, etc.

Key Components

• WorkflowCanvas: Main ReactFlow canvas with n8n node integration
• N8nNode: Custom ReactFlow node component that renders n8n nodes
• ParameterPanel: Dynamic form panel for node configuration
• NodeProvider: Individual node state management (critical for n8n compatibility)

Data Flow

• n8n workflow format ↔ ReactFlow format conversion
• Real-time parameter updates with debouncing
• Event-driven architecture with React callback patterns

🚀 Quick Start

Prerequisites

• Node.js >= 18.0.0
• pnpm >= 8.0.0 (or npm/yarn)

Installation

# Clone the repository
git clone https://github.com/koolii/react-workflow-editor.git
cd react-workflow-editor

# Install dependencies
pnpm install

# Start development server
pnpm dev

Build for Production

pnpm build

Type Checking

pnpm typecheck

Linting

pnpm lint
pnpm lint:fix

💡 Usage

The application includes a sample workflow with Manual Trigger and Set nodes. You can:

• Execute workflows using the Execute button
• Add new nodes via context menu (right-click) or toolbar
• Configure node parameters by selecting/double-clicking nodes
• Save/load workflow JSON files using the toolbar buttons
• Real-time parameter editing with automatic validation

Basic Example

import { WorkflowProvider, WorkflowCanvas } from 'react-workflow-editor';

const App = () => {
  const initialWorkflow = {
    id: 'sample-workflow',
    name: 'My Workflow',
    nodes: [
      {
        id: 'trigger',
        name: 'Manual Trigger',
        type: 'manualTrigger',
        position: [100, 200],
        parameters: {}
      }
    ],
    connections: {}
  };

  return (
    <WorkflowProvider initialWorkflow={initialWorkflow}>
      <div className="h-screen">
        <WorkflowCanvas />
      </div>
    </WorkflowProvider>
  );
};

🔧 Extending with Custom Nodes

To add new node types:

1. Create node definition in src/nodeTypes/:

// src/nodeTypes/MyCustomNode.ts
export const MyCustomNode: NodeTypeDefinition = {
  displayName: 'My Custom Node',
  name: 'myCustomNode',
  group: ['transform'],
  version: 1,
  properties: [
    {
      displayName: 'My Parameter',
      name: 'myParam',
      type: 'string',
      default: '',
      description: 'Description of my parameter',
    },
  ],
  inputs: [{ type: 'main' }],
  outputs: [{ type: 'main' }],
};

2. Register the node type in src/nodeTypes/index.ts:

import { MyCustomNode } from './MyCustomNode';

export const NODE_TYPE_DEFINITIONS = {
  // ... existing nodes
  myCustomNode: MyCustomNode,
};

3. The UI will automatically generate parameter forms and handle the node rendering.

📁 Project Structure

src/
├── App.tsx                     # Main application component
├── main.tsx                   # Entry point
├── contexts/                  # React Context providers
│   ├── WorkflowContext.tsx   # Main workflow state management
│   └── NodeContext.tsx       # Individual node state management
├── components/
│   ├── canvas/               # Canvas-related components
│   │   └── WorkflowCanvas.tsx
│   ├── nodes/               # Node components
│   │   └── N8nNode.tsx
│   └── panels/              # Parameter panels
│       ├── ParameterPanel.tsx
│       └── ParameterInput.tsx
├── nodeTypes/               # Node type definitions
│   ├── ManualTrigger.ts
│   ├── Set.ts
│   └── index.ts
├── types/                   # TypeScript type definitions
│   ├── context.ts
│   └── conversion.ts
├── utils/                   # Utility functions
│   ├── dataConversion.ts
│   └── cn.ts
└── hooks/                   # Custom React hooks
    ├── useStrictContext.ts
    └── useThrottle.ts

🎨 Styling

The project uses Tailwind CSS for styling with custom CSS variables for consistency:

• Colors: Primary, secondary, success, warning, danger variations
• Spacing: --spacing-xs through --spacing-5xl
• Typography: Font sizes, line heights, and weights
• Borders: Radius and border utilities

🌟 Key Design Decisions

Why NodeProvider is Critical

The NodeProvider is essential for n8n compatibility:

• Mirrors n8n's provide/inject pattern from Vue
• Enables future parameter system expansions (conditional parameters, expressions, validation)
• Provides performance optimization (local re-rendering)
• Ensures type safety for node-specific operations

For detailed explanation, see: NodeProvider Architecture Documentation

EventBus → React Callbacks

Originally used EventBus pattern, but migrated to React's standard callback patterns for:

• Better React integration
• Improved type safety
• Simplified debugging
• Reduced dependencies

🔮 Roadmap

Phase 1: Foundation (✅ Complete)

• Basic workflow editor
• ReactFlow integration
• Parameter panels
• Sample nodes

Phase 2: Advanced Features (🚧 In Progress)

• Expression evaluation ({{ $json.data }})
• Conditional parameter display
• Resource loading (API endpoints, credentials)
• Advanced validation
• Custom node SDK

Phase 3: Enterprise Features (🔮 Planned)

• Real workflow execution engine
• Plugin system
• Advanced debugging tools
• Performance analytics
• Collaborative editing

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow existing code patterns and TypeScript conventions
• Maintain n8n compatibility in new features
• Add tests for new functionality
• Update documentation as needed
• Use meaningful commit messages

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• n8n - For the incredible workflow automation platform and design inspiration
• ReactFlow - For the excellent flow library
• React - For the amazing frontend framework
• Community contributors - For ideas, feedback, and contributions

📞 Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions

---

Built with ❤️ for the workflow automation community