⚡ This new version enriches the plugin system with new lifecycle hooks and aligns the add-ons with bpmn-visualization 0.48.0. ⚡

The Plugin interface now lets plugins react to each BPMN load call and to instance disposal, so plugins can keep their state in sync with the rendered model and release their resources cleanly.

List of issues: milestone 0.10.0

Breaking changes

This version is not compatible with bpmn-visualization 0.47 and older. It requires bpmn-visualization 0.48.0 or higher. See the Minimal version of bpmn-visualization paragraph below and #539.

The main reasons:

• The flowKinds ShapeUtils implementation no longer returns artifacts, see process-analytics/bpmn-visualization-js#3398.
• The dispose method of the add-ons BpmnVisualization class relies on the new dispose capability of the core bpmn-visualization library.
• For more details, see the bpmn-visualization 0.48.0 release notes.

Removal of ShapeUtils

ShapeUtils has been removed from the add-ons. Use the ShapeUtils provided directly by bpmn-visualization instead.

Rename of Plugin.configure to Plugin.onConfigure (#538)

The optional configure method of the Plugin interface has been renamed to onConfigure. This signals that it is a lifecycle hook called by BpmnVisualization after all plugins are constructed, not an API meant to be called by client code. The on prefix follows the common naming convention for framework-invoked lifecycle callbacks.

Plugins implementing configure must rename the method to onConfigure.

Highlights

Minimal version of bpmn-visualization

You must now use bpmn-visualization 0.48.0 or higher with bpmn-visualization-addons. The previous versions worked with bpmn-visualization from 0.42.0 to 0.47.0.

ℹ️ For more details, see #539.

Bundle size impact

Upgrading to bpmn-visualization 0.48.0 increases the total minified size of the bundled dependencies by roughly 33 kB. The sizes below come from the demo build output (the lib-*.js chunks in packages/demo/dist/assets, listed with packages/demo/scripts/list-lib-chunks.sh) and compare each dependency between 0.9.2 and 0.10.0:

Notes:

• As explained in the bpmn-visualization 0.48.0 release notes, most of the increase comes from the fast-xml-parser library and its dependencies.
• These sizes were measured with the default minifier (oxc), which is less efficient than terser at minifying fast-xml-parser. See the bpmn-visualization 0.48.0 release notes for details.

New plugin lifecycle hooks (#540)

The Plugin interface gains new optional hooks, all called by BpmnVisualization and not by client code:

• onBeforeLoad / onLoadSuccess / onLoadError: called on each load call
• onDispose: called when the BpmnVisualization instance is disposed

Reacting to BPMN loading with the load hooks

The onBeforeLoad, onLoadSuccess and onLoadError hooks let a plugin react to each load call, so it can keep its own state in sync with the BPMN model currently rendered. They run around BpmnVisualization.load:

• onBeforeLoad: runs before the new BPMN source is processed, while the previous model is still rendered. Use it to reset state tied to the outgoing model, for example clearing caches, removing overlays or CSS classes, or discarding indexes built from the previous diagram.
• onLoadSuccess: runs after the new model has been rendered. Use it to (re)build state from the freshly loaded diagram, for example indexing elements, registering event listeners, or applying default styles and overlays.
• onLoadError: runs with the thrown error when loading fails, before the error is rethrown to the caller. Use it to roll back any partial work started in onBeforeLoad and to report or log the failure. It does not swallow the error.

load can be called several times on the same instance, so these hooks may run more than once. Make sure work done in onLoadSuccess is cleaned up in a later onBeforeLoad (or in onDispose) to avoid leaking state across loads.

class MyCustomPlugin implements Plugin {
    getPluginId(): string {
        return "my-custom-plugin";
    }

    onBeforeLoad(): void {
        // reset state tied to the previously loaded model
    }

    onLoadSuccess(): void {
        // build state from the freshly loaded model (indexes, listeners, styles, ...)
    }

    onLoadError(error: unknown): void {
        // roll back partial work and report the failure
        console.error("BPMN load failed", error);
    }
}

Cleaning up resources with onDispose

onDispose aligns plugin lifecycle management with the disposal capabilities of the core bpmn-visualization library. Implement it to release everything the plugin acquired, so the BpmnVisualization instance can be garbage collected and no work keeps running after disposal. Typical cleanup includes:

• removing DOM or graph event listeners registered by the plugin;
• clearing timers or intervals (clearTimeout / clearInterval);
• dropping references to the BpmnVisualization instance and to BPMN elements;
• discarding cached data or other internal state held by the plugin.

The hook runs before the core resources are released, so the BpmnVisualization instance and the BPMN model are still accessible if cleanup requires them.

class MyCustomPlugin implements Plugin {
    private readonly intervalId = setInterval(() => this.refresh(), 1000);

    getPluginId(): string {
        return "my-custom-plugin";
    }

    onDispose(): void {
        clearInterval(this.intervalId);
        // remove listeners, drop references and cached state here as well
    }
}

What's Changed

🎉 New Features

• feat: add plugin lifecycle hooks for load and dispose by @tbouffard in #540

📦 Dependency updates

• feat!: support bpmn-visualization 0.48.0 by @dependabot[bot] in #539

⚙️ Other Changes

• chore(demo): split lib chunks and track their sizes by @tbouffard in #521
• refactor!: rename Plugin.configure to Plugin.onConfigure by @tbouffard in #538

Full Changelog: v0.9.2...v0.10.0

NOTE: This release correctly publishes the 0.9.x package to npm and makes it available again.

What's Changed

⚙️ Other Changes

• chore: build with Node 24 by @tbouffard in #504

Full Changelog: v0.9.1...v0.9.2

IMPORTANT NOTES:

• The 0.9.x release line is the latest version compatible with bpmn-visualization 0.47.x.
• Version 0.9.1 has not been published to npm due to a publishing issue.

What's Changed

📝 Documentation

• docs: update description in package.json by @tbouffard in #455
• docs: add CLAUDE.md file by @tbouffard in #501

⚙️ Other Changes

• chore(eslint): convert eslint config to flat config by @csouchet in #376
• chore: mark as compatible with bpmn-visualization prior 0.48.0 by @tbouffard in #502
• ci: publish npm package with trusted publisher by @tbouffard in #503

Full Changelog: v0.9.0...v0.9.1

⚡ This new version adds the ShapeUtil.isFlowNode method to workaround a bug in bpmn-visualization. ⚡

What's Changed

🎉 New Features

• feat: add isFlowNode in ShapeUtil by @tbouffard in #320

📝 Documentation

• docs: fix link to CODE_OF_CONDUCT in README by @tbouffard in #361
• docs: improve the release how-to by @tbouffard in #364
• docs(release): explain the usage of PR labels by @tbouffard in #365

📦 Dependency updates

• chore(deps): bump bpmn-visualization from 0.44.0 to 0.45.0 by @dependabot in #351
• chore(deps): bump bpmn-visualization from 0.45.0 to 0.46.0 by @dependabot in #386

⚙️ Other Changes

• ci: use ubuntu-24.04 by @csouchet in #357
• chore(dependabot): ignore some eslint dependencies by @tbouffard in #372
• style: apply typescript-eslint stylistic rules by @tbouffard in #417

Full Changelog: v0.8.0...v0.9.0

⚡ This new version renames the npm package. ⚡

List of issues: milestone 0.8.0

Breaking changes

Usage

The GitHub repository and npm package have been renamed from bv-experimental-add-ons to bpmn-visualization-addons to better reflect the library's purpose.
ℹ️ For more details on this choice, see #310.

If your application was using the package under its old name (version 0.7.1 or earlier), proceed as follows 👇 :

# first uninstall the old package
npm uninstall @process-analytics/bv-experimental-add-ons
# then install the new package
npm install @process-analytics/bpmn-visualization-addons

Then, update the imports in your application code to use the new package name as follows 👇:

- import {BpmnVisualization} from "@process-analytics/bv-experimental-add-ons";
+ import {BpmnVisualization} from "@process-analytics/bpmn-visualization-addons";

For developers of bpmn-visualization-addons

As the GitHub repository URL has changed, we strongly recommend updating any existing local clones to point to the new repository URL. You can do this by using git remote on the command line:

# using ssh
git remote set-url origin [email protected]:process-analytics/bpmn-visualization-addons.git
# using https
git remote set-url origin https://github.com/process-analytics/bpmn-visualization-addons.git

For more details, see the related GitHub documentation.

What's Changed

📝 Documentation

• docs: use the new bpmn-visualization-addons repository name by @tbouffard in #311
• docs: update SonarCloud badge in README by @tbouffard in #313
• docs(StyleByNamePlugin): mention the match of several elements by @tbouffard in #314

⚙️ Other Changes

• refactor: improve internal types based on SonarCloud feedback by @tbouffard in #315
• refactor!: rename the package to bpmn-visualization-addons by @tbouffard in #316

Full Changelog: v0.7.1...v0.8.0

⚡ This new version makes the usage of bv-experimental-add-ons easier in applications built with webpack. ⚡

List of issues: milestone 0.7.1

🚀 Highlight - application built with webpack

In the past, when integrating bv-experimental-add-ons into an application built by webpack, webpack complained that certain modules could not be found, as in the following example 👇🏿 :

ERROR in ./node_modules/@process-analytics/bv-experimental-add-ons/dist/index.js 16:0-32
Module not found: Error: Can't resolve './bpmn-elements' in '/user/app/node_modules/@process-analytics/bv-experimental-add-ons/dist'
Did you mean 'bpmn-elements.js'?

This was only happening with webpack, not with other bundlers. Webpack expects imports and exports to use the js file extension, which was not the case in older versions of bv-experimental-add-ons.
In version 0.7.1, imports and exports have been updated to make webpack hapyy, so you can too 🎁.

ℹ️ For more details and a workaround for older version, see #301.

What's Changed

🐛 Bug Fixes

• fix(demo): add CSS rules removed by mistake by @tbouffard in #290
• fix: add missing file extension in imports of the npm package by @tbouffard in #301

📦 Dependency updates

• chore(deps): bump bpmn-visualization from 0.43.0 to 0.44.0 by @dependabot in #296

⚙️ Other Changes

• refactor(demo): fetch the BPMN diagrams by @tbouffard in #287
• chore(dependabot): ignore @types/node by @tbouffard in #297
• chore(package): store application resources in the lib folder by @tbouffard in #300
• chore: correctly include the lib folder in the npm package by @tbouffard in #303
• chore(test): switch from ts-jest to @swc/jest by @tbouffard in #302

Full Changelog: v0.7.0...v0.7.1

⚡ Exciting New Features in this Release! ⚡

Check out the full list of issues here: Milestone 0.7.0

🚀 Highlights

🎨 New Plugin: StyleByNamePlugin

In bpmn-visualization, BPMN elements are identified by their unique IDs. However, in some cases (like "Process Discovery"), only the element names are available to applications.

Previously, the BpmnElementsSearcher was introduced to retrieve an element's ID by name, allowing the use of existing bpmn-visualization APIs. With this release, the new StyleByNamePlugin simplifies things! Now, you can directly style elements using their names, mirroring the functionality of StyleRegistry.

Before:

const bpmnVisualization = new BpmnVisualization({
  container: 'bpmn-container',
});

const bpmnElementsRegistry = bpmnVisualization.bpmnElementsRegistry;
const searcher = new BpmnElementsSearcher(bpmnElementsRegistry);

// Update the style of a given element
const bpmnElementId = searcher.getElementIdByName('element-name');
bpmnElementsRegistry.updateStyle(bpmnElementId, styleUpdate);

// Updating the style of multiple elements was even more complex
const bpmnElementIds = searcher.searcher.getElementsByNames(['element-name-1', 'element-name-2'])
                                        .map(bpmnElement => bpmnElement.id);
bpmnElementsRegistry.updateStyle(bpmnElementIds, styleUpdate);

Now:

const bpmnVisualization = new BpmnVisualization({
  container: 'bpmn-container',
  plugins: [StyleByNamePlugin], // register the plugin
});

const styleByNamePlugin = bpmnVisualization.getPlugin<StyleByNamePlugin>('style');

// Update the style of a given element
styleByNamePlugin.updateStyle('element-name', styleUpdate);
// Update the style of multiple elements
styleByNamePlugin.updateStyle(['element-name-1', 'element-name-2'], styleUpdate);

✨ This streamlined approach significantly reduces complexity when working with element names!

📣 More name-based plugins are coming soon: 🎉

• #73
• #74
• #76

🛠️ Introducing Specialized Plugins

This version also introduces several new plugins, breaking down the BpmnElementsRegistry API into focused, interface-specific components:

• CssClassesPlugin mirrors CssClassesRegistry
• OverlaysPlugin mirrors OverlaysRegistry
• StylePlugin mirrors StyleRegistry

These plugins hint at the future direction of bpmn-visualization, where the BpmnElementsRegistry will be split into more specialized APIs.

ℹ️ For further details, visit Issue #77

What's Changed

🎉 New Features

• feat: introduce StyleByNamePlugin by @tbouffard in #281
• feat(demo): demonstrate the style update plugin using BPMN names by @tbouffard in #285
• feat: introduce the StylePlugin by @tbouffard in #286
• feat: introduce CssClassesPlugin by @tbouffard in #288
• feat(type): add guidance to retrieve core plugins by @tbouffard in #289

🐛 Bug Fixes

• fix: add missing ElementsPlugin export by @tbouffard in #280

📝 Documentation

• docs: improve BpmnElementsSearcher documentation by @tbouffard in #221

⚙️ Other Changes

• chore(dev): build with Node 20 by @tbouffard in #271
• refactor(demo): reorganize CSS by @tbouffard in #284

Full Changelog: v0.6.1...v0.7.0

⚡ This new version includes internal changes, in particular improvements that apply to the demo. ⚡

List of issues: milestone 0.6.1

What's Changed

🎉 New Features

• feat(demo): improve zoom control buttons by @tbouffard in #186

⚙️ Other Changes

• chore: update the script to develop the demo by @tbouffard in #166
• ci: add "actions" permissions to fix GH Pages deploy by @tbouffard in #194
• ci: automate the initialization of GitHub release by @tbouffard in #198
• refactor: simplify listener declaration in OverlayPlugin demo by @tbouffard in #201

Full Changelog: v0.6.0...v0.6.1

⚡ This new version improves the plugins and BpmnElementsSearcher. ⚡

List of issues: milestone 0.6.0

Highlights

Minimal version of bpmn-visualization

You must now use bpmn-visualization 0.42.0 or higher with bv-experimental-add-ons. The previous version required bpmn-visualization 0.40.0 or higher.

ℹ️ For more details, see #155.

Plugin are now configurable

The plugins can now be configured by passing options at BpmnVisualization initialization.

Previously, the plugins must be configured by calling a method. This is now easier and consistent with the rest of the library.

New ElementsPlugin plugin

This new version introduces the ElementsPlugin, which exposes the bpmn-visualization API methods that retrieve elements from the model.
This is the first step of an initiative that will provide all methods of BpmnElementsRegistry via plugins.

ℹ️ For more details, see #77

New CasePathResolver

This new class is dedicated to path resolution of a single instance/case of a process, while the existing PathResolver is for general resolution.

Given a set of elements considered as completed, it is currently able to compute the edges between the provided shapes and the shapes around the provided edges.
It is also able to consider completed and pending elements both in the input parameter and in the inferred path.

This is the first step towards the implementation of more intelligent computing in the future.

ℹ️ For more details, see #142

More options for BpmnElementsSearcher

BpmnElementsSearcher allows you to retrieve elements by providing their name.

Previously, it provided only one method, which returned the identifier of the element concerned. In many cases, the need is to retrieve the complete model object, not just its identifier. An additional call to the API was then necessary to obtain the complete object.

BpmnElementsSearcher now provides a new method that retrieves the complete element from the model. In addition, it allows you to choose how deduplication is performed if 2 or more elements match the name provided.

What's Changed

🎉 New Features

• feat: enable diagram navigation in the "Overlays" demo by @tbouffard in #135
• feat: introduce ElementsPlugin by @tbouffard in #139
• feat(BpmnElementsSearcher): provide options to deduplicate elements by @tbouffard in #131
• feat(BpmnElementsSearcher): add a new method to get all elements by name by @tbouffard in #134
• feat: introduce CasePathResolver by @tbouffard in #142
• feat: add a way to configure plugins by @tbouffard in #159

📝 Documentation

• docs: present the library as less "experimental" than before by @tbouffard in #160

⚙️ Other Changes

• style: apply unicorn/recommended rules by @tbouffard in #127
• chore(eslint): lint imports with eslint-plugin-import by @tbouffard in #140
• refactor(plugin): remove wrong comment by @tbouffard in #141
• refactor(path): let bpmn-visualization filters duplicates by @tbouffard in #155

Full Changelog: v0.5.0...v0.6.0

⚡ This new version improves BpmnElementsSearcher and PathResolver. ⚡

List of issues: milestone 0.5.0

Minimal version of bpmn-visualization

You must now use bpmn-visualization 0.40.0 or higher with bv-experimental-add-ons. The previous versions required bpmn-visualization 0.39.0 or higher.

What's Changed

🎉 New Features

• feat: allow to find flows when searching by name by @tbouffard in #118
• feat: improve the robustness of PathResolver by @tbouffard in #119
• feat: detect message flows with PathResolver by @tbouffard in #120
• feat: expose bpmn-visualization methods in OverlaysPlugin by @tbouffard in #123

📝 Documentation

• docs: add emoji in "other changes" paragraph of the release notes by @tbouffard in #116

📦 Dependency updates

• chore(deps): bump bpmn-visualization from 0.39.0 to 0.40.0 by @dependabot in #125

⚙️ Other Changes

• chore(eslint): add ESLint configuration for Jest by @csouchet in #108

Full Changelog: v0.4.0...v0.5.0