Version 0.24.0 released on 2026-07-08.

⚡ This new version continues improving modularity and tree-shaking: the image bundle feature moves to a dedicated plugin and per-edge-style registration helpers are introduced. ⚡

Breaking changes

Edge handle visibility is now driven by registry metadata

EdgeHandler.isHandleVisible() now uses EdgeStyleRegistry.allowsIntermediateHandles() instead of checking against the EdgeStyle.EntityRelation function reference.

• If you register custom edge styles that should hide intermediate bend handles, you must now set allowIntermediateHandles: false in the EdgeStyleMetaData when calling EdgeStyleRegistry.add().
• If you register EdgeStyle.EntityRelation yourself (e.g. when using BaseGraph), include { allowIntermediateHandles: false } in the metadata to preserve the previous behavior, or call the new registerEntityRelationEdgeStyle() function which sets the correct metadata for you.
• EdgeStyleRegistryInterface has a new allowsIntermediateHandles method. If you implement this interface directly, you must add this method.

If you register EdgeStyle.EntityRelation yourself:

// Before: the previous behavior was implied by the EntityRelation reference
import { EdgeStyle, EdgeStyleRegistry } from '@maxgraph/core';

EdgeStyleRegistry.add('entityRelationEdgeStyle', EdgeStyle.EntityRelation, {
  isOrthogonal: true,
});

// After: opt in explicitly, or use the dedicated helper
import { EdgeStyle, EdgeStyleRegistry, registerEntityRelationEdgeStyle } from '@maxgraph/core';

EdgeStyleRegistry.add('entityRelationEdgeStyle', EdgeStyle.EntityRelation, {
  allowIntermediateHandles: false,
  isOrthogonal: true,
});
// or simply:
registerEntityRelationEdgeStyle();

For more details, see #1040.

ImageMixin converted to ImageBundlePlugin

ImageMixin has been converted to a new ImageBundlePlugin (id 'image-bundle'). Unlike a mixin, which shares a single state tree across all Graph instances and adds domain-specific methods to AbstractGraph, the plugin is per-instance and opt-in, keeping AbstractGraph lean. As a result, AbstractGraph.addImageBundle, removeImageBundle, getImageFromBundles and the imageBundles property no longer exist on AbstractGraph, Graph, or BaseGraph.

• Migrate mutating call sites from graph.addImageBundle(bundle) (and siblings) to graph.getPlugin<ImageBundlePlugin>('image-bundle')!.addImageBundle(bundle). The non-null assertion is deliberate: if the plugin is not registered, the call fails fast rather than silently dropping the registration.
• For read-only key resolution, use graph.getPlugin<ImageBundlePlugin>('image-bundle')?.getImageFromBundles(key).
• BaseGraph no longer ships image-bundle support by default. Add ImageBundlePlugin to the plugins option to opt in. Graph continues to work unchanged because ImageBundlePlugin is part of getDefaultPlugins().
• XML serialization of <Graph> and <BaseGraph> no longer emits <Array as="imageBundles" />. Existing XML documents containing that element still decode without error, but the field is silently ignored.

// Before
graph.addImageBundle(bundle);
const image = graph.getImageFromBundles(key);

// After
import { ImageBundlePlugin } from '@maxgraph/core';

graph.getPlugin<ImageBundlePlugin>('image-bundle')!.addImageBundle(bundle);
const image = graph.getPlugin<ImageBundlePlugin>('image-bundle')?.getImageFromBundles(key);

A new "image bundles" usage guide and a Storybook story cover registration, the BaseGraph opt-in, and the XML-serialization change.

This change is part of #762. For more details, see #1050.

Highlights

Per-edge-style register helpers

There is now one register*EdgeStyle helper per built-in edge style (Elbow, EntityRelation, Loop, Manhattan, Orthogonal, Segment, SideToSide, TopToBottom), so BaseGraph users can register only what they need, without pulling in all of them and without having to know the associated EdgeStyleMetaData. registerDefaultEdgeStyles() now simply calls these eight helpers.

Before, you had to register each style explicitly and pass the right metadata by hand:

import { EdgeStyle, EdgeStyleRegistry } from '@maxgraph/core';

EdgeStyleRegistry.add('entityRelationEdgeStyle', EdgeStyle.EntityRelation, {
  allowIntermediateHandles: false,
  isOrthogonal: true,
});
EdgeStyleRegistry.add('manhattanEdgeStyle', EdgeStyle.ManhattanConnector, {
  handlerKind: 'segment',
  isOrthogonal: true,
});

Now, call the dedicated helper for each style you need:

import {
  registerEntityRelationEdgeStyle,
  registerManhattanEdgeStyle,
} from '@maxgraph/core';

registerEntityRelationEdgeStyle();
registerManhattanEdgeStyle();

For more details, see #1077.

Edge handle visibility driven by registry metadata

