Skip to content

docs: add a dedicated tree-shaking page - #1143

Merged
tbouffard merged 2 commits into
mainfrom
docs/add_tree-shaking_page
Aug 14, 2026
Merged

docs: add a dedicated tree-shaking page#1143
tbouffard merged 2 commits into
mainfrom
docs/add_tree-shaking_page

Conversation

@redfish4ktc

@redfish4ktc redfish4ktc commented Aug 12, 2026

Copy link
Copy Markdown
Member

Closes #781

Overview

Tree-shaking is one of the reasons maxGraph exists, but the documentation only mentioned it in passing, scattered over the Graph and getting started pages. Nothing explained what the library provides and, above all, what an application must do to benefit from it.

This adds a dedicated Tree-Shaking page in the Usage section, covering:

  • what tree-shaking is, why ES modules and side effects matter, and why the result depends on the bundler used by the application
  • what maxGraph provides: the ESM build, the sideEffects declaration, the explicit registration of the built-ins, and how this improved release after release
  • how to register only the shapes, edge styles, perimeters, edge markers, plugins, codecs, i18n and logger the application actually uses
  • how to measure the impact, using the example applications shipped in the repository and the analyzer of your own toolchain
  • a guide for migrating an existing Graph based application, which trims what Graph loads instead of adding to an empty graph, so the application keeps running and can be measured at every step
  • the current limitations, with links to Strategies for Further Tree-Shaking Improvements #665 and its children

The pages describing the features it references now link to it, and the examples list is resynced with the README.

The second checkbox of #781 was already covered by #1048, this PR covers the first one.

Notes

The page states how many built-in shapes, edge styles, perimeters, edge markers and plugins Graph loads. These counts are now asserted in the tests of the corresponding registration functions, with a comment pointing at the page, so adding a built-in element cannot silently make the page wrong.

No screenshot: the change is documentation only. The page can be reviewed by running npm start -w packages/website.

Summary by CodeRabbit

  • Documentation
    • Added comprehensive guidance for reducing bundle size through tree-shaking.
    • Documented selective registration of plugins, styles, codecs, images, and other features.
    • Added migration guidance from Graph to BaseGraph, including bundle measurement and troubleshooting tips.
    • Clarified CSS side effects, default registrations, and feature-specific bundle considerations.
    • Improved links, wording, examples, and recommendations throughout the documentation.
  • Tests
    • Added coverage confirming the documented number of built-in style elements is registered by default.

Tree-shaking is one of the reasons maxGraph exists, but the documentation only mentioned it in passing, scattered over
the Graph and getting started pages. Nothing explained what the library provides and, above all, what an application
must do to benefit from it.

The new page covers what tree-shaking is, why ES modules and side effects matter, why the result depends on the
bundler, what maxGraph provides and how it improved over the releases, and how to register only the shapes, edge
styles, perimeters, edge markers, plugins, codecs, i18n and logger an application actually uses. It closes with a guide
for migrating an existing `Graph` based application, which trims what `Graph` loads instead of adding to an empty
graph, so that the application keeps running and can be measured at every step.

Link the page from the pages describing the features it references, and resync the examples list with the README.

The page states how many built-in shapes, edge styles, perimeters, edge markers and plugins `Graph` loads. Assert these
counts in the tests of the corresponding registration functions, with a comment pointing at the page, so adding a
built-in element cannot silently make it wrong.
@redfish4ktc redfish4ktc added the documentation Improvements or additions to documentation label Aug 12, 2026
@coderabbitai

coderabbitai Bot commented Aug 12, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: fb2bf495-9759-4fe9-a87f-9a047728d083

📥 Commits

Reviewing files that changed from the base of the PR and between 6823531 and 1f8e05c.

📒 Files selected for processing (7)
  • README.md
  • packages/core/__tests__/view/register-style-elements.test.ts
  • packages/website/docs/demo-and-examples.md
  • packages/website/docs/getting-started.mdx
  • packages/website/docs/usage/graph.md
  • packages/website/docs/usage/migrate-from-mxgraph.md
  • packages/website/docs/usage/tree-shaking.md
🚧 Files skipped from review as they are similar to previous changes (6)
  • README.md
  • packages/website/docs/getting-started.mdx
  • packages/website/docs/usage/tree-shaking.md
  • packages/website/docs/usage/graph.md
  • packages/website/docs/usage/migrate-from-mxgraph.md
  • packages/core/tests/view/register-style-elements.test.ts

