Getting Started

Installation

Global Installation (Recommended)

npm install -g bpmn-txt
# or
pnpm add -g bpmn-txt

Local Installation

npm install bpmn-txt
# or
pnpm add bpmn-txt

Your First Process

Create a file named hello.bpmn.md:

process: hello-world
  name: "Hello World"

  start: begin
    name: "Start"

  task: greet
    name: "Say Hello"
    type: user

  end: finish
    name: "End"

  flow: f1
    from: begin
    to: greet

  flow: f2
    from: greet
    to: finish

Compile to BPMN

bpmn-txt compile hello.bpmn.md

This creates hello.bpmn with full BPMN 2.0 XML including diagram layout.

Validate Without Compiling

bpmn-txt validate hello.bpmn.md

Output:

✓ hello.bpmn.md is valid

Watch Mode

For development, use watch mode to recompile on changes:

bpmn-txt watch hello.bpmn.md

Output Formats

BPMN XML (Default)

bpmn-txt compile hello.bpmn.md -o process.bpmn

JSON

bpmn-txt compile hello.bpmn.md -f json -o process.json

Layout Options

Control the automatic layout direction:

# Left to right (default)
bpmn-txt compile hello.bpmn.md -d RIGHT

# Top to bottom
bpmn-txt compile hello.bpmn.md -d DOWN

# Disable auto-layout
bpmn-txt compile hello.bpmn.md --no-layout

Programmatic Usage

import { parse, validate, toBpmnXmlAsync } from 'bpmn-txt';
import { readFileSync } from 'fs';

const content = readFileSync('hello.bpmn.md', 'utf-8');

// Parse
const { document, errors } = parse(content);
if (errors.length > 0) {
  console.error('Parse errors:', errors);
  process.exit(1);
}

// Validate
const { errors: validationErrors } = validate(document);
if (validationErrors.length > 0) {
  console.error('Validation errors:', validationErrors);
  process.exit(1);
}

// Generate BPMN XML with layout
const xml = await toBpmnXmlAsync(document, {
  layoutOptions: { direction: 'RIGHT' }
});

console.log(xml);

Next Steps