bpmnlint

library11.12.1jsnpmunverified

bpmnlint is a BPMN diagram validation tool that checks diagrams against configurable lint rules. Current stable version is 11.12.1, with regular releases (approximately every few weeks). It supports BPMN 2.0 diagrams and provides multiple built-in configuration sets: 'recommended', 'correctness', and 'all'. Key differentiators include its focus on BPMN compliance, extensibility via custom plugins, moddle extension support for custom BPMN extensions, and both CLI and programmatic API usage. It integrates with bpmn-moddle for diagram parsing and is designed for process modelers and developers in BPMN-based workflows.

testing workflow devops

npm install bpmnlint

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BPMNLINT

bpmnlint

testingjavascriptv11.12.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Linter

✓ import Linter from 'bpmnlint';

✗ const Linter = require('bpmnlint');

bpmnlint uses default export; CommonJS require() is not supported in ESM-first environments. Since v10 the package is ESM-only.

NodeResolver

✓ import NodeResolver from 'bpmnlint/lib/resolver/node-resolver';

✗ import { NodeResolver } from 'bpmnlint';

NodeResolver is a named export from internal module, not from the main package. Must import from the specific path.

Linter

✓ import Linter from 'bpmnlint';

✗ import Linter from 'bpmnlint'; // correct

Default import is the only way; there is no named Linter export.

Shows how to programmatically lint a BPMN diagram using the bpmnlint API with a recommended config and NodeResolver.

import Linter from 'bpmnlint'; import NodeResolver from 'bpmnlint/lib/resolver/node-resolver'; import BpmnModdle from 'bpmn-moddle'; const moddle = new BpmnModdle(); const linter = new Linter({ config: { extends: 'bpmnlint:recommended' }, resolver: new NodeResolver() }); const xmlStr = ` <?xml version="1.0" encoding="UTF-8"?> <bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" id="definitions" targetNamespace="http://bpmn.io/schema/bpmn"> <bpmn:process id="process" /> </bpmn:definitions> `; const { rootElement: definitions } = await moddle.fromXML(xmlStr); const results = await linter.lint(definitions); console.log(JSON.stringify(results, null, 2));

bpmnlint --version

Debug

Known issues

breakingESM-only since v10: bpmnlint v10+ is pure ESM and cannot be imported via require().

fix

Switch to ES module imports: use `import Linter from 'bpmnlint'` and ensure your project is configured for ESM.

affects: >=10.0.0

deprecatedConfig format deprecated: older `.bpmnlintrc` files using `plugins` array should migrate to `extends` pattern.

fix

Use `extends: 'bpmnlint:recommended'` instead of directly listing plugins.

affects: >=8.0.0

gotchaNodeResolver must be imported from internal path: import { NodeResolver } from 'bpmnlint' does not work.

fix

Use `import NodeResolver from 'bpmnlint/lib/resolver/node-resolver';`

affects: all

gotchaModdle extensions resolution: extensions defined in config are resolved relative to the config file, not the working directory.

fix

Use absolute paths or ensure the moddle extension file is relative to the config file.

affects: all

Errors

Common errors & fixes

Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'bpmnlint'

Using require() instead of import in an ESM-only package.

fix

Replace const Linter = require('bpmnlint') with `import Linter from 'bpmnlint'`.

Cannot destructure property 'NodeResolver' of ... is not iterable

Importing NodeResolver as a named export from 'bpmnlint'.

fix

Use default import from 'bpmnlint/lib/resolver/node-resolver': `import NodeResolver from 'bpmnlint/lib/resolver/node-resolver'`.

No configuration found for bpmnlint

Missing or misconfigured .bpmnlintrc file.

fix

Create a .bpmnlintrc file in your project root with at least `extends: 'bpmnlint:recommended'`.

Upgrade

Version history

11.12.1latest on npm

Audit

Dependencies

bpmn-moddlerequiredRequired for parsing BPMN XML into a moddle model for validation.

moddlerequiredCore modeling framework used by bpmn-moddle.

moddle-xmlrequiredUsed for reading and writing moddle objects from XML.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bpmn-io/bpmnlint ↗

packagehttps://www.npmjs.com/package/bpmnlint ↗

homepagehttps://bpmn.io/toolkit/bpmnlint/ ↗