Website · Documentation · GitHub · Changelog

Core tier. Semver at 1.0: nothing breaks without a major release. See product tiers.

Overview

@bpmnkit/editor turns the @bpmnkit/canvas viewer into a fully interactive editor. Drag to connect elements, inline-edit labels, resize shapes, attach boundary events, and integrate AI-assisted design — all through a composable API.

Features

• 40+ element types — all BPMN 2.0 tasks, events, gateways, sub-processes
• Drag-to-connect — draw sequence flows with automatic waypoint routing
• Resize & move — multi-select, group move, constrained resize
• Label editing — inline text editor with multi-line support
• Undo/redo — full command history with keyboard shortcuts
• Copy/paste — multi-element clipboard with offset paste
• Boundary events — attach and detach boundary events interactively
• HUD toolbar — customisable palette with shape categories
• Side dock — resizable right sidebar with Properties, AI chat, and Docs tabs
• Theme persistence — auto read/write localStorage with persistTheme
• Ten languages — English built in; German, Spanish, French, Italian, Dutch, Polish, Portuguese (Brazil), Japanese and Chinese (Simplified) as tree-shakable locales

Installation

npm install @bpmnkit/editor @bpmnkit/canvas

Quick Start

import { BpmnEditor, initEditorHud, createSideDock } from "@bpmnkit/editor"

// Full editor (viewer + editing interactions)
const editor = new BpmnEditor({
  container: document.getElementById("editor")!,
  theme: "dark",
  persistTheme: true,
  plugins: [],
})

// Toolbar HUD (palette, zoom controls, etc.)
initEditorHud(editor, {
  container: document.getElementById("hud")!,
})

// Sidebar with Properties + AI tabs
const dock = createSideDock(document.body)
editor.loadXML(bpmnXml)

API Reference

BpmnEditor

Extends BpmnCanvas. Adds all editing interactions.

interface EditorOptions extends CanvasOptions {
  persistTheme?: boolean  // auto-save theme to localStorage
}

initEditorHud(editor, options)

Mounts the toolbar HUD into a container.

interface HudOptions {
  container: HTMLElement
  optimizeButton?: HTMLElement  // inject into action bar
  aiButton?: HTMLElement        // inject into action bar
  // Decisions and forms (and a title) for More → Export documentation…
  getDocumentationContext?: () => DocumentationOptions
}

The HUD's More menu has Export documentation…: a print-ready HTML view (Print → Save as PDF), or an HTML, Markdown or Word download, built with @bpmnkit/core's process documentation renderers.

applyProcessDelta(defs, delta, { aliases })

Applies a change script from @bpmnkit/core's parseProcessDelta to a diagram someone drew, keeping its layout: new nodes are placed beside what they follow, an insert between two connected nodes moves only the shapes right of it, and nothing the script does not mention changes. Returns the new document with what it created, changed and removed, the fixes it made and the problems it left out. Also exported from @bpmnkit/editor/headless. A script's with lines configure connectors when you pass applyConnectors: applyConnectorLines from @bpmnkit/core/connectors; required inputs they left out come back as questions.

import { parseProcessDelta, writeProcessText } from "@bpmnkit/core"
import { applyProcessDelta } from "@bpmnkit/editor/headless"

const { text, aliases } = writeProcessText(defs) // what the model reads
const script = await askModel(text, feedback)     // e.g. "review > second[user Second approval] > pay"
const { definitions, problems } = applyProcessDelta(defs, parseProcessDelta(script), { aliases })

createSideDock(container) → SideDock

Creates the right-side collapsible dock.

interface SideDock {
  el: HTMLElement
  propertiesPane: HTMLDivElement
  aiPane: HTMLDivElement
  docsPane: HTMLDivElement
  switchTab(tab: "properties" | "ai" | "docs" | "history" | "play"): void
  expand(): void
  collapse(): void
  collapsed: boolean
  setDiagramInfo(processName: string, fileName: string): void
}

Internationalisation

Each shipped language is its own entry point, so a bundle carries only what it imports. createTranslate(locale) turns one into the translate hook; pass the same hook to the editor, createSideDock and each @bpmnkit/plugins panel:

import { BpmnEditor, createSideDock, createTranslate, initEditorHud } from "@bpmnkit/editor"
import { de } from "@bpmnkit/editor/locales/de"

const translate = createTranslate(de)
const editor = new BpmnEditor({ container, translate })
const dock = createSideDock({ translate })
initEditorHud(editor) // reads the editor's hook

Locales: de, es, fr, it, nl, pl, pt-BR, ja, zh-CN. AVAILABLE_LOCALES lists them with their own names, and matchLocale(navigator.languages, codes) picks the browser's. A message can be a plural object ({ one, few, many, other }), chosen with Intl.PluralRules from count. Missing keys fall back to English. The translations are machine-assisted — corrections welcome, see CONTRIBUTING.md.

Related Packages

| Package | Description | |---------|-------------| | @bpmnkit/core | BPMN/DMN/Form parser, builder, layout engine | | @bpmnkit/canvas | Zero-dependency SVG BPMN viewer | | @bpmnkit/engine | Lightweight BPMN process simulator for tests and demos | | @bpmnkit/feel | FEEL expression language parser & evaluator | | @bpmnkit/plugins | 34 composable canvas plugins | | @bpmnkit/api | Camunda 8 REST API TypeScript client | | @bpmnkit/ascii | Render BPMN diagrams as Unicode ASCII art | | @bpmnkit/markdown | BPMN diagrams in Markdown — remark, markdown-it and README pre-rendering | | @bpmnkit/docspack | BPMN Kit docs as an offline docspack package for AI agents | | @bpmnkit/camunda-docspack | Camunda 8 docs as an offline docspack package for AI agents | | @bpmnkit/ui | Shared design tokens and UI components | | @bpmnkit/profiles | Shared auth, profile storage, and client factories for CLI & proxy | | @bpmnkit/operate | Monitoring & operations frontend for Camunda clusters | | @bpmnkit/connector-gen | Generate connector templates from OpenAPI specs | | @bpmnkit/connectors | Camunda 8 OOTB connector catalog and deterministic template application | | @bpmnkit/cli | Camunda 8 command-line interface (casen) | | @bpmnkit/proxy | Local AI bridge and Camunda API proxy server | | @bpmnkit/patterns | Domain process patterns for BPMNKit AIKit | | @bpmnkit/reebe-wasm | WebAssembly BPMN engine for browser simulation | | @bpmnkit/worker-client | Thin Zeebe REST client for standalone workers | | @bpmnkit/flow | Code-first durable flows that derive BPMN, job types and workers | | @bpmnkit/user-tasks | Embeddable user task widget for Camunda 8 | | @bpmnkit/cli-sdk | Plugin authoring SDK for the casen CLI | | @bpmnkit/create-casen-plugin | Scaffold a new casen CLI plugin in seconds | | @bpmnkit/casen-report | HTML reports from Camunda 8 incident and SLA data | | @bpmnkit/casen-worker-http | Example HTTP worker plugin — completes jobs with live JSONPlaceholder API data | | @bpmnkit/casen-worker-ai | AI task worker — classify, summarize, extract, and decide using Claude |

License

MIT © BPMN Kit — made by u11g