Skip to content

[INFRA] Evaluate the Replacement of mxGraph with maxGraph #3238

New issue
New issue
Open
Task
#3414
Open
[INFRA] Evaluate the Replacement of mxGraph with maxGraph#3238
Task
#3414
Labels
mxgraph integrationSomething involving mxGraph (be aware of EOL)
Milestone
0.48.0
@tbouffard

Description

@tbouffard
tbouffard
opened on Jan 8, 2025

Important

This is an in-progress evaluation, some information presented here are out-of date and must be updated.

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:

Overall Status of the Evaluation

Important

This is an ongoing evaluation, not a final decision. The technical evaluation is still in progress.

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

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)

Bundle mxGraph 4.2.2 maxGraph 0.1.0 maxGraph 0.10.3 maxGraph 0.15.0 maxGraph 0.15.1 maxGraph 0.20.0
IIFE raw 1 669 729 1 466 189 1 249 348 1 207 959 1 207 989 952 642
IIFE minified 984 186 703 551 604 940 586 176 586 120 467 796
ESM (lib code only) 198 486 195 232 194 144 194 144 194 144 193 623
Demo chunk 818 KB 563.29 kB 466.12 kB 447.69 kB 447.63 kB 329.66 kB

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

Bundle 0.28.2 maxGraph 0.1.0
IIFE raw 2 913 702 2 409 834
IIFE minified 982 368 699 072

Metadata

Metadata

Assignees

No one assigned

    Labels

    mxgraph integrationSomething involving mxGraph (be aware of EOL)

    Type

    Task

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions