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

``bash


Using pnpm (recommended)

pnpm add workflow-vue

Using npm

npm install workflow-vue

Using yarn

yarn add workflow-vue
`

🚀 Quick Start

$3

`javascript
// 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:

`vue

`

$3

`vue



`

📚 Core API

$3

#### WorkflowBuilder - Workflow Builder

The main visual workflow builder component.

`vue
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.

`vue
: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

$3

#### WorkflowService - Workflow Management Service

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

`javascript
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.

`javascript
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

$3

#### NODE_TYPES - Node Type Configuration

All supported node types and their configurations.

`javascript
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.

`javascript
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);
});
`

$3

#### WorkflowUtils - Workflow Utilities

Utility functions related to workflows.

`javascript
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.

`javascript
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.

`javascript
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 });
`

$3

#### WorkflowEngine - Execution Engine

Workflow runtime execution engine.

`javascript
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

$3

`vue



`

$3

`vue



`

$3

`javascript
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

$3

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

`json
{
"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

$3

`bash


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
`

$3

`
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

$3

- [ ] 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

$3

Follow Semantic Versioning specification:

`bash


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.

$3

Execute in monorepo root directory:

`bash


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.

$3

If you need to publish to a private npm registry:

`bash


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"
}
}
`

$3

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

1. Modify name in package.json:
`json
{
"name": "@pieteams/workflow-vue"
}
`

2. Specify access when publishing:
`bash
pnpm publish --access public
`

$3

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

$3

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:
`bash
pnpm add vue@^3.4.0 bootstrap@^5.3.0 bootstrap-icons@^1.11.0
`

$3

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

$3

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:
`bash
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"
``

$3

- 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