Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
diff
✓ import { diff } from 'bpmn-js-differ';
✗ const { diff } = require('bpmn-js-differ');
bpmn-js-differ became an ES module in v3.0.0; CommonJS require() is not supported for versions >= 3.
BpmnModdle
✓ import { BpmnModdle } from 'bpmn-moddle';
✗ const { BpmnModdle } = require('bpmn-moddle');
Required to parse BPMN XML into the definitions object expected by `diff`. bpmn-moddle also switched to ESM.
BpmnJsDifferTypes
✓ import type { Change, Changes } from 'bpmn-js-differ';
Type imports for the output of the diff function are useful for TypeScript users.
This quickstart demonstrates how to use `bpmn-js-differ` to compare two BPMN 2.0 XML strings by first parsing them with `bpmn-moddle` and then feeding the resulting definitions into the `diff` function. It then logs the detected additions, removals, modifications, and layout changes.
import { diff } from 'bpmn-js-differ';
import { BpmnModdle } from 'bpmn-moddle';
// Example BPMN XML strings (replace with your actual diagrams)
const diagramAXML = `<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" id="Definitions_1">
<bpmn:process id="Process_1" isExecutable="false">
<bpmn:startEvent id="StartEvent_1" name="Start"></bpmn:startEvent>
<bpmn:task id="Task_1" name="Original Task"></bpmn:task>
<bpmn:sequenceFlow id="Flow_1" sourceRef="StartEvent_1" targetRef="Task_1"></bpmn:sequenceFlow>
</bpmn:process>
</bpmn:definitions>`;
const diagramBXML = `<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" id="Definitions_1">
<bpmn:process id="Process_1" isExecutable="false">
<bpmn:startEvent id="StartEvent_1" name="Start"></bpmn:startEvent>
<bpmn:task id="Task_1" name="Modified Task"></bpmn:task>
<bpmn:endEvent id="EndEvent_1" name="End"></bpmn:endEvent>
<bpmn:sequenceFlow id="Flow_1" sourceRef="StartEvent_1" targetRef="Task_1"></bpmn:sequenceFlow>
<bpmn:sequenceFlow id="Flow_2" sourceRef="Task_1" targetRef="EndEvent_1"></bpmn:sequenceFlow>
</bpmn:process>
</bpmn:definitions>`;
async function compareBpmnDiagrams(xmlA, xmlB) {
const bpmnModdle = new BpmnModdle();
const { rootElement: definitionsA } = await bpmnModdle.fromXML(xmlA);
const { rootElement: definitionsB } = await bpmnModdle.fromXML(xmlB);
const changes = diff(definitionsA, definitionsB);
console.log('Detected Changes:');
console.log(' Added:', Object.keys(changes._added));
console.log(' Removed:', Object.keys(changes._removed));
console.log(' Changed:', Object.keys(changes._changed));
console.log(' Layout Changed:', Object.keys(changes._layoutChanged));
return changes;
}
compareBpmnDiagrams(diagramAXML, diagramBXML)
.catch(console.error);
Errors
Common errors & fixes
ERR_REQUIRE_ESM
`bpmn-js-differ` v3.0.0+ is an ES module, but you are trying to `require()` it in a CommonJS context.
fixChange `const { diff } = require('bpmn-js-differ');` to `import { diff } from 'bpmn-js-differ';` and ensure your project is configured for ESM. TypeError: Cannot read properties of undefined (reading 'length')
The `diff` function expects valid BPMN definition objects, typically produced by `bpmn-moddle`. This error often occurs when invalid inputs (e.g., `undefined`, raw XML strings, or incorrectly parsed objects) are provided.
fixAlways parse your BPMN XML using `bpmn-moddle` (e.g., `bpmnModdle.fromXML(xml)`) and pass the resulting `rootElement` (definitions) to `diff`.
SyntaxError: The requested module 'bpmn-js-differ' does not provide an export named 'default'
You are attempting a default import (`import BpmnDiffer from 'bpmn-js-differ';`) but the library only provides named exports (specifically `diff`).
fixUse a named import: `import { diff } from 'bpmn-js-differ';`. Audit
Dependencies
bpmn-moddlerequiredRequired to parse BPMN 2.0 XML into definitions, which are the input for bpmn-js-differ.
min-dashrequiredAn internal utility library from bpmn.io, used for various helper functions.