Intermediate bend handle visibility is now resolved from edge style registry metadata (allowsIntermediateHandles) rather than from a hard-coded reference to EdgeStyle.EntityRelation. Previously only EntityRelation could influence handle visibility; now any edge style, including custom ones, controls it through configuration instead of being forced to write code to override maxGraph's defaults. Because EdgeHandler no longer imports EdgeStyle directly, EntityRelation is tree-shaken when your application does not register it, saving about 2 kB. See the Breaking changes section above for the migration details.

This closes #978. For more details, see #1040.

Bundle size

Overall the example bundle sizes stay roughly stable. The reduced examples (selected-features and without-defaults) shrink by 1 to 3 kB because EntityRelation and the image-bundle code path are now tree-shaken when they are not used. The fully featured examples (js-example, ts-example) grow by about 1 kB: they still register EntityRelation by default, so they do not benefit from the tree-shaking but do include the new handle-visibility code.

Examples in the maxGraph repository

Resources

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

What's Changed

🎉 New Features

• feat!: use registry metadata for edge handle visibility by @redfish4ktc in #1040
• feat(style): add register helper per built-in edge style by @redfish4ktc in #1077

🐛 Bug Fixes

• fix: restore preview edge default target position on cell hover by @LOUISNOYEZ in #1025
• fix(connectionHandler): apply perimeter style to new edges by @LOUISNOYEZ in #1026
• fix : make the KeyHandler work in the Validation story by @LOUISNOYEZ in #1027
• fix(ConnectorShape): ignore unset arrows in edge bounding box by @tbouffard in #1094

📝 Documentation

• docs: fix wording in the perimeters documentation by @tbouffard in #1032
• docs: add AGENTS.md and align agent configs with current code by @redfish4ktc in #1049
• docs: add graph documentation page and refine related pages by @redfish4ktc in #1048

⚙️ Refactor

• refactor!: convert ImageMixin to ImageBundlePlugin by @tbouffard in #1050
• refactor: improve GraphSelectionModel implementation, jsdoc and tests by @redfish4ktc in #1055
• test(FitPlugin): simplify container dimension setup by @redfish4ktc in #1079

🛠 Chore

• ci: improve the release template by @redfish4ktc in #1038
• chore: display bundle size table at end of build-all-examples script by @redfish4ktc in #1037
• chore: apply exec permission to shell hook script by @redfish4ktc in #1054
• chore: remove commented clearSelection in CellEditorHandler by @redfish4ktc in #1075
• refactor: tighten selectionModel type and verify per-instance creation by @redfish4ktc in #1078
• chore: share Claude build-protection config and trim rule bloat by @redfish4ktc in #1086

New Contributors

• @LOUISNOYEZ made their first contribution in #1025

Full Changelog: v0.23.0...v0.24.0

Version 0.23.0 released on 2026-03-30.

⚡ This new version improves modularity, fixes important memory leaks, and adds utilities for better configuration management. ⚡

Breaking changes

Tooltip API moved to TooltipHandler

The tooltip-related methods have been moved from AbstractGraph to the TooltipHandler plugin.

This change improves modularity and tree-shaking, and clarifies responsibilities by removing tooltip logic from the core graph.

• getTooltip
• getTooltipForCell

are no longer available on AbstractGraph.

This change mainly impacts advanced usages where tooltips are customized.

xmlUtils.getViewXml moved

The function xmlUtils.getViewXml has been moved to xmlViewUtils.getViewXml.

This change helps clarify responsibilities around XML view utilities and prepares for better modularization.

If you were using this function, you only need to update the import path.

Highlights

Reset functions for global configurations

New helper functions are available to reset global configuration objects:

• resetGlobalConfig()
• resetStencilShapeConfig()

These functions restore default values, including internal instances like NoOpLogger and NoOpI18n.

They are especially useful for:

• testing scenarios
• Storybook environments
• applications that need to isolate configuration state between runs

Fix memory leaks in destroy methods

This release includes an important fix for memory leaks during graph destruction.

Some resources were not properly released, especially in plugins like PanningManager, but the issue was more general.

This update:

• standardizes destruction flows across components
• ensures base class cleanup is always executed
• stops active timers and processes
• removes event listeners (panning, gestures, etc.)

This fix makes teardown more reliable and prevents hidden memory issues in long-running applications.

Resources

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

What's Changed

🎉 New Features

• feat(config): add reset functions for global configurations by @tbouffard in #979

🐛 Bug Fixes

• fix: fix memory leaks in destroy methods by @redfish4ktc in #1023

📝 Documentation

• docs(HiearchicalLayout): fix copy pasted JSDoc for cache attributes by @le-codeur-rapide in #975
• docs: improve library presentation in README and website by @tbouffard in #1006
• docs: improve JSDoc of UndoManager by @tbouffard in #1007
• docs: fix JSDoc refs pointing to CellRenderer instead of ShapeRegistry by @tbouffard in #1010
• docs: fix orthogonal projection description and add cross-links by @redfish4ktc in #1030

