Agents: read node_modules/@bpmnkit/core/AGENTS.md, then node_modules/@bpmnkit/core/agent-cards/<bpmn|dmn|form>.md (~1k tokens) instead of this README.

@bpmnkit/core

TypeScript-first BPMN 2.0 SDK — parse, build, layout, and optimize diagrams

Website · Documentation · GitHub · Changelog

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

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
• Connector catalog — all Camunda 8 out-of-the-box connector templates, applied deterministically (@bpmnkit/core/connectors)
• 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

Every element takes (id, options). Branches off a gateway are declared with .branch(), not by wiring flows by hand — the builder creates the sequence flows.

import { Bpmn } from "@bpmnkit/core"

const defs = Bpmn.createProcess("order-flow")
  .name("Order Flow")
  .startEvent("start", { name: "Order Received" })
  .serviceTask("validate", {
    name: "Validate Order",
    taskType: "order-validator",
    ioMapping: {
      inputs: [{ source: "=order", target: "order" }],
      outputs: [{ source: "=valid", target: "isValid" }],
    },
  })
  .exclusiveGateway("check", { name: "Order Valid?" })
  .branch("valid", (b) =>
    b
      .condition("=isValid = true")
      .serviceTask("fulfill", { name: "Fulfill Order", taskType: "fulfillment-service" })
      .endEvent("end", { name: "Order Complete" }),
  )
  .branch("invalid", (b) =>
    b.defaultFlow().endEvent("reject-end", { name: "Order Rejected" }),
  )
  .withAutoLayout()
  .build()

const xml = Bpmn.export(defs)

Sub-processes, boundary events and multi-instance

These are the constructs most often reached for and most often guessed at, so the exact shapes are worth stating. subProcess takes its body as a callback (second argument) and options third. A boundary event needs the id of the activity it attaches to; withBoundary supplies it from the preceding activity for you.

import { Bpmn } from "@bpmnkit/core"

const defs = Bpmn.createProcess("fulfilment")
  .name("Fulfilment")
  .startEvent("start")

  // Sub-process: id, content callback, then options.
  // multiInstance runs the body once per item in the collection.
  .subProcess(
    "provision",
    (sub) => {
      sub
        .startEvent("p-start")
        .serviceTask("provision-line", { name: "Provision Line", taskType: "provision" })
        .endEvent("p-end")
    },
    {
      name: "Provision Each Line",
      multiInstance: { collection: "=order.lines", elementVariable: "line", isSequential: false },
    },
  )

  // withBoundary attaches to the activity just added — no id repeated.
  .serviceTask("charge", { name: "Charge Payment", taskType: "payment" })
  .withBoundary("charge-failed", { errorCode: "PAYMENT_FAILED" }, (b) => {
    b.serviceTask("retry-charge", { name: "Retry Charge", taskType: "payment" }).endEvent("gave-up")
  })

  // Wait for whichever event arrives first.
  .eventBasedGateway("await-payment", { name: "Paid?" })
  .branch("paid", (b) =>
    b
      .intermediateCatchEvent("payment-confirmed", {
        messageName: "PaymentConfirmed",
        correlationKey: "=orderId",
      })
      .endEvent("done"),
  )
  .branch("timeout", (b) =>
    b.intermediateCatchEvent("payment-timeout", { timerDuration: "P14D" }).endEvent("written-off"),
  )
  .withAutoLayout()
  .build()

Attach a boundary event explicitly when it is not the preceding activity — both forms below are accepted, and a boundary event with no host throws rather than exporting BPMN that cannot be read back:

.boundaryEvent("timeout", { attachedTo: "charge", timerDuration: "PT30M" })
.boundaryEvent("timeout", "charge", { timerDuration: "PT30M" })

Event definitions are named options, not nested objects — timerDuration, timerDate, timerCycle, messageName (with correlationKey), errorCode, signalName, compensation. An option the builder does not know is dropped silently, so timer: { duration: "P7D" } produces a boundary event with no timer on it.

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 { applyAutoLayout, Bpmn } from "@bpmnkit/core"

// Lays out every process and writes the diagram interchange back onto the model.
const laid = Bpmn.export(applyAutoLayout(Bpmn.parse(xml)))

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)

Rendering while the model is still writing

A model emits a diagram one token at a time, and the outermost } — the one JSON.parse waits for — is the last character it sends. createCompactStream reads the elements out of the text as their own literals close, so there is something to draw long before the document is finished:

import { createCompactStream } from "@bpmnkit/core"

// `base` is the diagram being edited, so a frame shows the whole thing rather
// than the fragment the model is adding to it. Omit it to build from nothing.
const diagramStream = createCompactStream({ base: null })

function onModelChunk(chunk: string): void {
  const frame = diagramStream.push(chunk) // null until the frame changes
  if (frame) console.log("elements so far:", frame.processes[0]?.flowElements.length)
}

Frames are a guess at an unfinished document: push never throws, drops what it cannot place, and expects the caller to have an authoritative result coming.

API Reference

BPMN

Process builder

Every element method is (id, options) and returns the builder. The same methods exist inside .branch() and inside a sub-process body.

Event definitions are options on the element: timerDuration, timerDate, timerCycle, messageName + correlationKey, errorCode, signalName, compensation. Multi-instance is options.multiInstance = { collection, elementVariable, isSequential? }.

Semantics

Typed code generation

Editing

Writing files (@bpmnkit/core/node)

import { writeBpmn } from "@bpmnkit/core/node"

// Refuses rather than overwrite; pass force: true to replace.
const { semanticHash, changes } = await writeBpmn(defs, { output: "flow.bpmn" })

Connectors (@bpmnkit/core/connectors)

The Camunda 8 out-of-the-box connector catalog, behind its own subpath so its data is only bundled by code that imports it. The templates leave out icons, groups, tooltips and placeholders; @bpmnkit/connectors adds those back for a property panel.

import { applyConnectorTemplate } from "@bpmnkit/core/connectors"

const { serviceTask, problems } = applyConnectorTemplate("io.camunda.connectors.HttpJson.v2", {
  url: "https://api.example.com/orders",
})

DMN

Form

Layout & Optimization

Process documentation

options takes decisions (DmnDefinitions[]), forms (FormDefinition[]), title, subtitle and diagram. Output is deterministic and all model text is escaped.

Related Packages

License

MIT © BPMN Kit — made by u11g