⚡ This new version improves registry consistency, removes legacy enums, supports CommonJS, and enables tree-shaking optimizations. ⚡

Resources

• npm package: @maxgraph/core 0.20.0
• Fixed issues: milestone 0.20.0
• Documentation: maxgraph_0.20.0_website.zip
• Examples: maxgraph_0.20.0_examples.zip
• Changelog (only includes a summary and breaking changes): changelog

Breaking changes

Unified Registry API for Style Elements

All style-related registries now implement the same Registry interface. This ensures a consistent developer experience and makes it easier to use or extend them. 🛠️

• All registries now expose the same methods: add, get, getName, and clear.
• Their internal storage is no longer directly accessible.

Renamed / Replaced Registries

• MarkerShape → EdgeMarkerRegistry
• Shapes are now registered via ShapeRegistry (not CellRenderer anymore)
• StyleRegistry has been removed. Use EdgeStyleRegistry and PerimeterRegistry instead.

Code migration examples

// Edge Marker
- MarkerShape.addMarker('oval', EdgeMarker.oval);
+ EdgeMarkerRegistry.add('oval', EdgeMarker.oval);

// Perimeter
- StyleRegistry.putValue('hexagonPerimeter', Perimeter.HexagonPerimeter);
+ PerimeterRegistry.add('hexagonPerimeter', Perimeter.HexagonPerimeter);

// Shape
- CellRenderer.registerShape('rhombus', RhombusShape);
+ ShapeRegistry.add('rhombus', RhombusShape);

// Stencil Shape
- StencilShapeRegistry.addStencil('my-stencil', new StencilShape(shape));
+ StencilShapeRegistry.add('my-stencil', new StencilShape(shape));

Special case: EdgeStyleRegistry

In addition to method renaming, EdgeStyleRegistry.add() now takes an extra options object to categorize the style. This avoids hardcoded behavior and improves flexibility. 🧩

- StyleRegistry.putValue('elbowEdgeStyle', EdgeStyle.ElbowConnector);
+ EdgeStyleRegistry.add('elbowEdgeStyle', EdgeStyle.ElbowConnector, { handlerKind: 'elbow', isOrthogonal: true });

This change supports internal refactors (see Highlights) and better extension patterns.

Element retrieval

For most users, no impact is expected. Retrieval methods are typically used in custom extensions only.

// Edge Marker
- MarkerShape.markers['oval'];
+ EdgeMarkerRegistry.get('oval');

// Edge Style
- StyleRegistry.getValue('elbowEdgeStyle');
+ EdgeStyleRegistry.get('elbowEdgeStyle');

// Perimeter
- StyleRegistry.getValue('hexagonPerimeter');
+ PerimeterRegistry.get('hexagonPerimeter');

// Shape
- CellRenderer.defaultShapes['rhombus'];
+ ShapeRegistry.get('rhombus');

// Stencil Shape
- StencilShapeRegistry.getStencil('my-stencil')
+ StencilShapeRegistry.get('my-stencil')

Enum Removal and Renaming

All remaining enums have been removed. They caused unnecessary complexity and weren’t actually used to list values. 🧹

Use the corresponding string-based types instead:

Other specific changes:

• constants.NODETYPE → replaced by value object constants.NODE_TYPE

  • DOCUMENTTYPE → DOCUMENT_TYPE

• constants.FONT → replaced by constants.FONT_STYLE_FLAG

• constants.CURSOR → values moved to:

  • ConnectionHandler
  • EdgeHandlerConfig
  • HandleConfig
  • VertexHandlerConfig

Also, constants.DIRECTION_MASK is now read-only. 🔒

Highlights

CommonJS Support for Node & Test Environments

maxGraph now ships with dual ESM and CommonJS builds. 🎉

Historically, only ESM was supported, as maxGraph was mainly used in browser-based applications with bundlers. But some new use cases made CJS support necessary:

Why it's useful

• Testing (e.g. with Jest): CJS is default in many test setups. Previously, you had to:

  • Add extra config just to run tests.
  • Migrate whole test suites to ESM - a massive task in large apps.
  • Replace CJS-only dependencies.

Now, maxGraph works in Jest without forcing ESM migration. ✅

