Skip to content

Consider adding CommonJS support in the npm package #824

@tbouffard

Description

@tbouffard

Is your feature request related to a problem? Please describe.

Currently (as of v0.19.0), the maxGraph npm package only provides ES modules.

CommonJS support was removed in v0.5.0. At that time, it was only provided as a single bundle file (UMD).

But several users have reported issues when using maxGraph in environments where CommonJS is still the default. For example:

In applications with large Jest-based test suites written in CommonJS, just adding maxGraph forces a full migration to ESM, which can be a major blocker.

➡️ Example: In bpmn-visualization, migrating from mxGraph to maxGraph required updating 3,000+ test and helper files. See PR #3098.

Another use case: headless SVG rendering using Node.js and jsdom (see #761). While Node supports ESM, some apps are still built in CommonJS — which currently prevents using maxGraph at all.

Describe the solution you'd like

Publish a dual ESM + CJS build in the npm package, including types if necessary.

This would help:

  • Use maxGraph in test environments like Jest (via ts-jest or pure JS)
  • Use maxGraph headlessly in Node.js (e.g., SVG export)

Additional context

Here are some dual-build strategies used in the community:

Suggested tasks

Important

We should verify that type definitions work in both cases.

  • Create a minimal Jest + CommonJS reproduction example using ts-jest
  • Check that types are correctly resolved with that setup
  • Create a Node.js example providing a script that uses maxGraph with CommonJS + jsdom (see ideas in Running maxgraph headlessly #761)
  • Validate that there is no impact on the bundle size of the existing examples
  • In the node.js example, add link to the issue explaining why this is currently not working with ESM

Metadata

Metadata

Assignees

Labels

No labels
No labels

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions