Objectives

This issue, a subtask of #3237 , aims to assess the feasibility and implications of replacing mxGraph with maxGraph.

The findings will support informed decisions regarding the viability and benefits of a full migration. This evaluation also aims to deliver actionable insights and establish a strong foundation for a potential transition to maxGraph.

Background

maxGraph is fork of mxGraph with a similar API and context.

Organizational Requirements

• maxGraph is a community-driven open-source project (Apache 2.0) with limited active maintainers.
• Two contributors involved in the initial migration from mxGraph have been inactive since January 2022.
• Process Analytics (PA) maintainers have control over the maxGraph codebase.
• Currently, I (@tbouffard) am the sole active maintainer, with occasional external contributions.
• Despite calls for contributors (e.g., #354), engagement has been minimal.

Popularity

• maxGraph has 857 stars on GitHub as of January 8, 2025.
• A few questions and issues are posted monthly, reflecting ongoing use.
• npm downloads are relatively low, averaging between 500 and 1,000 per week.

Features and Technical Requirements

• maxGraph, as a fork of mxGraph, retains feature parity (including similar extension points) with its predecessor.
• It includes additional functionalities, such as features added directly by bpmn-visualization (e.g., color fill for arrow markers on edges).
• Native TypeScript / ES6 Module Support: maxGraph is written in TypeScript and its npm package provides ESM JavaScript files. It also provides CommonJS file as of version 0.20.0 which eases integration in tests (we use Jest with CommonJS), without requiring any configuration change.
• Internal Model Support: it is the same or almost the same model as in mxGraph.
• Quality and Testability: mxGraph had no automatic tests at all. The codebase was targeting ES5, using old code patterns
  • Tests are added progressively to maxGraph. On 2025-02-04, there were 143 tests covering 29.21% ( 7109/24334 ) of statements
  • The code quality is tracked with SonarQube cloud
• Lightweight with Tree Shaking Support:
  • The initial maxGraph release removed support for Internet Explorer and removed custom code that could be replaced by new ECMAScript API. These removal reduced the final size of the lib comparing to mxGraph
  • Since the initial release, the tree-shaking support has been improved, and further enhancements are planned (see Strategies for Further Tree-Shaking Improvements maxGraph/maxGraph#665). Main enhancements already available:
    • https://github.com/maxGraph/maxGraph/releases/tag/v0.6.0: Codecs no longer registered by default
    • https://github.com/maxGraph/maxGraph/releases/tag/v0.11.0: MaxLog is no longer called directly in the maxGraph code, and neither is MaxWindow, which was included transitively.
    • https://github.com/maxGraph/maxGraph/releases/tag/v0.12.0: npm package declared without side effects

Overall Status of the Evaluation

maxGraph meets almost all the criteria defined for selecting a suitable candidate.

The only concern lies with the community: maxGraph appears to have limited adoption, and there are no active maintainers outside of the Process-Analytics project and Bonitasoft.

However, the maintainers of bpmn-visualization could also become maintainers of maxGraph, enabling them to apply necessary fixes and introduce new features to meet the needs of bpmn-visualization.

Given these factors, maxGraph could serve as at least a short-to-medium-term solution to mitigate risks.

Additionally, since maxGraph's API is very similar to mxGraph, the migration effort would be significantly lower compared to a complete rewrite using an entirely new rendering library.

Technical Evaluation

The latest Proof of Concept (POC) is available in #3340 (see the "Evaluation Followup" paragraph).

• All features have been successfully restored, and both unit and integration tests are passing.
• All unit and integration tests are passing.
• Tests of the npm package are passing.
• Over 75% of the e2e tests are passing consistently. The remaining test failures require further review. Minor discrepancies have been observed in the rendering of dashed strokes, which might be linked to unintended changes introduced in maxGraph during the migration from mxGraph.
• Several potential improvements have been identified but were not implemented yet, as they depend on stable end-to-end (E2E) test results to ensure no regressions are introduced.
• All critical issues identified in maxGraph have been addressed in version 0.10.3 (including implementation and type definitions).

As part of this evaluation, we contributed to the maxGraph project by opening more than 15 issues and pull requests, along with enhancements to their documentation.
Some customization/extensions of maxGraph used in bpmn-visualization have been contributed to maxGraph. This reduces the custom code in the library and reduces its final size. This also reduces the maintenance as maxGraph is now responsible of the related code.

Purpose of the Evaluation

1. Assess Migration Effort: Determine the complexity and time required for migration.
2. Detect Problems Early: Identify potential issues and blockers ahead of the migration.
3. Enhance the Codebase: Apply improvements to the master branch to simplify future migrations and strengthen tests.
4. Support the maxGraph Community: Provide feedback and propose fixes for issues encountered during the evaluation.
5. Reusability: Ensure that the effort can be reused in future pull requests to test new maxGraph releases.

Scope

• The evaluation will focus solely on code analysis.
• It will not include migrating the existing bpmn-visualization documentation referencing mxGraph.
• Pull requests will be created to test new maxGraph releases as they become available and as the bpmn-visualization code evolves.
• A summary of the latest pull request’s status will be documented here, along with a list of all pull requests made during the evaluation.

Evaluation Followup

In the code, the parts of the code that could be improved or that require changes are mark using "TODO" following this convention: // TODO maxgraph (the case of maxgraph may vary)

Created Pull Requests

• Coming maxGraph 0.20.0 (bpmn-visualization latest)
• refactor: [POC] Replace mxGraph with maxGraph 0.20.0 #3340 (bpmn-visualization 0.37.0)
• refactor: [POC] Replace mxGraph with maxGraph 0.15.1 #3270 (bpmn-visualization 0.37.0)
• refactor: [POC] Replace mxGraph with maxGraph 0.10.3 #3098 (bpmn-visualization 0.37.0)
• refactor: [POC] investigate replacement of mxGraph by [email protected] (2nd attempt) #2756 (bpmn-visualization 0.37.0)
• refactor: [POC] Replace mxGraph with maxGraph 0.1.0 #2366 (bpmn-visualization 0.28.2)

Bundle sizes comparison

Notes:

• demo chunk: the demo involves additional mxGraph/maxGraph code for the SVG Exporter (it uses the ImageExport API). As a result, this chunk is larger than the chunk in an application integrating bpmn visualization in a standard way.
• ESM bundle: it only includes the code of bpmn-visualization. api-extractor removes all comments from the code before generating this bundle, so the size of the bundle is a good indicator of the impact of migration on the amount of code needed to interact with mxGraph or maxGraph.

bpmn-visualization 0.37.0 with various maxGraph versions (in progress)

POC where done from master e8fa907 (0.37.0 with dev dependencies update only)

bpmn-visualization 0.28.2 with maxGraph 0.1.0
See #2366 (comment)