BPMN.js Differ

Common errors

• ERR_REQUIRE_ESM

  cause `bpmn-js-differ` v3.0.0+ is an ES module, but you are trying to `require()` it in a CommonJS context.
  fix Change `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')

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

  cause You are attempting a default import (`import BpmnDiffer from 'bpmn-js-differ';`) but the library only provides named exports (specifically `diff`).
  fix Use a named import: `import { diff } from 'bpmn-js-differ';`.

Warnings

• breaking Starting with version 3.0.0, `bpmn-js-differ` is distributed as an ES module (ESM) only. This means that `require()` statements for CommonJS environments will no longer work and must be replaced with `import` syntax.
  Fix: Migrate your module loading to `import { diff } from 'bpmn-js-differ';`. If using Node.js, ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).
• breaking Version 3.0.0 introduced a fundamental change by building the diffing logic on top of `bpmn-moddle`'s infrastructure. While the public `diff` function signature generally remained stable, this change mandates the use of `bpmn-moddle` (specifically version 9.0.0 or higher) to parse BPMN XML into the expected definition objects. Directly passing raw XML strings or objects from older parsing utilities will not work.
  Fix: Ensure you are using `bpmn-moddle` (preferably its latest major version, currently 10.0.0+) to parse your BPMN XML into definition objects before passing them to `diff`.
• gotcha Prior to version 3.0.1, `bpmn-js-differ` might not have reliably detected changes to an element's `$type` property. For example, changing a `bpmn:Task` to a `bpmn:ServiceTask` might have been missed or incorrectly reported.
  Fix: Upgrade to `bpmn-js-differ@3.0.1` or newer to ensure accurate detection of `$type` changes.

Install

• npm install bpmn-js-differ npm
• yarn add bpmn-js-differ yarn
• pnpm add bpmn-js-differ pnpm

Imports

• diff
  wrong:

  const { diff } = require('bpmn-js-differ');

  correct:

  import { diff } from 'bpmn-js-differ';

  bpmn-js-differ became an ES module in v3.0.0; CommonJS require() is not supported for versions >= 3.
• BpmnModdle
  wrong:

  const { BpmnModdle } = require('bpmn-moddle');

  correct:

  import { BpmnModdle } from '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.

Quickstart

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