Documentation · GitHub · Changelog

Overview

@bpmn-sdk/ascii converts BPMN 2.0 diagrams into Unicode box-drawing text art. It uses the same Sugiyama layout engine as the visual renderer, so the spatial flow of the diagram is preserved.

Useful for: CLI output, plain-text documentation, terminal UIs, test snapshots, and LLM prompts where visual BPMN isn't available.

Features

• Unicode box-drawing — ┌─┐, │, └─┘, → for clean terminal output
• Automatic layout — uses @bpmn-sdk/core's layout engine
• All element types — tasks, events, gateways, sub-processes
• Configurable output — optional title, element type labels
• Zero additional dependencies — only requires @bpmn-sdk/core (already bundled)

Installation

npm install @bpmn-sdk/ascii

Quick Start

import { renderBpmnAscii } from "@bpmn-sdk/ascii"
import { readFileSync } from "node:fs"

const xml = readFileSync("my-process.bpmn", "utf8")
const art = renderBpmnAscii(xml, { title: true, showTypes: true })
console.log(art)

Example output

Order Flow
══════════════════════════════════════════════
  ╭──────────╮     ╭───────────────╮     ╭╮
  │  Order   │────▶│ Validate Order│────▶││
  │ Received │     │ (ServiceTask) │     │◇│
  ╰──────────╯     ╰───────────────╯     ╰╯
                                          │
                         ╭───────────────╯│╰───────────────╮
                         ▼                                  ▼
                   ╭───────────╮                    ╭──────────────╮
                   │  Fulfill  │                    │    Reject    │
                   │   Order   │                    │    Order     │
                   ╰───────────╯                    ╰──────────────╯

API Reference

function renderBpmnAscii(xml: string, options?: RenderOptions): string

interface RenderOptions {
  title?: boolean     // Show process name as header. Default: false
  showTypes?: boolean // Include element type in boxes. Default: false
}

Related Packages

| Package | Description | |---------|-------------| | @bpmn-sdk/core | BPMN/DMN/Form parser, builder, layout engine | | @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/profiles | Shared auth, profile storage, and client factories for CLI & proxy | | @bpmn-sdk/operate | Monitoring & operations frontend for Camunda clusters |

License

MIT © bpmn-sdk