bpmnlint

11.12.1 verified Fri May 01 auth: no javascript

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.

Common errors

error Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'bpmnlint' ↓

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

fix

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

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

cause 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'.

error No configuration found for bpmnlint ↓

cause Missing or misconfigured .bpmnlintrc file.

fix

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

Warnings

breaking ESM-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.

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

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

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

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

gotcha Moddle 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.

Install

npm install bpmnlint

yarn add bpmnlint

pnpm add bpmnlint

Imports

Linter
wrong
```
const Linter = require('bpmnlint');
```
correct
```
import Linter from 'bpmnlint';
```
bpmnlint uses default export; CommonJS require() is not supported in ESM-first environments. Since v10 the package is ESM-only.
NodeResolver
wrong
```
import { NodeResolver } from 'bpmnlint';
```
correct
```
import NodeResolver from 'bpmnlint/lib/resolver/node-resolver';
```
NodeResolver is a named export from internal module, not from the main package. Must import from the specific path.
Linter
wrong
```
import Linter from 'bpmnlint'; // correct
```
correct
```
import Linter from 'bpmnlint';
```
Default import is the only way; there is no named Linter export.

Quickstart

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));