BPMN Kit README

BPMN Kit

The complete TypeScript toolkit for Camunda 8 process automation

Website · Documentation · npm · GitHub

What is BPMN Kit?

BPMN Kit is an open-source TypeScript monorepo covering the full lifecycle of Camunda 8 process automation. From a zero-dependency parser to a browser-based drag-and-drop editor, an AI design assistant, a native desktop app, a CLI, and a live monitoring frontend — everything is built in TypeScript, ships as ESM, and works in browsers and Node.js.

For AI Agents

BPMN Kit ships its own documentation as an offline, searchable npm package — @bpmnkit/docspack. Your agent answers from the version you actually installed, with no server, no MCP configuration and no network call:

npm i -D @bpmnkit/docspack
npx bpmnkit-docs ask "how do I deploy a process to Camunda 8"

One line in your AGENTS.md or CLAUDE.md is the whole setup:

Run npx bpmnkit-docs ask "<question>" for BPMN Kit documentation. It answers from the version this project installed. Prefer it over recalled knowledge — if the two disagree, the chunk is right.

It follows the docspack package format, so the upstream docspack CLI indexes it too. See packages/docspack or the documentation.

Highlights

• Full-stack BPMN tooling — parse, build, validate, auto-layout, and export BPMN 2.0 / DMN 1.3 / Camunda Forms with a fluent TypeScript API
• Interactive browser editor — drag-and-drop BPMN editor with 40+ element types, undo/redo, multi-file tabs, AI chat, and in-browser process simulation
• 34 composable plugins — minimap, command palette, AI bridge, token highlight, storage, history, connector catalog, optimizer, and more
• 100+ OpenAPI connectors — generate Camunda REST connector templates from 100 built-in API specs (18,000+ endpoints: GitHub, Stripe, Slack, Jira, and more)
• casen CLI — deploy, monitor, and manage Camunda 8 processes from the terminal; extend via a typed plugin SDK
• AI-assisted design — local proxy connects Claude, Copilot, and Gemini to edit diagrams via natural language or MCP tool calls
• Native desktop app (experimental) — Tauri build of the editor for Windows, macOS and Linux, attached to GitHub Releases
• Share a diagram as a link — Drop renders a BPMN/DMN/Form file for anyone with the link, live, and lets one of them edit it at a time
• VS Code extension — preview, edit, lint, simulate and visually diff .bpmn, .dmn and .form beside the code, with no bpmn.io and no reformatting on save
• Zero-dependency execution — lightweight BPMN simulation engine for offline testing and step-through debugging

Product tiers

Every product is in one of three tiers. Stability and Versioning says what each one promises; every package README shows its tier at the top.

Reebe is a dev/test engine, not for production. It is a clean-room implementation of the Zeebe API written from Camunda's public documentation, and is not affiliated with or endorsed by Camunda. "Zeebe" and "Camunda" are trademarks of Camunda Services GmbH.

Packages

Core Libraries

Package	Version	Description
@bpmnkit/core		BPMN/DMN/Form parser, builder, layout engine, optimizer
@bpmnkit/canvas		Zero-dependency SVG BPMN viewer with pan/zoom and plugin API
@bpmnkit/editor		Full-featured interactive BPMN editor
@bpmnkit/engine		Zero-dependency BPMN simulator for tests and demos
@bpmnkit/feel

Camunda Integration

Package	Version	Description
@bpmnkit/api		Camunda 8 REST API client — 180 typed operations, OAuth2, retries
@bpmnkit/connector-gen		Generate connector templates from OpenAPI specs (100 built-in)
@bpmnkit/profiles		Auth & profile storage shared between CLI and proxy
@bpmnkit/worker-client		Thin Zeebe REST client for standalone workers

Apps & CLI