• Node-based (headless) apps: Like SVG export use cases (see Running maxgraph headlessly #761). Some apps still use CommonJS, and maxGraph was previously unusable in those.

Now it just works. 😎

Tree-shaking Improvements

Tree-shaking is now much more effective thanks to multiple internal refactors. 🧼

Main improvement

EdgeStyle implementations are no longer hardcoded throughout the codebase. Instead, the code only relies on what is dynamically registered with configuration (see Breaking changes).

This allows bundlers to remove unused styles - big win on size! 📦

Example size comparison

Examples from maxGraph repo

Even with no changes in your app, enum removal already saves 3–5 kB. If your app avoids most EdgeStyles, savings can go up to 17 kB. 📉

Examples from maxgraph-integration-examples repo

All share common Graph config and use EdgeStyle.OrthConnector. ⚙️

What's Changed

🎉 New Features

• feat!: make various cursors configurable by @tbouffard in feat!: make various cursors configurable #806
• feat!: improve tree-shaking of EdgeStyle by @tbouffard in feat!: improve tree-shaking of EdgeStyle #809
• feat: improve plugin ID guidance and type safety by @tbouffard in feat: improve plugin ID guidance and type safety #818
• feat: add CommonJS support to npm package by @tbouffard in feat: add CommonJS support to npm package #826

🐛 Bug Fixes

• fix: correctly set italic in styleUtils.getSizeForString by @tbouffard in fix: correctly set italic in styleUtils.getSizeForString #805
• fix: ensure mdx pages can be displayed by storybook by @tbouffard in fix: ensure mdx pages can be displayed by storybook #814

📝 Documentation

• docs: fix changelog 0.19.0 by @tbouffard in docs: fix changelog 0.19.0 #794
• docs: introduce and use more categories in JSDoc by @tbouffard in docs: introduce and use more categories in JSDoc #807
• docs: display documentation with some stories by @tbouffard in docs: display documentation with some stories #816
• docs: enhance demo homepage with emojis and better organization by @tbouffard in docs: enhance demo homepage with emojis and better organization #820

⚙️ Refactor

• refactor!: remove the SHAPE enum by @tbouffard in refactor!: remove the SHAPE enum #795
• refactor!: remove ARROW, EDGESTYLE, PERIMETER enums by @tbouffard in refactor!: remove ARROW, EDGESTYLE, PERIMETER enums #796
• refactor!: remove the ALIGN and RENDERING_HINT enums by @tbouffard in refactor!: remove the ALIGN and RENDERING_HINT enums #798
• refactor!: remove the DIALECT enum by @tbouffard in refactor!: remove the DIALECT enum #800
• refactor!: remove DIRECTION and TEXT_DIRECTION enums by @tbouffard in refactor!: remove DIRECTION and TEXT_DIRECTION enums #799
• refactor!: remove the ELBOW enum by @tbouffard in refactor!: remove the ELBOW enum #801
• refactor!: replace NODETYPE enum by NODE_TYPE value object by @tbouffard in refactor!: replace NODETYPE enum by NODE_TYPE value object #802
• refactor(type)!: make DIRECTION_MASK read-only by @tbouffard in refactor(type)!: make DIRECTION_MASK read-only #803
• refactor!: replace FONT enum by FONT_STYLE_MASK value object by @tbouffard in refactor!: replace FONT enum by FONT_STYLE_MASK value object #804
• refactor!: standardize style registries with Registry interface by @tbouffard in refactor!: standardize style registries with Registry interface #812
• refactor: move shapes to a dedicated directory by @tbouffard in refactor: move shapes to a dedicated directory #817
• refactor: migrate the Control story to TypeScript by @tbouffard in refactor: migrate the Control story to TypeScript #821
• refactor(js-example): simplify the management of buttons by @tbouffard in refactor(js-example): simplify the management of buttons #822

🛠 Chore

• test: improve the Graph tests by @tbouffard in test: improve the Graph tests #797
• test: add tests to GraphView by @tbouffard in test: add tests to GraphView #808
• test: verify AbstractGraph.createHandler factory method delegation by @tbouffard in test: verify AbstractGraph.createHandler factory method delegation #819

Full Changelog: v0.19.0...v0.20.0

This discussion was created from the release 0.20.0.