workflow-vue

A powerful Vue 3 workflow builder component library that provides visual workflow design and management capabilities.

English | 简体中文

✨ Features

• 🎨 Visual Design - Intuitive drag-and-drop workflow builder
• 🔧 Flexible Configuration - Support for multiple node types: approval, conditional branches, CC, etc.
• 🚀 Ready to Use - Available as both Vue plugin and on-demand imports
• 📦 Lightweight - Minimal core functionality with optimized dependencies
• 🎯 TypeScript Support - Complete type definitions
• 🧪 Test Coverage - Comprehensive unit tests

📦 Installation

# Using pnpm (recommended)
pnpm add workflow-vue

# Using npm
npm install workflow-vue

# Using yarn
yarn add workflow-vue

🚀 Quick Start

Option 1: Use as Vue Plugin (Recommended)

// main.js
import { createApp } from 'vue';
import App from './App.vue';
import { WorkflowVue } from 'workflow-vue';
import 'workflow-vue/style.css';

const app = createApp(App);
app.use(WorkflowVue);
app.mount('#app');

After installing the plugin, all components are automatically registered globally and can be used directly in templates:

<template>
  <WorkflowBuilder v-model="workflowData" @save="handleSave" />
</template>

Option 2: Import Components On-Demand

<template>
  <WorkflowBuilder 
    v-model="workflowData"
    @save="handleSave"
  />
</template>

<script setup>
import { ref } from 'vue';
import { WorkflowBuilder } from 'workflow-vue';

const workflowData = ref(null);

const handleSave = (workflow) => {
  console.log('Save workflow:', workflow);
};
</script>

📚 Core API

Components

WorkflowBuilder - Workflow Builder

The main visual workflow builder component.

<WorkflowBuilder 
  v-model="workflowData"
  :readonly="false"
  @save="handleSave"
  @cancel="handleCancel"
/>

Props:

• modelValue - Workflow data object
• readonly - Read-only mode (default: false)

Events:

• update:modelValue - Emitted when workflow data is updated
• save - Emitted when save button is clicked
• cancel - Emitted when cancel button is clicked

WorkflowNode - Workflow Node

Individual workflow node component for displaying and editing nodes.

<WorkflowNode 
  :node="nodeData"
  :readonly="false"
  @edit="handleEdit"
  @delete="handleDelete"
/>

Props:

• node - Node data object
• readonly - Read-only mode

Events:

• edit - Emitted when editing a node
• delete - Emitted when deleting a node

Services

WorkflowService - Workflow Management Service

Provides workflow creation, validation, serialization, and other functionalities.

import { WorkflowService } from 'workflow-vue';

// Create a new workflow
const workflow = WorkflowService.createWorkflow('Approval Process');

// Validate workflow
const isValid = WorkflowService.validateWorkflow(workflow);

// Serialize workflow to JSON
const json = WorkflowService.serializeWorkflow(workflow);

// Deserialize workflow from JSON
const workflow = WorkflowService.deserializeWorkflow(json);

Main Methods:

• createWorkflow(name) - Create a new workflow
• validateWorkflow(workflow) - Validate workflow
• serializeWorkflow(workflow) - Serialize to JSON
• deserializeWorkflow(json) - Deserialize from JSON

NodeService - Node Management Service

Provides node creation, validation, cloning, and other functionalities.

import { NodeService } from 'workflow-vue';

// Create approval node
const approvalNode = NodeService.createNode('APPROVAL', 'Department Approval');

// Create CC node
const ccNode = NodeService.createNode('CC', 'CC to HR');

// Validate node configuration
const isValid = NodeService.validateNode(node);

// Clone node
const clonedNode = NodeService.cloneNode(node);

Main Methods:

• createNode(type, name) - Create a node
• validateNode(node) - Validate a node
• cloneNode(node) - Clone a node
• updateNode(node, updates) - Update a node

Constants

NODE_TYPES - Node Type Configuration

All supported node types and their configurations.

import { NODE_TYPES } from 'workflow-vue';

console.log(NODE_TYPES.START);      // Start node
console.log(NODE_TYPES.APPROVAL);   // Approval node
console.log(NODE_TYPES.CONDITION);  // Conditional branch
console.log(NODE_TYPES.CC);         // CC node
console.log(NODE_TYPES.END);        // End node