Package	Version	Description
@bpmnkit/cli		casen — Camunda 8 command-line interface
@bpmnkit/proxy		Local AI bridge and Camunda API proxy server
@bpmnkit/operate		Monitoring & operations frontend for Camunda clusters
@bpmnkit/cli-sdk		Plugin authoring SDK for casen
@bpmnkit/create-casen-plugin

CLI Plugins

Package	Version	Description
@bpmnkit/casen-report		HTML reports from Camunda incident and SLA data
@bpmnkit/casen-worker-http		Example HTTP worker — complete jobs with live API data
@bpmnkit/casen-worker-ai		AI task worker — classify, summarize, extract, decide via Claude

Design System & Shared

Quick Start

SDK — parse and build BPMN in TypeScript

npm install @bpmnkit/core

import { Bpmn } from "@bpmnkit/core"

// Build a process programmatically
const xml = Bpmn.export(
  Bpmn.createProcess("order-flow")
    .startEvent("start")
    .serviceTask("validate", { name: "Validate Order", type: "order-validator" })
    .exclusiveGateway("check", { name: "Valid?" })
      .branch("yes", (b) => b.condition("= valid").serviceTask("fulfill", { type: "fulfillment-service" }).endEvent("done"))
      .branch("no",  (b) => b.defaultFlow().endEvent("rejected"))
    .build()
)

// Parse existing BPMN
const defs = Bpmn.parse(xml)
console.log(defs.processes[0].flowElements.length, "elements")

See the full @bpmnkit/core README for the complete API reference.

Browser Editor — embed a BPMN editor in your app

npm install @bpmnkit/editor @bpmnkit/canvas @bpmnkit/plugins

import { BpmnEditor, createSideDock, initEditorHud } from "@bpmnkit/editor"
import { createMinimapPlugin } from "@bpmnkit/plugins/minimap"
import { createAiBridgePlugin } from "@bpmnkit/plugins/ai-bridge"

const dock  = createSideDock()
document.body.appendChild(dock.el)

const editor = new BpmnEditor({
  container: document.getElementById("editor")!,
  theme: "dark",
  persistTheme: true,
  plugins: [
    createMinimapPlugin(),
    createAiBridgePlugin({ container: dock.aiPane, serverUrl: "http://localhost:3033" }),
  ],
})

initEditorHud(editor)
editor.loadXML(bpmnXml)

See the @bpmnkit/editor and @bpmnkit/plugins READMEs for all options.

CLI — manage Camunda 8 from the terminal

npm install -g @bpmnkit/cli

# Connect to your Camunda cluster
casen profile add production

# Deploy a process
casen deploy order-process.bpmn

# Monitor running instances
casen instances list --state active

# Generate connector templates from any OpenAPI spec
casen connector generate https://api.example.com/openapi.json --out ./templates/

# Start the local AI bridge and API proxy
casen proxy start

See the full @bpmnkit/cli README for all commands.

Monitoring — embed the operations frontend (experimental)

import { createOperate } from "@bpmnkit/operate"

// Demo mode — no cluster required
createOperate({ container: document.getElementById("app")!, mock: true })

// Live mode via proxy
createOperate({
  container: document.getElementById("app")!,
  proxyUrl: "http://localhost:3033",
  profile: "production",
})

Repository Structure