⚙️ Refactor

• refactor!: move tooltip methods to TooltipHandler by @tbouffard in #640
• refactor: introduce internal log() shortcut function by @tbouffard in #974
• refactor(stories): migrate HelloWorld story to TypeScript by @tbouffard in #984
• refactor: use singular and kebab-case for source folder names by @tbouffard in #985
• refactor: simplify the implementation of isNullish by @tbouffard in #989
• refactor!: move getViewXml from xmlUtils to xmlViewUtils by @tbouffard in #992
• refactor: use parseXml instead of direct call to DOMParser by @tbouffard in #991
• refactor(typescript): fix SonarQube issues on extensible string types by @tbouffard in #1009
• refactor(typescript): introduce the Constructor utility type by @tbouffard in #1011
• fix: parse HTML instead of XML in SvgCanvas2D.convertHtml by @tbouffard in #1012
• refactor: improve type guard for domUtils.isNode by @tbouffard in #1000

🛠 Chore

• chore(deps-dev): bump storybook from 9.1.1 to 10.1.0 by @tbouffard in #981
• chore: add storybook patterns to dependabot configuration by @tbouffard in #987
• ci: ensure that all workflows define permissions of the GITHUB_TOKEN by @tbouffard in #990
• ci: attach examples and website assets to GitHub releases by @tbouffard in #996
• chore: improve Claude Code configuration by @redfish4ktc in #1029

New Contributors

• @le-codeur-rapide made their first contribution in #975
• @redfish4ktc made their first contribution in #1023

Full Changelog: v0.22.0...v0.23.0

Version 0.22.0 released on 2025-12-11.

⚡ This new version makes default style properties globally configurable and includes bug fixes for a smoother developer experience. ⚡

Resources

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

Highlights

Globally configurable default style properties

Previously, changing default styles required local configuration per Graph instance using a Stylesheet.
It was also not possible to configure the rounding factor used when a vertex uses a non absolute arcSize, because there was no dedicated cell style property for that.
This release solves these limitations by making the built-in defaults globally configurable.

The StyleDefaultsConfig object has been extended to allow customization of default style values that were previously hardcoded as constants.
All direct references to DEFAULT_* constants in the codebase are now replaced with StyleDefaultsConfig property access. This means you can change these defaults at runtime without updating stylesheets on every Graph instance.

New configurable properties include:

• Font settings: fontFamily, fontSize
• Arrow settings: arrowSize, arrowSpacing, arrowWidth
• Size settings: markerSize, imageSize, startSize
• Rounding: roundingFactor, lineArcSize

You can now globally customize these defaults at runtime like this:

import { StyleDefaultsConfig } from '@maxgraph/core';

// Change default marker size
StyleDefaultsConfig.markerSize = 10;

// Change default image size for labels
StyleDefaultsConfig.imageSize = 32;

// Change default swimlane start size
StyleDefaultsConfig.startSize = 50;

// Change default rounding factor
StyleDefaultsConfig.roundingFactor = 0.4;

Bug fixes

This release also includes bug fixes that improve overall stability and consistency of rendering and styling.
If you encounter any regressions or unexpected behavior, please open an issue with a minimal reproduction so we can address it quickly.

What's Changed

🎉 New Features

• feat: accept more nullish parameter in various methods by @tbouffard in #892
• feat: allow to pass more null and undefined to Multiplicity by @tbouffard in #914
• feat: add generic font in default font family by @tbouffard in #931
• feat: make default style properties globally configurable by @tbouffard in #932

🐛 Bug Fixes

• fix(editor): ensure editor context in installDblClickHandler callback by @tbouffard in #934
• fix: restore tooltip display when PopupMenuHandler is unavailable by @chrisob194 in #970
• fix(VertexHandler): fix top-left resize handle behavior by @Lockps in #968

📝 Documentation

• docs: add badge to DeepWiki in the README by @tbouffard in #913
• docs(website): enable system color mode toggle by @tbouffard in #933
• docs: display correct title on image of the home page by @tbouffard in #951
• docs: add Contributing guide by @tbouffard in #948

⚙️ Refactor

• refactor: fix most problems in the Wires story by @tbouffard in #893
• refactor: simplify signature of the isNullish internal function by @tbouffard in #907
• refactor: migrate the Guides story to TypeScript by @tbouffard in #908
• refactor: simplify implementation of ParallelEdgeLayout by @tbouffard in #909
• refactor: ensure mixins do not create shared properties in AbstractGraph by @tbouffard in #879
• refactor: simplify Editor installDblClickHandler by @tbouffard in #938
• refactor: prefer includes to indexOf by @tbouffard in #952
• refactor(Stylesheet): simplify default style creation methods by @tbouffard in #955
• refactor: introduce AbstractPathShape base class for shape hierarchy by @tbouffard in #953
• refactor: improve types usage in PageBreaksMixin by @tbouffard in #956

🛠 Chore