Walkthrough

The PR adds a dedicated tree-shaking guide, updates related documentation and examples, and adds tests that verify default plugin and style-element registration counts.

Changes

Tree-shaking guidance

Layer / File(s) Summary
Default registration count validation
packages/core/__tests__/view/plugin/index.test.ts, packages/core/__tests__/view/register-style-elements.test.ts
Documents the default plugin count and tests builtin style-element registration counts with mock restoration.
Tree-shaking concepts and registrations
packages/website/docs/usage/tree-shaking.md
Explains bundler behavior, side effects, Graph and BaseGraph, and selective feature registration.
Migration and bundle validation
packages/website/docs/usage/tree-shaking.md
Adds bundle measurement, migration, trimming, troubleshooting, validation, and limitation guidance.
Tree-shaking examples
README.md, packages/website/docs/demo-and-examples.md
Corrects example descriptions and links selective-feature and no-defaults examples.
Cross-document tree-shaking guidance
packages/website/docs/intro.md, packages/website/docs/getting-started.mdx, packages/website/docs/usage/*.md
Links existing guidance to the tree-shaking documentation and clarifies Graph, BaseGraph, plugin, style, codec, i18n, and image registration behavior.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related issues

Possibly related PRs

Suggested labels: skip-changelog

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly identifies the primary change: adding a dedicated tree-shaking documentation page.
Description check ✅ Passed The description provides the issue reference, rationale, detailed scope, testing context, and explanation for omitting screenshots.
Linked Issues check ✅ Passed The changes satisfy issue #781 by documenting tree-shaking practices, BaseGraph usage, selective registration, measurements, and relevant links.
Out of Scope Changes check ✅ Passed The documentation updates, example synchronization, and registration-count tests directly support the tree-shaking documentation objectives.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 6

🧹 Nitpick comments (1)
packages/core/__tests__/view/register-style-elements.test.ts (1)

60-65: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Guarantee cleanup for addSpy.

addSpy.mockRestore() runs only after the assertion. If registration or the assertion throws, the spy stays installed unless the Jest configuration enables restoreMocks. Restore mocks in afterEach, or wrap the registration and assertion in try/finally. Jest documents mockRestore() for spies and restoreMocks for automatic restoration. (jestjs.io)

Proposed cleanup
-    registerDefaultStyleElements();
-
-    expect(addSpy).toHaveBeenCalledTimes(expectedCount);
-    addSpy.mockRestore();
+    try {
+      registerDefaultStyleElements();
+      expect(addSpy).toHaveBeenCalledTimes(expectedCount);
+    } finally {
+      addSpy.mockRestore();
+    }

Source: MCP tools


ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 41711dca-2dd7-4382-8d7d-f649bbb90351

📥 Commits

Reviewing files that changed from the base of the PR and between 34a0d3c and 6823531.

📒 Files selected for processing (18)
  • README.md
  • packages/core/__tests__/view/plugin/index.test.ts
  • packages/core/__tests__/view/register-style-elements.test.ts
  • packages/website/docs/demo-and-examples.md
  • packages/website/docs/getting-started.mdx
  • packages/website/docs/intro.md
  • packages/website/docs/usage/cell-handlers.md
  • packages/website/docs/usage/codecs.md
  • packages/website/docs/usage/css-and-images.md
  • packages/website/docs/usage/edge-styles.md
  • packages/website/docs/usage/global-configuration.md
  • packages/website/docs/usage/graph.md
  • packages/website/docs/usage/i18n.md
  • packages/website/docs/usage/image-bundles.md
  • packages/website/docs/usage/migrate-from-mxgraph.md
  • packages/website/docs/usage/perimeters.md
  • packages/website/docs/usage/plugins.md
  • packages/website/docs/usage/tree-shaking.md

Comment thread packages/website/docs/getting-started.mdx
Comment thread packages/website/docs/usage/graph.md
Comment thread packages/website/docs/usage/tree-shaking.md Outdated
Comment thread packages/website/docs/usage/tree-shaking.md Outdated
Comment thread packages/website/docs/usage/tree-shaking.md Outdated
Comment thread README.md Outdated
Accuracy fixes, all of them cases where the wording claimed more than the code does:

- `Graph` loads the *default* plugins, not every built-in one: `RubberBandHandler` is built-in but not a default. The
  getting-started tip and the mxGraph migration guideline said "all built-ins".
- The Graph page warned that registering the defaults sets a floor on the bundle, without saying why that holds even
  when the caller passes its own `plugins` list. `getDefaultPlugins()` is only called when the argument is omitted, but
  `Graph` imports it either way, so the plugin code is bundled regardless. Spelling that out strengthens the case for
  `BaseGraph` instead of leaving a claim that looks refutable.
- "Each family follows the same pattern: a registry, a granular API and a `registerDefault*` escape hatch" was false for
  three families out of five: plugins use the `plugins` option, codecs use `registerAllCodecs`, i18n and the logger use
  `GlobalConfig`. A reader could go looking for functions that do not exist. Each mechanism is now named, and what the
  families genuinely share, a broad shortcut next to the narrow one, is stated separately.
- "Primarily a configuration change, not an API change" glossed over the constructor, which does change shape. The graph
  API is what stays identical.
- The opening sentence of "Going Further" presented selective loading of shapes and plugins as future work. It was
  quoted verbatim from issue #665, written before `BaseGraph` existed in 0.18.0, and it contradicted the entire page.
  It now says selective loading is available and that what remains is finer-grained modularity.

Wording, in both copies of the examples list: "stories demonstrate" for subject-verb agreement, and "efficient
tree-shaking" without the article, the term being uncountable here.

The introduction also links to the Global Configuration page, which is the catalogue of the registries and
configuration objects the rest of the page tells you to use sparingly.

In the test, `jest.restoreAllMocks()` moves to the shared `afterEach`. `addSpy.mockRestore()` ran only after the
assertion, so a throwing test left the spy installed, `restoreMocks` not being enabled in the Jest configuration. The
shared hook also covers any spy added to this file later.
@sonarqubecloud

Copy link
Copy Markdown

@redfish4ktc

Copy link
Copy Markdown
Member Author

Review feedback addressed in 1f8e05c. All seven points were valid; here is what changed for each.

Graph loads the default plugins, not every built-in one. Correct, RubberBandHandler is built-in but not a default. Fixed in getting-started.mdx and in the mxGraph migration guideline, which both said "all built-ins".

Qualify the plugin-loading statement in graph.md. Correct, and worth stating precisely: getDefaultPlugins() is only called when the plugins argument is omitted, but Graph imports it either way, so the plugin code lands in the bundle even when the caller passes its own list. The warning now says so, which strengthens the case for BaseGraph rather than leaving a claim that looks refutable.

Describe the registration mechanisms separately. Correct, and the wording could have sent readers looking for functions that do not exist. "Each family follows the same pattern: a registry, a granular API and a registerDefault* escape hatch" was false for three families out of five. Each mechanism is now named (registries and register* helpers, the plugins option, the codec functions, GlobalConfig), and what they genuinely share, a broad shortcut next to the narrow one, is stated separately.

Qualify the API-compatibility claim. Agreed, the constructor does change shape. The paragraph now says the graph API is what stays identical, and spells out how construction differs.

Describe the remaining limitation as finer-grained modularity. Best catch of the review. That sentence was quoted verbatim from #665, written before BaseGraph existed in 0.18.0, and it presented as future work the selective loading the whole page explains how to do today. Rewritten: selective loading is available, what remains is finer-grained modularity.

Mirrored example descriptions. Fixed in both copies: "stories demonstrate" for subject-verb agreement, and "efficient tree-shaking" without the article, the term being uncountable here.

Nitpick, addSpy cleanup. Valid, restoreMocks is not enabled in jest.config.cjs. Rather than wrapping the test body in try/finally, jest.restoreAllMocks() moved into the afterEach that already exists in this file. Same guarantee, no noise in the test, and it covers any spy added later.

Validated locally: 561 tests over 62 suites, lint, and the Docusaurus build with onBrokenLinks and onBrokenAnchors set to throw.

@tbouffard
tbouffard merged commit e660a95 into main Aug 14, 2026
14 checks passed
@tbouffard
tbouffard deleted the docs/add_tree-shaking_page branch August 14, 2026 14:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document usage of BaseGraph and advices for optimal tree-shaking

2 participants