Website · Documentation · GitHub · Changelog

Overview

@bpmnkit/core is the foundation of the BPMN Kit. It gives you everything to work with BPMN 2.0, DMN 1.3, and Camunda Form definitions in pure TypeScript — no XML wrestling, no runtime dependencies.

Parse → Modify → Validate → Export

Features

• BPMN 2.0 — parse, create, and export process diagrams with full Zeebe/Camunda 8 extension support
• Fluent Builder API — construct valid processes programmatically, never touch raw XML
• Sugiyama Layout Engine — auto-position elements with clean orthogonal edge routing
• DMN 1.3 — decision tables, including FEEL expression support
• Camunda Form Definitions — type-safe form schema builder
• Optimizer — built-in rule engine to detect and auto-fix anti-patterns
• Compact Format — 70% smaller token-efficient JSON representation for AI/LLM workflows
• Zero Dependencies — runs in browsers, Node.js, Deno, Bun, and edge runtimes

Installation

npm install @bpmnkit/core
pnpm add @bpmnkit/core

Quick Start

Build a process from code

import { Bpmn } from "@bpmnkit/core"

const process = Bpmn.createProcess("order-flow", "Order Flow")
  .startEvent("start", "Order Received")
  .serviceTask("validate", "Validate Order", {
    type: "order-validator",
    inputs: [{ source: "=order", target: "order" }],
    outputs: [{ source: "=valid", target: "isValid" }],
  })
  .exclusiveGateway("check", "Order Valid?")
  .sequenceFlow("check", "fulfill", "=isValid = true")
  .serviceTask("fulfill", "Fulfill Order", { type: "fulfillment-service" })
  .endEvent("end", "Order Complete")
  .sequenceFlow("check", "reject", "=isValid = false")
  .endEvent("reject-end", "Order Rejected")
  .build()

const xml = Bpmn.export(process)

Parse and modify existing BPMN

import { Bpmn } from "@bpmnkit/core"

const defs = Bpmn.parse(xml)
const process = defs.processes[0]

// Access flow elements
for (const el of process.flowElements) {
  console.log(el.type, el.id, el.name)
}

// Serialize back to XML
const updated = Bpmn.export(defs)

Auto-layout a process

import { Bpmn, layoutProcess } from "@bpmnkit/core"

const defs = Bpmn.parse(xml)
const result = layoutProcess(defs.processes[0])
// result.defs now has updated DI coordinates
const laid = Bpmn.export(result.defs)

Optimize a diagram

import { Bpmn, optimize } from "@bpmnkit/core"

const defs = Bpmn.parse(xml)
const report = optimize(defs)

console.log(`${report.summary.total} findings`)

for (const finding of report.findings) {
  console.log(`[${finding.severity}] ${finding.message}`)
  if (finding.applyFix) {
    const { description } = finding.applyFix(defs)
    console.log("Fixed:", description)
  }
}

Compact format for AI/LLM workflows

import { Bpmn, compactify, expand } from "@bpmnkit/core"

// Shrink for AI prompt
const defs = Bpmn.parse(xml)
const compact = compactify(defs)          // ~70% smaller JSON
const json = JSON.stringify(compact)      // send to LLM

// Restore full BPMN from AI response
const restored = expand(JSON.parse(json))
const outXml = Bpmn.export(restored)

API Reference

BPMN

| Export | Description | |--------|-------------| | Bpmn.parse(xml) | Parse BPMN XML → BpmnDefinitions | | Bpmn.export(defs) | Serialize BpmnDefinitions → XML | | Bpmn.createProcess(id, name?) | Start a ProcessBuilder | | Bpmn.makeEmpty(processId?, name?) | Minimal BPMN XML with one start event | | Bpmn.SAMPLE_XML | 3-node sample diagram string |

DMN

| Export | Description | |--------|-------------| | Dmn.parse(xml) | Parse DMN XML → DmnDefinitions | | Dmn.export(defs) | Serialize → XML | | Dmn.createDecisionTable(id, name?) | Start a DecisionTableBuilder | | Dmn.makeEmpty() | Minimal DMN with one empty decision table |

Form

| Export | Description | |--------|-------------| | Form.create() | Start a FormBuilder | | Form.parse(json) | Parse a form schema | | Form.export(schema) | Serialize → JSON string |

Layout & Optimization

| Export | Description | |--------|-------------| | layoutProcess(process) | Auto-layout all elements; returns LayoutResult | | optimize(defs) | Run all optimization rules; returns OptimizeReport | | compactify(defs) | Convert to compact CompactDiagram | | expand(compact) | Restore full BpmnDefinitions | | generateId(prefix) | Generate a unique short ID |

Related Packages

| Package | Description | |---------|-------------| | @bpmnkit/canvas | Zero-dependency SVG BPMN viewer | | @bpmnkit/editor | Full-featured interactive BPMN editor | | @bpmnkit/engine | Lightweight BPMN process execution engine | | @bpmnkit/feel | FEEL expression language parser & evaluator | | @bpmnkit/plugins | 22 composable canvas plugins | | @bpmnkit/api | Camunda 8 REST API TypeScript client | | @bpmnkit/ascii | Render BPMN diagrams as Unicode ASCII art | | @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/cli | Camunda 8 command-line interface (casen) | | @bpmnkit/proxy | Local AI bridge and Camunda API proxy server | | @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