BPMN SVG Generator

Portable BPMN-to-SVG generator for Kogito-style process diagrams.

This utility is intended to replace ad hoc machine-local scripts with a repo-managed workflow:

• dependencies declared in the utility repo
• no /tmp/... imports
• no hardcoded Chrome path
• Kogito-compatible output under src/main/resources/META-INF/processSVG/<processId>.svg
• explicit generate and verify commands for local use and CI

Status

Initial standalone CLI scaffold with:

• BPMN discovery under src/main/resources
• BPMN process-id extraction
• SVG generation through @kie-tools/kie-editors-standalone
• verification for missing, stale, orphaned, and duplicate outputs
• optional changed-file generation via git diff

Install

npm install

On first render, the tool bootstraps Playwright's managed headless Chromium runtime automatically if it is missing.

If you want to preinstall the browser explicitly, run either of these:

npx bpmn-svg install-browser
npx playwright install chromium

The tool does not require a system Chrome install or a hardcoded Chrome path.

Commands

Generate all BPMN SVGs for a consumer repo:

npx bpmn-svg generate --root /path/to/consumer-repo --all

Generate to a custom output directory:

npx bpmn-svg generate --root /path/to/consumer-repo --all --output-dir /tmp/processSVG

Generate one BPMN file:

npx bpmn-svg generate --input /path/to/consumer-repo/src/main/resources/com/example/process.bpmn2

Generate SVGs only for BPMNs changed from a git base ref:

npx bpmn-svg generate --root /path/to/consumer-repo --changed --base origin/main

Verify coverage and staleness:

npx bpmn-svg verify --root /path/to/consumer-repo

Verify a custom output directory:

npx bpmn-svg verify --root /path/to/consumer-repo --output-dir /tmp/processSVG

CI or Jenkins

Use the same commands in CI:

npm ci
npx bpmn-svg verify --root "$WORKSPACE/engine"

For generation jobs:

npm ci
npx bpmn-svg generate --root "$WORKSPACE/engine" --all

If your CI image is network-restricted during the build step, preinstall the Playwright browser in the image or in an earlier setup step:

npx bpmn-svg install-browser

If CI needs artifacts outside the consumer repo, pass --output-dir:

npx bpmn-svg generate --root "$WORKSPACE/engine" --all --output-dir "$WORKSPACE/generated/processSVG"
npx bpmn-svg verify --root "$WORKSPACE/engine" --output-dir "$WORKSPACE/generated/processSVG"

Set BPMN_SVG_RENDER_TIMEOUT_MS if large diagrams need a longer render timeout.

Release and publish

This repo is set up to publish from GitHub Actions.

Local verification before a release:

npm ci
npm test
npm run pack:check

To publish a new version:

npm version patch
git push origin main --follow-tags

The publish.yml workflow publishes tagged versions to npm. The recommended npm setup is trusted publishing from GitHub Actions, configured once on npmjs.com for:

• GitHub user: karthikeyanga
• Repository: bpmn-svg-generator
• Workflow file: publish.yml

Until trusted publishing is configured on npm, you can switch the workflow to token-based publishing with an NPM_TOKEN repository secret if needed.

Output convention

For BPMN files discovered under:

• src/main/resources/**/*.bpmn
• src/main/resources/**/*.bpmn2

the generated SVG output is:

• src/main/resources/META-INF/processSVG/<processId>.svg

The output filename is based on BPMN processId, not BPMN filename.

Use --output-dir <dir> to override only the output directory. The file name still remains <processId>.svg.

Relative --output-dir values are resolved from the consumer repo root. Absolute paths are used as-is.

The renderer creates short-lived host files in the operating system temp directory and removes them after each render. Repo-local scratch folders such as tmp/ and .tmp/ are ignored by .gitignore.

Verification model

verify checks generated outputs by filename and file freshness. It reports:

• missing SVGs
• stale SVGs
• orphaned SVGs
• duplicate process ids

Intended consumer workflow

This repo is designed to be consumed by engine or workflow repos later via:

• local sibling checkout during early adoption
• npm package publishing later
• Maven wrapper scripts or exec plugin integration
• CI verification steps