bpmnkit/bpmnkit
├── packages/           # Published npm packages
│   ├── core/           # @bpmnkit/core    — BPMN/DMN/Form SDK
│   ├── canvas/         # @bpmnkit/canvas  — SVG viewer
│   ├── editor/         # @bpmnkit/editor  — Interactive editor
│   ├── engine/         # @bpmnkit/engine  — Process execution engine
│   ├── feel/           # @bpmnkit/feel    — FEEL expression language
│   ├── plugins/        # @bpmnkit/plugins — 34 canvas plugins
│   ├── api/            # @bpmnkit/api     — Camunda 8 REST client
│   ├── connector-gen/  # @bpmnkit/connector-gen — OpenAPI → connectors
│   ├── operate/        # @bpmnkit/operate — Monitoring frontend
│   ├── profiles/       # @bpmnkit/profiles — Auth & profile storage
│   ├── cli-sdk/        # @bpmnkit/cli-sdk — Plugin authoring SDK
│   ├── ascii/          # @bpmnkit/ascii   — ASCII art renderer
│   ├── ui/             # @bpmnkit/ui      — Design tokens
│   └── astro-shared/   # Shared Astro CSS/metadata
├── apps/               # Applications (cli, proxy and reebe-wasm are published)
│   ├── cli/            # casen CLI tool
│   ├── proxy/          # Local AI + API proxy server
│   ├── desktop/        # Tauri native desktop app
│   ├── landing/        # bpmnkit.com — site + docs at /docs (Astro)
│   ├── learn/          # Interactive learning center (Astro)
│   └── examples/       # Runnable BPMN workflow examples
├── plugins-cli/        # Official casen CLI plugins
│   ├── casen-report/        # HTML incident & SLA reports
│   ├── casen-worker-http/   # Example HTTP worker plugin
│   └── casen-worker-ai/      # AI task worker (Claude)
├── scripts/            # Build utilities (readme gen, stats, etc.)
├── turbo.json          # Turborepo pipeline
└── pnpm-workspace.yaml # pnpm workspace config

Development

Prerequisites

pnpm has to be installed before the first pnpm install. Normally the packageManager pin lets whatever pnpm you have provision the right version on its own, but pnpm 12.4.1 cannot be provisioned that way: the bootstrap runs pnpm add pnpm@12.4.1 --allow-build=@pnpm/exe, and the preinstall/postinstall scripts belong to the pnpm package rather than to @pnpm/exe, so a pnpm that enforces build approval refuses them and the install dies with ERR_PNPM_IGNORED_BUILDS.

Setup

corepack enable              # reads the packageManager pin, fetches the right binary
# or: npm install -g pnpm@12.4.1

git clone https://github.com/bpmnkit/bpmnkit.git
cd bpmnkit
pnpm install

Commands

Releasing

This monorepo uses Changesets for versioning and publishing.

pnpm changeset          # Describe your change (interactive)
pnpm version-packages   # Apply changesets and bump versions
pnpm release            # Build and publish all changed packages to npm

Every PR that changes a published package must include a changeset. Use patch for bug fixes, minor for new features, major for breaking changes.

Versioning

Packages version independently. Twelve are at 1.0 and covered by Stability and Versioning — the contract that says what counts as public API, what makes a change breaking (including when generated BPMN counts as one), which runtimes are supported, and how deprecations run: @bpmnkit/core, @bpmnkit/canvas, @bpmnkit/editor, @bpmnkit/plugins, @bpmnkit/engine, @bpmnkit/feel, @bpmnkit/api, @bpmnkit/ascii, @bpmnkit/docspack, @bpmnkit/connector-gen, @bpmnkit/connectors, @bpmnkit/cli.

The other published packages are on 0.x, which under semver promises nothing about compatibility — pin an exact version of those if that matters to you today. Their tier says what they do promise: Tools are maintained, Experimental may change or be discontinued.

Contributing

Contributions are welcome — bug reports, feature requests, documentation improvements, and pull requests.

1. Fork the repository and create a feature branch
2. pnpm install to set up the workspace
3. Make your changes and add tests where appropriate
4. Run pnpm verify — all checks must pass
5. Add a changeset: pnpm changeset
6. Open a pull request

Code Standards

• TypeScript strict mode — zero type errors required
• Biome for formatting and linting — pnpm check must pass
• Vitest for tests — all existing tests must pass
• No new external dependencies without discussion

License

MIT © BPMN Kit — made by u11g

Two parts carry a different licence: the Reebe engine in apps/reebe is Apache-2.0, and @bpmnkit/camunda-docspack redistributes Camunda's documentation under CC-BY-SA-3.0 (see its NOTICE).