• test: add more tests for FitPlugin.fit by @tbouffard in #888
• chore(typescript): always use explicit override by @tbouffard in #921
• chore: use stricter options with the TS compiler by @tbouffard in #922
• chore: add some unicorn eslint plugin rules by @tbouffard in #925
• chore: add config files for some code assistant by @tbouffard in #930
• chore: build with node 22 by @tbouffard in #937
• chore: add react patterns to dependabot configuration by @tbouffard in #964
• docs: enhance bug report template with additional guidance by @tbouffard in #967
• chore: build with node 24 by @tbouffard in #971
• ci: publish npm package with trusted publisher by @tbouffard in #972

New Contributors

• @chrisob194 made their first contribution in #970
• @Lockps made their first contribution in #968

Full Changelog: v0.21.0...v0.22.0

Version 0.21.0 released on 2025-07-23.

⚡ This release improves Webpack and Node.js compatibility, removes legacy code, and slightly reduces bundle size. ⚡

Resources

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

Breaking changes

fit method moved to FitPlugin

The AbstractGraph.fit method and the minFitScale and maxFitScale properties have been moved to the FitPlugin.
This helps reduce the size of the base graph when the plugin is not used.

Removal of Dictionary class

The Dictionary class has been removed. You can now use the native JavaScript Map object, which is available in all environments supported by maxGraph.
This class was originally introduced in mxGraph to support old browsers lacking Map.

If your code used Dictionary, replace it with Map.

Rounded shapes: consistent arcSize rendering

The way arcSize is computed for rounded shapes is now consistent across all shape types and matches the behavior of mxGraph.

TypeScript-specific changes

• AbstractGraph.getPlugin() now explicitly returns undefined if the plugin is not found.
  You must handle the undefined case in your code.

• Improved return types for EditorToolbar methods:

  • addPrototype() now returns HTMLImageElement (was HTMLImageElement | HTMLButtonElement)
  • addCombo() now returns HTMLSelectElement (was HTMLElement)

Highlights

🔍 Search bar on the documentation website

You can now quickly search the documentation!
The new search bar uses a local lunr-search index for fast results.

🛠️ Webpack configuration simplified + Node.js ESM support

maxGraph can now be used with Webpack and Node.js ESM without extra config 🎉

Before this update, using maxGraph with Webpack required a workaround like this:

module.exports = {
  module: {
    rules: [
      {
        test: /\.m?js/,
        resolve: {
          fullySpecified: false,
        },
      },
    ],
  },
};

This was needed because import paths in maxGraph were missing the .js extension.
This also caused issues when importing maxGraph in ESM contexts with Node.js — no workaround was possible in that case.

These issues are now fixed ✅

📦 Bundle size reduction

Small but measurable size gains:

