@bpmn-sdk/ascii

Render BPMN diagrams as Unicode box-drawing ASCII art — perfect for terminals and docs

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

License

MIT © bpmn-sdk