Each node type includes the following configuration:

• type - Node type identifier
• name - Node display name
• description - Node description
• icon - Bootstrap icon class name
• class - CSS style class
• deletable - Whether it can be deleted
• editable - Whether it can be edited

ADDABLE_NODE_TYPES - Addable Node List

List of addable node types for UI display.

import { ADDABLE_NODE_TYPES } from 'workflow-vue';

// Includes: Approval, Conditional, CC, Auto Approve, Auto Reject
ADDABLE_NODE_TYPES.forEach(nodeType => {
  console.log(nodeType.name, nodeType.description);
});

Utilities

WorkflowUtils - Workflow Utilities

Utility functions related to workflows.

import { WorkflowUtils } from 'workflow-vue';

// Find node by ID
const node = WorkflowUtils.findNodeById(workflow, 'node-123');

// Get all nodes in the workflow
const allNodes = WorkflowUtils.getAllNodes(workflow);

// Detect circular dependencies
const hasCycle = WorkflowUtils.detectCycle(workflow);

// Get all successor nodes of a node
const nextNodes = WorkflowUtils.getNextNodes(workflow, nodeId);

NodeHelper - Node Helper Functions

Helper functions related to nodes.

import { NodeHelper } from 'workflow-vue';

// Get node icon
const icon = NodeHelper.getNodeIcon('APPROVAL');

// Get node style class
const className = NodeHelper.getNodeClass('APPROVAL');

// Check if node is deletable
const deletable = NodeHelper.isNodeDeletable(node);

// Check if node is editable
const editable = NodeHelper.isNodeEditable(node);

JsonHelper - JSON Utilities

JSON serialization and deserialization utilities.

import { JsonHelper } from 'workflow-vue';

// Deep clone object
const cloned = JsonHelper.deepClone(obj);

// Safe JSON parsing
const data = JsonHelper.safeParse(jsonString, defaultValue);

// Format JSON
const formatted = JsonHelper.stringify(obj, { pretty: true });

Workflow Engine

WorkflowEngine - Execution Engine

Workflow runtime execution engine.

import { createWorkflowEngine } from 'workflow-vue';

// Create engine instance
const engine = createWorkflowEngine(workflowData);

// Start workflow execution
const result = await engine.execute({
  userId: 'user-123',
  formData: { amount: 5000, reason: 'Purchase Request' }
});

// Get current execution node
const currentNode = engine.getCurrentNode();

// Move to next node
await engine.moveToNext({
  approved: true,
  comment: 'Approved'
});

// Get execution history
const history = engine.getHistory();

Main Methods:

• execute(context) - Start workflow
• getCurrentNode() - Get current node
• moveToNext(result) - Move to next node
• getHistory() - Get execution history
• rollback() - Rollback to previous node

🎯 Node Types

| Node Type | Description | Deletable | Editable | Icon | |-----------|-------------|-----------|----------|------| | START | Start node, workflow entry point | ❌ | ❌ | bi-play-circle-fill | | APPROVAL | Approval node, requires approvers | ✅ | ✅ | bi-person-check-fill | | CONDITION | Conditional branch, different paths based on conditions | ✅ | ✅ | bi-diagram-3-fill | | CC | CC node, notify relevant personnel | ✅ | ✅ | bi-send-fill | | END | End node, workflow termination point | ❌ | ❌ | bi-stop-circle-fill | | AUTO_APPROVE | Auto approve, system automatically approves | ✅ | ✅ | bi-check-circle-fill | | AUTO_REJECT | Auto reject, system automatically rejects | ✅ | ✅ | bi-x-circle-fill |

💡 Usage Examples

Example 1: Simple Approval Process

<template>
  <div class="workflow-container">
    <WorkflowBuilder 
      v-model="workflow"
      @save="saveWorkflow"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { WorkflowBuilder, WorkflowService } from 'workflow-vue';

// Create initial workflow
const workflow = ref(
  WorkflowService.createWorkflow('Leave Approval Process')
);

// Save workflow
const saveWorkflow = async (data) => {
  try {
    const json = WorkflowService.serializeWorkflow(data);
    await api.saveWorkflow(json);
    console.log('Workflow saved successfully');
  } catch (error) {
    console.error('Save failed:', error);
  }
};
</script>