• -0.7 kB: removal of the Dictionary class and internal refactoring (#857)
• -1.0 kB: when not using the FitPlugin, due to fit logic moving out of BaseGraph (#734)

What's Changed

🎉 New Features

• feat: let choose the implementation of ConstraintHandler by @tbouffard in #838
• feat(type): allow optional for parameters of AbstractGraph.addCells by @tbouffard in #847
• feat: add search to website by @tbouffard in #853
• feat: ease webpack configuration and add support Node ESM by @tbouffard in #867

🐛 Bug Fixes

• fix(FitPlugin): handle edge cases in fitCenter calculation by @tbouffard in #831
• fix: correct Editor cycleAttribute and swapStyles methods by @tbouffard in #871
• fix!: improve the robustness of codecs by @tbouffard in #872
• fix: consistently compute the arcSize for edges and vertices by @tbouffard in #884

📝 Documentation

• docs(release): fix the name of the zip files to archive by @tbouffard in #833
• docs: fix CHANGELOG for 0.20.0 by @tbouffard in #845
• docs: improve jsdoc of CellOverlay by @tbouffard in #846
• docs: fix some typedoc warnings by @tbouffard in #870

⚙️ Refactor

• refactor!: move AbstractGraph.fit to FitPlugin by @tbouffard in #734
• refactor: migrate the Orthogonal story to TypeScript by @tbouffard in #835
• refactor: migrate the FixedPoints story to TypeScript by @tbouffard in #839
• refactor(type)!: make AbstractGraph.getPlugin return T | undefined by @tbouffard in #842
• refactor: increase usage of the MouseListenerSet interface by @tbouffard in #848
• refactor(stories): remove reference to Graph handler by @tbouffard in #849
• refactor!: remove Dictionary and use Map instead by @tbouffard in #857
• refactor: migrate the DragSource story to TypeScript by @tbouffard in #860
• refactor: remove reference to legacy insert cells methods by @tbouffard in #876
• refactor: migrate the Thread story to TypeScript by @tbouffard in #877
• refactor: migrate the Stylesheet story to TypeScript by @tbouffard in #878

🛠 Chore

• test: add more tests to FitPlugin by @tbouffard in #834
• test: add tests for Cell.hasAttribute by @tbouffard in #850
• chore(eslint): use flat configuration by @tbouffard in #851
• ci: run with ubuntu-24.04 by @tbouffard in #861
• ci: display the date of the release in the release notes by @tbouffard in #885

Full Changelog: v0.20.0...v0.21.0

Version 0.20.0 released on 2025-05-16.

⚡ 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 #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 #806
• feat!: improve tree-shaking of EdgeStyle by @tbouffard in #809
• feat: improve plugin ID guidance and type safety by @tbouffard in #818
• feat: add CommonJS support to npm package by @tbouffard in #826

🐛 Bug Fixes

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

📝 Documentation

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

⚙️ Refactor

• refactor!: remove the SHAPE enum by @tbouffard in #795
• refactor!: remove ARROW, EDGESTYLE, PERIMETER enums by @tbouffard in #796
• refactor!: remove the ALIGN and RENDERING_HINT enums by @tbouffard in #798
• refactor!: remove the DIALECT enum by @tbouffard in #800
• refactor!: remove DIRECTION and TEXT_DIRECTION enums by @tbouffard in https://github...

⚡ This new version improves tree-shaking for EdgeStyle and Perimeter, updates the documentation, and fixes bugs. ⚡

Resources

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

Breaking changes

• EdgeStyle is now a namespace
  It used to be a class with static properties. You could technically mutate it to add or override values — but that’s no longer possible.
  If you were doing this, you now need to define your own EdgeStyle implementation and register it explicitly.

• Perimeter is now a namespace
  Previously a plain object, Perimeter could be mutated too. Not anymore.
  Like with EdgeStyle, create your own perimeter implementation and register it if needed.

Highlights

📦 Tree-shaking improvements for EdgeStyle and Perimeter

Until now, all edge styles and perimeters were bundled into your app even if you only used a few of them. Why? Because EdgeStyle and Perimeter were objects that referenced everything, which prevented bundlers from optimizing properly.

Here’s what changed:

• EdgeStyle is now a namespace. This allows bundlers to drop unused edge styles and only keep what’s actually registered and used via StyleRegistry.
• Perimeter is now also a namespace, instead of a value object. This improves bundling behavior, especially for bundlers that couldn’t previously optimize it (Webpack, Vite when misconfigured, etc.).

📉 Impact on bundle size

Depending on what edge styles and perimeters your app uses, and the bundler you're using, bundle size can shrink by 1 to 5 kB.

🔍 A few things to keep in mind

• The EdgeStyle change currently has limited effect, since many built-in styles are still referenced directly in the codebase. This will improve in the future (see #767).
• The Perimeter change doesn’t impact apps built with Rollup or Vite (which uses Rollup internally), since they already optimized this before. But it’s now cleaner and safer across the board.

Here’s a concrete example of what Rollup was doing with the old object-based Perimeter (with minification disabled):

const RectanglePerimeter = ...
const EllipsePerimeter = ...

const Perimeter = {
  RectanglePerimeter,
  EllipsePerimeter
};

Only the perimeters actually used are bundled in.

🔬 Real-world examples from the maxGraph repo

Analysis:

• In the *-without-default examples, there's no change — because Perimeter wasn't used.
• In TS examples, the gains are minor (Rollup already tree-shaked well).
• The best gains are seen in JS/Webpack examples where tree-shaking was previously limited.

🔬 Examples from the maxgraph-integration-examples repository

• Related PR: #220

What's Changed

🎉 New Features

• feat!: improve tree-shaking of Perimeter by @tbouffard in #785
• feat: improve IDE guidance for style element registration by @tbouffard in #787
• feat!: improve tree-shaking of EdgeStyle by @tbouffard in #791

🐛 Bug Fixes

• fix: correctly convert "arc" attributes to boolean in StencilShape by @tbouffard in #788

📝 Documentation

• docs: add structure section and improve npm package details by @tbouffard in #792

Full Changelog: v0.18.0...v0.19.0

⚡ This new version introduces BaseGraph for better control over loaded features, adds new utilities to register default style elements, and significantly reduces bundle size! ⚡

Resources

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

Highlights

🚀 Introducing BaseGraph

Historically, the Graph class has been the main entry point in maxGraph, just like it was in mxGraph.
It automatically loads default plugins and style elements, making it convenient for prototyping but less ideal for production use - it increases the bundle size by including features you might not even use.

With v0.18.0, you now have a better option:

• BaseGraph: an alternative to Graph that loads nothing by default. You choose what to include.
• AbstractGraph: a new abstract class with all the common logic, shared by both Graph and BaseGraph.
• Graph remains fully functional, but it's now built on top of AbstractGraph.

This is a big step toward full tree-shaking support!
More improvements are coming soon. Stay tuned! 📻

• Related PR: Introduce BaseGraph in #776

🛠 Usage of BaseGraph

BaseGraph also simplifies constructor usage:
Instead of many parameters (and sometimes lots of null), you now pass a single configuration object.

Example - Basic setup:

const graph = new BaseGraph({
  container: document.getElementById('graphContainer')!,
});

Example - Full configuration:

const graph = new BaseGraph({
  container: document.getElementById('graphContainer')!,
  model: new MyGraphDataModel(),
  stylesheet: new MyStylesheet(),
  plugins: [Plugin1, Plugin2],
  cellRenderer: new MyCellRenderer(),
  view: (graph: AbstractGraph) => new MyGraphView(graph),
  selectionModel: (graph: AbstractGraph) => new MyGraphSelectionModel(graph),
});

Compared to Graph, it's much cleaner - no need to extend classes just to customize internals!

⚡ Comparison: Graph Usage

When using the traditional Graph class, customization often requires class extension and overriding internal methods (createXXX) which makes the code heavier and less readable.

Example - Basic setup:

const graph = new Graph(document.getElementById('graphContainer')!);

Example - Full customization:

class MyCustomGraph extends Graph {
  override createCellRenderer(): CellRenderer {
    return new MyCellRenderer();
  }

  override createGraphView(): GraphView {
    return new MyGraphView(this);
  }

  override createSelectionModel(): GraphSelectionModel {
    return new MyGraphSelectionModel(this);
  }
}

const graph = new MyCustomGraph(
  document.getElementById('graphContainer')!,
  new MyGraphDataModel(),
  new MyStylesheet(),
  [Plugin1, Plugin2],
);


// If you want to override only some elements and not others, you might end up passing `undefined` explicitly:
// In case of the GraphDataModel and Stylesheet are managed by overriding `createGraphDataModel` and `createStylesheet` respectively
const graph = new MyCustomGraph(
  document.getElementById('graphContainer')!,
  undefined,
  undefined, 
  [Plugin1, Plugin2],
);

🎨 Easier Ways to Register Style Elements

Want to manually register default styles? New helper functions are available:

registerDefaultEdgeMarkers();
registerDefaultEdgeStyles();
registerDefaultPerimeters();
registerDefaultShapes();

Use them to selectively register only what your app actually needs!
If you need all built-in elements for a category, these helpers make it super easy.

• Related PR: #757

📦 Impact of BaseGraph on Bundle Size

Using BaseGraph with only the styles and plugins you need can drastically shrink your app's bundle size.
Tree-shaking now works better and smarter!

In our examples, switching to BaseGraph with a minimal setup gave measurable improvements, even with default bundler configs!
The "without-defaults" examples showed a decrease 105 kB!

🔬 Examples from the maxGraph repository

• the JS and TS examples doesn't cover the same use case
• the size mentioned here is the one of the whole application in the JS examples and the one of the maxGraph chunk in the TS examples

📖 See documentation for full example details.

• Related PRs: #774, #776, #779

🔬 Examples from the maxgraph-integration-examples repository

Integration projects also switched to BaseGraph, showing similar gains:

Fun fact:

• Removing the optional CellEditorHandler plugin in vite drops another ~12.5 kB!

• Related PRs: #214, #215

What's Changed

🎉 New Features

• feat: simplify types used to register shapes by @tbouffard in #768
• feat(core): explicitly support undefined container in Graph constructor by @tbouffard in #769
• feat: let register and unregister default style elements by @tbouffard in #757
• feat: introduce examples that not rely on default plugins and styles by @tbouffard in #774
• feat: let efficiently not load default plugins and style builtins by @tbouffard in #776
• feat: let serialize BaseGraph with Codecs by @tbouffard in #778

🐛 Bug Fixes

• fix: use the right list of excluded fields in GraphCodec by @tbouffard in #777

📝 Documentation

• docs: explain that the mxGraph migration guide is no longer updated by @tbouffard in #783

⚙️ Refactor

• refactor(type): explicitly declare the MouseListenerSet interface by @tbouffard in #770
• refactor: reorganize builtin style elements by @tbouffard in #775
• refactor: use CellEditorHandler plugin in selected-features examples by @tbouffard in #779

Full Changelog: v0.17.0...v0.18.0

⚡ This new version improves graph fitting, makes i18n fully configurable, and reduces bundle size significantly. ⚡

Resources

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

Breaking changes

🔐 Eval usage is now disabled by default

To prevent potential security issues, StylesheetCodec.allowEval is now false by default.

🌐 Configurable i18n

The built-in Translations class is no longer used by default. If you want to keep using it, you must now explicitly enable it:

GlobalConfig.i18n = new TranslationsAsI18n();

🧰 Utility functions access changes

Several utils have been reorganized for better clarity and maintainability:

• These functions are now accessed through specific namespaces:
  • get, getAll, load, post, submit → requestUtils
  • error, popup → guiUtils
• The old utils namespace has been removed.
• Remaining relevant properties were moved to guiUtils.

💥 Removed internal functions

Some functions that were mistakenly exposed as public have been removed:

• Utils.copyTextToClipboard is no longer available.

  See #738

• cellArrayUtils.filterCells was removed - just use the native Array.filter() instead!

  See #752

Highlights

🎯 New: Fit Center

You can now center and fit your graph into the container with the new FitPlugin.
The method is inspired by the former example provided in the JSDoc of Graph.fit() but improved to:

• handle margins better,
• reduce visual shifts when called multiple times.

The storybook and TypeScript example have been updated to showcase how it works in various contexts.

🌍 Configurable i18n support

Until now, the Translations class was always used internally. Now you can:

• Disable i18n completely for smaller bundles,
• Plug in your own i18n solution.

This makes maxGraph more flexible and lighter by default.

📦 Smaller bundle size

Thanks to the new i18n configuration, tree-shaking now works better.
Depending on your setup, you could reduce the size of your app by 5-10kB - and probably more with tuned bundler configs!

🔬 Examples in the maxGraph repo

📖 See documentation for what each example includes.

🔬 Examples in maxgraph-integration-examples

All integration projects reuse a shared core similar to ts-example. Here's the app size:

[1] parcel is the sole bundler that increases the size of the application. Parcel was bump from 2.13.3 to 2.14.4 which may have introduced changes.

➰ New story: curved edges

We've added a story to show the difference between:

• default edges
• curved edges
• rounded edges

What's Changed

🎉 New Features

• feat: refine the type of CellStateStyle.elbow by @tbouffard in #701
• feat: CellStateStyle port constraints accept multiple DirectionValue by @tbouffard in #721
• feat: let "fit center" with the new FitPlugin by @tbouffard in #733
• feat!: limit usage of the eval function by @tbouffard in #736
• feat!: introduce a way to configure the I18n provider by @tbouffard in #737

🐛 Bug Fixes

• fix: consider ManhattanConnector as orthogonal by @tbouffard in #707
• fix(type): let Graph fitScale properties allow null by @tbouffard in #715
• fix(story): add buttons to container, not to the document by @tbouffard in #750
• fix(story): ensure that the Model Codecs are always registered by @tbouffard in #749
• fix: make Graph.options truly per-instance by @tbouffard in #751

📝 Documentation

• docs: add more JSDoc categories by @tbouffard in #714
• docs: improve jsdoc for custom implementation of EdgeStyle by @tbouffard in #724
• docs: improve JSDoc of styleUtils by @tbouffard in #727
• docs: improve JSDoc of allowEval properties by @tbouffard in #729
• docs: update reference to functions moved to dedicated namespaces by @tbouffard in #746

⚙️ Refactor

• refactor: migrate the Events story to TypeScript by @tbouffard in #702
• refactor: introduce shared code to manage description of story by @tbouffard in #703
• refactor: migrate the Wrapping story to TypeScript by @tbouffard in #720
• refactor: simplify type management in Codecs by @tbouffard in #723
• refactor: apply internal improvements to editor classes by @tbouffard in #726
• refactor: improve the management of CellStateStyle.curved by @tbouffard in #731
• refactor: remove isNotNullish internal function by @tbouffard in #732
• refactor: move plugins to a dedicated folder by @tbouffard in #735
• refactor!: move internal utils functions to a dedicated directory by @tbouffard in #738
• refactor!: expose all exported functions in namespaces by @tbouffard in #740
• refactor!: move properties of utils to guiUtils by @tbouffard in #741
• refactor(types): simplify imports of the Graph types by @tbouffard in #743
• refactor!: remove cellArrayUtils.filterCells by @tbouffard in #752

🛠 Chore

• chore: add more checks in ts-support by @tbouffard in #728
• chore(types): enforce usage of explicit override keyword in examples by @tbouffard in #739

Full Changelog: v0.16.0...v0.17.0

⚡ This new version enhances internationalization (i18n), improves connector configurations, and prepares for future updates with tree shaking optimizations. ⚡

Resources

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

Breaking changes

• Private utility functions:
  The functions utils.isNullish and utils.isNotNullish are now marked as private. They were mistakenly made public and have always been intended for internal use.

• Removed utility functions:
  Several utility functions, originally designed for internal use to retrieve default values for CellStateStyle and CellStyle, have been removed:

  • utils.getValue
  • stringUtils.getColor
  • stringUtils.getNumber
  • stringUtils.getStringValue

  You should now use the nullish coalescing operator (??) and Optional chaining (?.) instead.

• Removed Client.isBrowserSupported:
  The Client.isBrowserSupported method has been removed. It was not correctly validating all the prerequisites for determining whether the browser supports maxGraph. This method is now deprecated with no direct replacement.

• Moved Client.VERSION to constants.VERSION:
  The VERSION constant, previously stored in Client, is now stored in the constants module to ensure its immutability, as it represents the actual version of maxGraph.

• Relocated Translations configuration:
  Configuration elements for translations have been moved from Client to TranslationsConfig. The following properties have been migrated:

  • Client.defaultLanguage → TranslationsConfig.getDefaultLanguage
  • Client.setDefaultLanguage → TranslationsConfig.setDefaultLanguage
  • Client.language → TranslationsConfig.getLanguage
  • Client.setLanguage → TranslationsConfig.setLanguage
  • Client.languages → TranslationsConfig.getLanguages
  • Client.setLanguages → TranslationsConfig.setLanguages

• Connector Configuration changes:

  • ManhattanConnector: Now configured via the global ManhattanConnectorConfig object. Several properties that were previously part of EdgeStyle have moved to this configuration object:
    • MANHATTAN_END_DIRECTIONS → endDirections
    • MANHATTAN_MAX_ALLOWED_DIRECTION_CHANGE → maxAllowedDirectionChange
    • MANHATTAN_MAXIMUM_LOOPS → maxLoops
    • MANHATTAN_START_DIRECTIONS → startDirections
    • MANHATTAN_STEP → step
  • OrthConnector: Now configured via the global OrthogonalConnectorConfig object. The following properties have been moved:
    • orthBuffer → buffer
    • orthPointsFallback → pointsFallback

• Internal utility methods:
  Several properties and utility methods previously exposed by EdgeStyle are now internal. For example:

  • The getRoutePattern method has been removed entirely, as it was not being used anywhere within the codebase.

Highlights

🌍 Custom Shape Support for Overlays

You can now use custom shapes for overlays instead of just images. The CellRenderer provides extension points for configuring custom shapes and their associated DOM nodes.

Here is an example of custom Overlays taken from the Overlays story 👇🏿

🌐 Improved i18n Support

This release enhances i18n support with the restoration of original mxGraph resource files (Chinese, English, and German) and adds French and Spanish resources. Additionally, a new configuration object, TranslationsConfig, is introduced to simplify and extend internationalization functionality in future releases.
This update is part of ongoing efforts to allow for custom i18n mechanisms in future versions (see issue #688).

🔗 Enhanced Manhattan and Orthogonal Connector Configuration

The configuration for both the Manhattan and Orthogonal connectors is now centralized in dedicated global configuration objects: ManhattanConnectorConfig and OrthogonalConnectorConfig. This change helps clarify responsibilities and makes future tree shaking optimizations easier. Additionally, related reset functions are now available.

What's Changed

🎉 New Features

• feat!: introduce global config for the Orthogonal connector by @tbouffard in #678
• feat!: introduce global config for the Manhattan connector by @tbouffard in #681
• feat: provide i18n default resources by @tbouffard in #689
• feat: provide i18n resources for French and Spanish by @tbouffard in #690
• feat!: introduce TranslationsConfig by @tbouffard in #691
• feat: allow to use custom shape for overlays by @tbouffard in #696

🐛 Bug Fixes

• fix: Graph.isValidAncestor manages null Cell parameter by @tbouffard in #699

📝 Documentation

• docs: apply improvements to the navbar by @tbouffard in #675
• docs: improve css and images page by @tbouffard in #677

⚙️ Refactor

• refactor!: mark isNullish and isNotNullish as private by @tbouffard in #661
• refactor!: remove extra getDefault functions and related functions by @tbouffard in #662
• refactor!: remove Client.isBrowserSupported by @tbouffard in #679
• refactor!: move VERSION to constants by @tbouffard in #680
• refactor!: extract Orthogonal and Manhattan connectors by @tbouffard in #684
• refactor: rename OrthConnectorConfig to OrthogonalConnectorConfig by @tbouffard in #685
• refactor: do not redeclare ImageShape properties already in Shape by @tbouffard in #694
• refactor: reset more global configurations in stories by @tbouffard in #646
• refactor: use external CSS file MenuStyle and ShowRegion stories by @tbouffard in #698

Full Changelog: v0.15.1...v0.16.0

⚡ This new version includes bug fixes and documentation improvements. ⚡

Resources

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

What's Changed

🐛 Bug Fixes

• fix: remove some circular dependencies by @tbouffard in #663
• fix(VertexHandler): display overlay when resizing a vertex by @tbouffard in #673

📝 Documentation

• docs: fix typo in CHANGELOG by @tbouffard in #653
• docs: apply quick fixes to the "getting started" and "demos" page by @tbouffard in #654
• docs(release): better explain how to choose the new version by @tbouffard in #655
• docs: add more information about perimeters by @tbouffard in #656
• docs: add missing Logging category to the Logger interface by @tbouffard in #667
• docs: add a first blog post in the website by @tbouffard in #672

⚙️ Refactor

• refactor: improve StencilShapeRegistry method signatures by @tbouffard in #660
• refactor: simplify CellRenderer by @tbouffard in #659

🛠 Chore

• ci(release): fix api call to get milestone number by @tbouffard in #651
• ci: include js-example-without-defaults during the build by @tbouffard in #669

Full Changelog: v0.15.0...v0.15.1