
editor
The official vendor-neutral visual editor for the Open Workflow Specification.

Try the editor — the latest released version.
Overview
This project provides an interactive, visual diagram editor designed to be:
- Vendor-neutral: No platform-specific dependencies
- Embeddable: Core logic decoupled from platform APIs (VS Code, browser extensions, etc.)
- Specification-first: Built around the official Open Workflow Specification
Prerequisites
To build and run the editor locally, you will need:
- Node.js:
^22.22.2 || ^24.15.0 || >=26.0.0 (see nodejs.org)
- pnpm:
10.31.0 (exact version, enforced by packageManager field)
Getting Started with the Diagram Editor
See the Getting Started guide for installation and usage instructions for the Open Workflow Diagram Editor React component.
Building the Project
# Clone the repository
git clone https://github.com/open-workflow-specification/editor.git
cd editor
# Install dependencies
pnpm install
# Build all packages (development)
pnpm run build:dev
# Or build all packages (production - includes linting and tests)
pnpm run build:prod
Development
Running Storybook
Storybook provides an interactive development environment for the diagram editor:
cd packages/open-workflow-diagram-editor
pnpm start # Starts Storybook on http://localhost:6006
Running Tests
cd packages/open-workflow-diagram-editor
# Unit tests (Vitest)
pnpm test
# E2E tests (Playwright)
pnpm test-e2e # Headless
pnpm test-e2e:ui # With Playwright UI
# Type checking
pnpm typecheck
# Linting
pnpm lint
Before running E2E tests for the first time:
# From root directory
pnpm playwright:install:ci
Code Quality
# Format all files
pnpm format
# Check formatting without modifying
pnpm format:check
# Check dependency versions across packages
pnpm dependencies:check
# Fix dependency version mismatches
pnpm dependencies:fix
Repository Structure
editor/
├── .github/ # CI workflows, issue templates, Dependabot config
├── .husky/ # Git hooks (commit-msg for DCO, pre-commit for linting)
├── adr/ # Architecture Decision Records
├── packages/ # Monorepo workspace packages
│ ├── open-workflow-diagram-editor/ # Main diagram editor component
│ └── i18n/ # Internationalization utilities
├── .changeset/ # Changesets for version management
├── .oxfmtrc.json # Formatter config (oxfmt)
├── .oxlintrc.json # Linter config (oxlint)
├── .syncpackrc.json # Monorepo package version consistency
├── netlify.toml # Netlify configuration for Storybook previews
├── pnpm-workspace.yaml # pnpm workspace definition with catalog dependencies
├── tsconfig.base.json # Shared TypeScript config (strict mode enabled)
└── CONTRIBUTING.md # Contribution guidelines
Packages
The main visual diagram editor component built with:
Internationalization utilities used by the diagram editor.
Technology Stack
Architecture
The diagram editor maintains strict separation of concerns:
- SDK Isolation: SDK integration helpers live under
src/core/ (e.g., workflowSdk.ts, graph.ts, taskSubType.ts, taskDetails.ts, mermaidExport.ts); other layers may also import SDK types/enums (e.g., Specification, GraphNodeType) when needed.
- React Flow Isolation: React Flow rendering components live in
src/react-flow/ (nodes/edges/diagram); other layers may import @xyflow/react types and/or ReactFlowProvider.
- Platform Agnostic: Core logic decoupled from platform-specific APIs
- Embeddable: Designed for integration into VS Code, web apps, and browser extensions
See adr/ for Architecture Decision Records.
Contributing
We welcome contributions! Please see CONTRIBUTING.md for details on:
- Setting up your development environment
- Coding standards and best practices
- Testing requirements
- Pull request process
- DCO sign-off requirements (required for all commits)
DCO Sign-off
As a CNCF project, all commits must include a Signed-off-by line:
git commit -s -m "Your commit message"
The commit-msg hook will automatically verify DCO compliance.
Continuous Integration
- Automated Testing: All PRs run linting, type checking, unit tests, and E2E tests
- Netlify Previews: Storybook is automatically deployed for PRs modifying the diagram editor package
- GitHub Pages: Each released version is published to open-workflow-specification.github.io/editor/latest/, built from its git tag. Unlike the Netlify previews, this only ever shows what has been released to npm
- Dependency Updates: Automated via Dependabot
- License Header Checks: Apache 2.0 headers verified on all source files
Release Process
This project uses Changesets for version management:
# Create a changeset when making package changes
pnpm changeset
# Or compare against upstream explicitly
# add upstream remote, if you don't have it already
git remote add upstream https://github.com/open-workflow-specification/editor.git
pnpm changeset --since upstream/main
See RELEASE_PROCESS.md for details.
Community
License
This project is licensed under the Apache License 2.0.
elkjs is used under EPL-2.0, not GPL
elkjs, used for automatic graph layout, is dual-licensed
EPL-2.0 OR GPL-3.0-or-later. OR means the recipient chooses, and this project uses elkjs
under the Eclipse Public License 2.0.
Related Projects