This document provides a high-level introduction to the maxGraph system: its purpose, architecture, structure, and distribution. It serves as the entry point for understanding the entire codebase before diving into specific subsystems.
For detailed installation and first-time usage instructions, see Getting Started. For information about the monorepo structure and individual packages, see Monorepo Structure and Packages. For the internal architecture of the core library, see Architecture Overview.
maxGraph is a TypeScript library for building interactive diagram applications in web browsers. At its core, it provides a programmable system for managing and rendering graph structures consisting of:
Beyond basic diagram editing capabilities (resize, move, rotate, connect), maxGraph provides automatic layout algorithms, graph theory operations, hierarchical grouping, undo/redo management, XML serialization, and deep API-level customization.
The library is designed for developers building custom diagramming tools where off-the-shelf solutions lack sufficient flexibility or programmability. Typical use cases include flowchart editors, data lineage visualizers, network topology maps, business process modelers, and organizational charts.
Sources: README.md8-14 packages/core/README.md4-10 packages/core/package.json10
maxGraph is the actively maintained successor to mxGraph which was archived on November 9, 2020. The project began as a fork of mxGraph 4.2.2 with the goal of modernizing the codebase while preserving its comprehensive feature set and XML compatibility.
Key evolutionary changes from mxGraph:
The XML serialization format remains compatible with mxGraph, enabling interoperability with existing mxGraph-based systems and migration paths from legacy codebases.
Sources: README.md183-208 CHANGELOG.md438-445
maxGraph is organized as an npm workspaces monorepo containing 10+ packages. The following diagram shows the primary packages and their relationships:
Core Library Package — @maxgraph/core is the primary deliverable, containing all graph visualization functionality. It builds to both ESM and CommonJS formats for broad compatibility.
Example Packages — Eight example applications demonstrate different integration patterns:
Documentation Packages — The website package generates Docusaurus-based documentation, while the html package provides Storybook-based interactive demos.
Sources: package.json14-16 package-lock.json6-11 README.md144-163 packages/website/docs/demo-and-examples.md17-41
The core library implements a multi-layer architecture with clear separation of concerns. The following diagram maps the major architectural components to their corresponding code entities:
Graph Layer — The Graph class (and its base AbstractGraph) serves as the primary API entry point. It instantiates and coordinates all major subsystems, automatically registering default plugins, shapes, edge styles, and perimeters.
Data Model Layer — GraphDataModel manages the graph structure through transactional operations. Cell objects form a tree structure representing vertices, edges, and groups, each with associated Geometry and style information.
View and Rendering Layer — GraphView orchestrates the rendering pipeline, transforming Cell objects into CellState objects containing computed, absolute rendering properties. CellRenderer then creates visual Shape instances from these states.
Style System — Stylesheet resolves cell styles by merging default styles with cell-specific overrides. The system uses four registries (ShapeRegistry, EdgeMarkerRegistry, EdgeStyleRegistry, PerimeterRegistry) to map style property values to implementation functions.
Plugin System — Plugins (implementing GraphPlugin interface) provide modular interaction handlers. Default plugins include connection creation, selection management, and vertex/edge manipulation.
Serialization — The Codec and ObjectCodec classes provide XML serialization/deserialization. ModelXmlSerializer offers a convenience wrapper for model persistence with mxGraph XML compatibility.
Global Configuration — Configuration objects (GlobalConfig, StyleDefaultsConfig, StencilShapeConfig) provide centralized defaults that can be modified globally, affecting all Graph instances.
Sources: packages/core/src/view/Graph.ts packages/core/src/view/GraphDataModel.ts packages/core/src/view/GraphView.ts packages/core/src/view/style/Stylesheet.ts packages/core/src/types.ts packages/core/src/serialization/Codec.ts
maxGraph distributes through three primary channels with automated CI/CD pipelines:
npm Package — The core library publishes to the npm registry as @maxgraph/core. The package includes:
lib/esm/) and CommonJS (lib/cjs/)*.d.ts files)css/)images/)i18n/)xsd/)The build process generates the CommonJS package.json file via packages/core/scripts/generate-cjs-package-json.mjs to enable proper module resolution.
Documentation Website — The website deploys to GitHub Pages at maxgraph.github.io/maxGraph, containing:
The website generation workflow copies TypeDoc and Storybook outputs into the Docusaurus build directory for unified deployment.
GitHub Releases — Each version creates a GitHub Release with:
examples.zip — Built Storybook and example applicationswebsite.zip — Complete documentation archive for offline useThe release process is semi-automated: scripts/update-versions.mjs updates version strings, then .github/workflows/create-github-release.yml creates a draft release that maintainers manually review and publish.
Sources: packages/core/package.json18-44 .github/workflows/build.yml .github/workflows/generate-website.yml .github/workflows/create-github-release.yml README.md241-261
CellStyle objects (replacing mxGraph's string-based styles)UndoManagerGraphPlugin interface to add new behaviorsSources: README.md21-33 packages/core/package.json10-17 packages/website/docs/usage/perimeters.md packages/website/docs/usage/plugins.md
maxGraph supports modern browsers with SVG rendering capabilities:
The library detects browser capabilities and platform features through the Client class, which provides static properties for feature detection (e.g., Client.IS_TOUCH, Client.IS_POINTER, Client.IS_MAC).
JavaScript compatibility:
import) and CommonJS (require) formatsTypeScript compatibility:
@maxgraph/ts-support packageSources: README.md38-39 packages/core/README.md18-24 packages/core/package.json6-31 packages/core/src/Client.ts
The Client class provides static properties and methods for configuring paths and detecting the runtime environment:
Path configuration:
Client.basePath — Base path for all URLs (default: .)Client.imageBasePath — Base path for image assets (default: .)Client.setBasePath() / Client.setImageBasePath() — Configuration methodsPlatform detection:
Client.IS_WIN, Client.IS_MAC, Client.IS_CHROMEOS — Operating systemClient.IS_TOUCH, Client.IS_POINTER — Input capabilitiesClient.IS_GC, Client.IS_FF, Client.IS_SF, Client.IS_EDGE — Browser typeClient.IS_IOS, Client.IS_ANDROID — Mobile platformsClient.IS_LOCAL — Detects file:// protocolThese properties enable conditional behavior based on the runtime environment.
Sources: packages/core/src/Client.ts36-213
The current version is stored in packages/core/src/util/Constants.ts as constants.VERSION and synchronized across:
Version updates use scripts/update-versions.mjs to maintain consistency. The release process follows semantic versioning with detailed changelogs in CHANGELOG.md
Release artifacts are published to:
@maxgraph/core packageSources: packages/core/package.json5 scripts/update-versions.mjs CHANGELOG.md1-6
This overview provides the foundation for understanding maxGraph. Related pages provide deeper exploration:
Refresh this wiki