JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 24
  • Score
    100M100P100Q10468F
  • License MIT

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

Package Exports

  • @bpmn-sdk/core

Readme

BPMN SDK logo

@bpmn-sdk/core

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

npm license typescript

Documentation · GitHub · Changelog


Overview

@bpmn-sdk/core is the foundation of the BPMN SDK. 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 @bpmn-sdk/core
pnpm add @bpmn-sdk/core

Quick Start

Build a process from code

import { Bpmn } from "@bpmn-sdk/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 "@bpmn-sdk/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 "@bpmn-sdk/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 "@bpmn-sdk/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 "@bpmn-sdk/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

Package Description
@bpmn-sdk/canvas Zero-dependency SVG BPMN viewer
@bpmn-sdk/editor Full-featured interactive BPMN editor
@bpmn-sdk/engine Lightweight BPMN process execution engine
@bpmn-sdk/feel FEEL expression language parser & evaluator
@bpmn-sdk/plugins 22 composable canvas plugins
@bpmn-sdk/api Camunda 8 REST API TypeScript client
@bpmn-sdk/ascii Render BPMN diagrams as Unicode ASCII art
@bpmn-sdk/profiles Shared auth, profile storage, and client factories for CLI & proxy
@bpmn-sdk/operate Monitoring & operations frontend for Camunda clusters

License

MIT © bpmn-sdk