[INFRA] Evaluate the Replacement of `mxGraph` with a New Library

[tbouffard]

Overview

The bpmn-visualization project currently relies on mxGraph for rendering. However, mxGraph was declared end-of-life on November 9, 2020 (see the mxGraph End-of-Life Announcement). To ensure the project's sustainability and maintainability, it is crucial to replace mxGraph with a new library.
In addition, typed-mxgraph, the npm package adding TypeScript support to mxGraph, is no longer supported as well as of January 21, 2025. See the commit mentioning the archived state.

Current Risks

Features incompatible with new browser versions

As mentioned in the mxGraph README:

Over time you can expect this codebase will break features against new browser releases, it's not advised to start new projects against this codebase for that reason.

Known mxGraph vulnerabilities

Switching to a new library will also remove exposure to mxGraph vulnerabilities.

mxTooltipHandler.show contains a cross-site scripting (XSS) vulnerability made public in October 2022:

• https://www.cve.org/CVERecord?id=CVE-2022-40440
• https://security.snyk.io/vuln/SNYK-JS-MXGRAPH-3043010

bpmn-visualization does not activate the tooltip functionality, so it is not affected by this vulnerability. However, applications including bpmn-visualization are notified of this issue. This could scare people away from using the library, especially as the vulnerability will not be fixed.

Selection Criteria for a New Library

Organizational Requirements

• Open Source License: The library should have a permissive license, such as Apache 2.0 or MIT, to ensure no restrictions on the commercial or free software usage of bpmn-visualization.

• Community-Driven Development: The library must not be controlled by a single entity that could discontinue it unexpectedly as it happens with mxGraph.

• Active Maintenance: Ideally, the library should have multiple maintainers. If there is only one maintainer, the Process Analytics and/or Bonitasoft teams should be able to contribute to its development (as maintainers of the project) to drive the development and ensure that new requirements and bugs can be solve when needed by bpmn-visualization.

• Ease of Contribution: It should be straightforward to contribute fixes or improvements. Pull requests should be welcomed and merged in a timely manner, indicating an open and active contribution process.

• Broad Community Base: The library should have a large and active community of users and contributors, fostering diverse perspectives and reducing reliance on a small core team. While GitHub stars may indicate popularity, they are not always a reliable metric for assessing community engagement.

Features and Technical Requirements

• Native TypeScript Support: The library should natively support TypeScript to align with modern development practices.

• ES6 Module Support: Compatibility with ES6 modules for a streamlined integration with modern JavaScript environments.

• Internal Model Support: The library should have an internal model built on top of its drawing capabilities to simplify customization and interaction management.

• Quality and Testability: High-quality code with a focus on testability, making it easier for contributors to add features or fix issues effectively.

• Lightweight with Tree Shaking Support: The library should be as small as possible and support tree shaking to remove unused code. If tree shaking is not supported, it should be on the library's development roadmap.

  • Libraries often include editing features that are unnecessary for bpmn-visualization; these features should be easily removable.
  • the mxGraph library is not tree-shakable and is then fully imported/bundled in applications. The size of the mxGraph minified bundle is around 811kB. The new library should be much smaller than that, i.e. its participation to the overall size of an application should be smaller than mxGraph, thanks to tree-shaking capabilities.

• Feature Parity: The library must provide at least the same features as mxGraph to avoid regressions in functionality.

• Extensibility: The library should be as extensible as mxGraph, enabling future enhancements and customizations.

Potential Candidates

Below is a non-exhaustive list of potential libraries to evaluate. Detailed analyses will be carried out in dedicated sub-issues.

Under evaluation

• maxGraph: A fork of mxGraph with a similar API and context. [INFRA] Evaluate the Replacement of mxGraph with maxGraph #3238

Fully evaluated

Rejected:

• JointJS: A proven SVG-based JavaScript diagramming library powering exceptional UIs [INFRA] Evaluate the Replacement of mxGraph with JointJS #3315

To evaluate

• G6: A graph visualization library with rich features.
• diagram-js
  • power bpmn-js
  • 1822 stars on 2025-08-04
  • Size small: the bpmn-js viewer that uses it is small (about 200kB)
  • Topics to investigate:
    • for the model, use the moddle lib, bpmn-modle lib exists and is used by bpmn-js. If we use this stack, what is the differentiator with bpmn-js
    • TS support: diagram-js written in JS, provides TS definition (at least since the beginning of 2025). To validate if this is usable
    • Overlays: provide support for full custom overlays. Check if we can replicate what we currently have in SVG
    • Shape: defined in pure SVG, no abstraction. BPMN Shapes have been created in bpmn-js

Possible candidates

• Two.js: https://two.js.org/
• Logic Flow: A library with BPMN support. Documentation available at Logic Flow BPMN Extension