Example 2: Read-Only Display

<template>
  <WorkflowBuilder 
    v-model="workflow"
    :readonly="true"
  />
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { WorkflowService } from 'workflow-vue';

const workflow = ref(null);

onMounted(async () => {
  const json = await api.getWorkflow(workflowId);
  workflow.value = WorkflowService.deserializeWorkflow(json);
});
</script>

Example 3: Programmatic Workflow Creation

import { WorkflowService, NodeService } from 'workflow-vue';

// Create workflow
const workflow = WorkflowService.createWorkflow('Purchase Approval');

// Add approval nodes
const deptApproval = NodeService.createNode('APPROVAL', 'Department Approval');
deptApproval.approvers = ['user-001', 'user-002'];

const financeApproval = NodeService.createNode('APPROVAL', 'Finance Approval');
financeApproval.approvers = ['user-003'];

// Add CC node
const ccNode = NodeService.createNode('CC', 'CC to HR');
ccNode.ccUsers = ['user-004'];

// Build workflow
workflow.nodes = [
  workflow.startNode,
  deptApproval,
  financeApproval,
  ccNode,
  workflow.endNode
];

// Save
const json = WorkflowService.serializeWorkflow(workflow);

🔧 Local Development

Monorepo Internal Reference

In the PieMDM monorepo, frontend references the local package via workspace:

{
  "dependencies": {
    "workflow-vue": "workspace:*"
  }
}

Development Experience Advantages:

• ✅ No Pre-build Required - Vite processes source code directly, no need to run pnpm build first
• ✅ Hot Module Replacement - Modifying workflow-vue source code automatically refreshes frontend
• ✅ Type Hints - Full TypeScript support with IDE intellisense
• ✅ Debug Friendly - Can set breakpoints directly in source code

Why No Pre-build Required?

In pnpm workspace mode:

1. Vite processes src/lib/index.js source code directly
2. Does not use the exports configuration in package.json
3. Source code changes take effect immediately without rebuilding

The main, module, and exports fields in package.json are mainly used for:

• External projects after publishing to npm
• TypeScript type definition file references

Development Commands

# Install dependencies
pnpm install

# Start development server (with HMR)
pnpm dev

# Build production version
pnpm build

# Run unit tests
pnpm test

# Run tests with coverage report
pnpm test:coverage

# Run tests in watch mode
pnpm test:watch

# Test UI interface
pnpm test:ui

# TypeScript type checking
pnpm type-check

# ESLint code checking
pnpm lint

# Prettier code formatting
pnpm format

Project Structure

workflow-vue/
├── src/
│   ├── lib/                    # 📚 Library source code
│   │   ├── components/         # 🎨 Vue components
│   │   │   ├── WorkflowBuilder.vue    # Workflow builder
│   │   │   ├── WorkflowNode.vue       # Workflow node
│   │   │   └── AddNodeModal.vue       # Add node modal
│   │   ├── services/           # 🔧 Business services
│   │   │   ├── workflow-service.js    # Workflow service
│   │   │   ├── node-service.js        # Node service
│   │   │   └── user-service.js        # User service
│   │   ├── utils/              # 🛠️ Utility functions
│   │   │   ├── workflow-utils.js      # Workflow utilities
│   │   │   ├── node-helper.js         # Node helpers
│   │   │   ├── json-helper.js         # JSON utilities
│   │   │   └── validator.js           # Validation utilities
│   │   ├── constants/          # 📋 Constants
│   │   │   └── node-types.js          # Node types
│   │   ├── engine/             # ⚙️ Workflow engine
│   │   │   └── workflow-engine.js     # Execution engine
│   │   └── index.js            # 📦 Entry file
│   ├── App.vue                 # 🎯 Development preview app
│   └── main.js                 # 🚀 Development entry
├── tests/                      # 🧪 Test files
│   ├── unit/                   # Unit tests
│   └── integration/            # Integration tests
├── dist/                       # 📦 Build output (auto-generated)
├── package.json                # 📄 Package configuration
├── vite.config.js              # ⚡ Vite configuration
├── vitest.config.js            # 🧪 Vitest configuration
├── tsconfig.json               # 📘 TypeScript configuration
├── eslint.config.js            # 🔍 ESLint configuration
├── README.md                   # 📖 English documentation
└── README_CN.md                # 📖 Chinese documentation

