Workflow Viz

A standalone visual workflow designer with CLI - drag-and-drop workflow builder with visual connections and PNG/JSON export capabilities.

🚀 Quick Start

Installation

npm install -g workflow-viz

Start the Designer

# Default (opens on port 8005)
workflow-viz serve

# Custom port
workflow-viz serve --port 3000

# Custom host and port
workflow-viz serve --host 0.0.0.0 --port 8080

# Don't open browser automatically
workflow-viz serve --port 3000 --no-open

📋 Features

• 🎨 Drag & Drop Interface - Intuitive node palette with various node types
• 🔗 Visual Connections - Connect nodes with animated bezier curves
• 📝 Properties Panel - Edit node properties in real-time
• 💾 Import/Export - Save and load workflows as JSON
• 🖼️ PNG Export - Export entire workflow as high-quality PNG image
• 🎯 Customizable - Extensible node types and styling
• 📱 Responsive - Works on desktop and tablet devices
• 🖥️ CLI Tool - Standalone server with command-line interface

🛠️ CLI Commands

workflow-viz serve

Start the workflow designer server.

Options:

• -p, --port <port> - Port to run the server on (default: 8005)
• --host <host> - Host to bind the server to (default: localhost)
• --no-open - Do not open browser automatically
• -V, --version - Output the version number
• --help - Display help for command

Examples:

# Start on default port 8005
workflow-viz serve

# Start on port 3000
workflow-viz serve --port 3000

# Start on port 8080 and expose to network
workflow-viz serve --host 0.0.0.0 --port 8080

# Start without opening browser
workflow-viz serve --no-open

# Start on custom port without browser
workflow-viz serve --port 4000 --no-open

📦 Usage as Library

You can also use workflow-viz as a React component in your projects.

Installation

npm install workflow-viz

Basic Usage

import React from 'react';
import { WorkflowDesigner } from 'workflow-viz';
import 'workflow-viz/dist/style.css';

function App() {
  const handleSave = (workflowData) => {
    console.log('Workflow saved:', workflowData);
  };

  return (
    <div style={{ height: '100vh' }}>
      <WorkflowDesigner onSave={handleSave} />
    </div>
  );
}

export default App;

With Initial Data

import React from 'react';
import { WorkflowDesigner } from 'workflow-viz';

const initialWorkflow = {
  nodes: [
    {
      id: 'node_1',
      type: 'custom',
      position: { x: 250, y: 100 },
      data: { label: 'Start', type: 'start' }
    }
  ],
  edges: [],
  metadata: {
    name: 'My Workflow',
    version: '1.0.0'
  }
};

function App() {
  return (
    <WorkflowDesigner 
      initialData={initialWorkflow}
      onSave={(data) => console.log(data)}
    />
  );
}

🎯 Available Node Types

• Start - Workflow entry point
• End - Workflow termination
• Process - Processing step
• Decision - Conditional branching
• API Call - External API integration
• Database - Database operations
• Transform - Data transformation
• Notification - Send notifications
• Timer - Scheduled tasks
• Loop - Iterative operations

📤 Export & Import

Export Workflow

JSON Export:

• Click the "Export JSON" button in the toolbar
• Downloads workflow as .json file
• Includes all nodes, edges, and metadata

PNG Export:

• Click the "Export PNG" button in the toolbar
• Captures entire workflow canvas (all nodes, not just viewport)
• High-quality 2x pixel ratio
• Excludes UI controls (minimap, toolbar)

Import Workflow

1. Click the "Import" button in the toolbar
2. Select a .json workflow file
3. Workflow loads with proper positioning

🔧 API Reference

WorkflowDesigner Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | initialData | WorkflowData | undefined | Initial workflow data with nodes and edges | | onSave | (data: WorkflowData) => void | undefined | Callback when workflow is saved | | onChange | (data: WorkflowData) => void | undefined | Callback when workflow changes | | readOnly | boolean | false | Make workflow read-only | | className | string | '' | Additional CSS classes |

WorkflowData Type

interface WorkflowData {
  nodes: Node[];
  edges: Edge[];
  metadata?: {
    name?: string;
    version?: string;
    created?: string;
    [key: string]: any;
  };
}

🌐 Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

📚 Dependencies

• React 18+
• React Flow 11+
• html-to-image 1.11+
• Commander 11+ (CLI)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT

🆘 Support

For issues and questions, please open an issue on GitHub.

Made with ❤️ using React Flow