📦 Publishing to npm

Pre-publish Checklist

• [ ] Update version in package.json
• [ ] Ensure all tests pass (pnpm test)
• [ ] Ensure build succeeds (pnpm build)
• [ ] Check TypeScript types (pnpm type-check)
• [ ] Run code linting (pnpm lint)
• [ ] Update CHANGELOG.md (if applicable)
• [ ] Commit all code changes

Version Management

Follow Semantic Versioning specification:

# In packages/web/workflow-vue directory

# Patch version (bug fixes)
pnpm version patch  # 1.0.0 -> 1.0.1

# Minor version (new features, backward compatible)
pnpm version minor  # 1.0.0 -> 1.1.0

# Major version (breaking changes)
pnpm version major  # 1.0.0 -> 2.0.0

Or directly edit the version field in package.json.

Publishing to Public npm

Execute in monorepo root directory:

# Method 1: Use -C to specify directory
pnpm -C packages/web/workflow-vue publish --access public

# Method 2: Use filter (recommended, more suitable for monorepo)
pnpm -r --filter workflow-vue publish --access public

# Publish beta version
pnpm -r --filter workflow-vue publish --tag beta

# Publish with specific tag
pnpm -r --filter workflow-vue publish --tag next

Note: The prepublishOnly script is configured in package.json and will automatically run pnpm build before publishing.

Publishing to Private Registry

If you need to publish to a private npm registry:

# Method 1: Temporarily specify registry
pnpm -r --filter workflow-vue publish --registry https://your-registry.com

# Method 2: Configure in package.json
{
  "publishConfig": {
    "registry": "https://your-registry.com",
    "access": "restricted"
  }
}

Publishing Scoped Package

If you need to publish as a scoped package (e.g., @pieteams/workflow-vue):

1. Modify name in package.json:

{
  "name": "@pieteams/workflow-vue"
}

2. Specify access when publishing:

pnpm publish --access public

When to Consider Separate Repository

Publishing directly from a monorepo subdirectory is the most convenient and maintainable approach. Only consider splitting into a separate repository if:

• ❌ Need completely independent permission/visibility control
• ❌ Need completely independent release process and version management
• ❌ Don't want consumers to get monorepo-related metadata
• ❌ Need independent CI/CD pipeline

Otherwise, keeping it in the monorepo has more advantages:

• ✅ Unified dependency management
• ✅ Easier code sharing
• ✅ Controllable refactoring impact
• ✅ Better local development experience

🔗 Dependencies

Peer Dependencies (Required in consuming projects)

These dependencies need to be installed in projects using workflow-vue:

• Vue ^3.4.0 - Vue 3 framework
• Bootstrap ^5.3.0 - UI styling framework
• Bootstrap Icons ^1.11.0 - Icon library

Installation command:

pnpm add vue@^3.4.0 bootstrap@^5.3.0 bootstrap-icons@^1.11.0

Runtime Dependencies (Auto-installed)

These dependencies are automatically installed when installing workflow-vue:

• uuid ^9.0.1 - UUID generation utility
• vue-select 4.0.0-beta.6 - Dropdown select component

🤝 Contributing

Contributions are welcome! Please follow these steps:

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

Commit Convention

Follow Conventional Commits specification:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation updates
• style: - Code formatting (no functional changes)
• refactor: - Code refactoring (neither new feature nor bug fix)
• perf: - Performance optimization
• test: - Test-related changes
• chore: - Build/toolchain updates

Examples:

git commit -m "feat(workflow): add workflow export functionality"
git commit -m "fix(node): fix memory leak when deleting nodes"
git commit -m "docs: update API documentation"

Code Standards

• Use ESLint for code linting
• Use Prettier for code formatting
• Write unit tests for new features
• Update relevant documentation

📄 License

MIT © PieTeams

🔗 Related Links

• GitHub Repository
• Issue Tracker
• PieMDM Documentation
• Changelog

💬 Support

For questions or suggestions:

• 📝 Submit an Issue
• 📖 Check the Documentation
• 💬 Contact the maintenance team

🙏 Acknowledgments

Thanks to all developers who have contributed to this project!

Made with ❤️ by PieTeams