docs: add a dedicated tree-shaking page - #1143
Conversation
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.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (7)
🚧 Files skipped from review as they are similar to previous changes (6)
WalkthroughThe PR adds a dedicated tree-shaking guide, updates related documentation and examples, and adds tests that verify default plugin and style-element registration counts. ChangesTree-shaking guidance
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related issues
Possibly related PRs
Suggested labels: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
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. Comment |
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (1)
packages/core/__tests__/view/register-style-elements.test.ts (1)
60-65: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick winGuarantee cleanup for
addSpy.
addSpy.mockRestore()runs only after the assertion. If registration or the assertion throws, the spy stays installed unless the Jest configuration enablesrestoreMocks. Restore mocks inafterEach, or wrap the registration and assertion intry/finally. Jest documentsmockRestore()for spies andrestoreMocksfor 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
📒 Files selected for processing (18)
README.mdpackages/core/__tests__/view/plugin/index.test.tspackages/core/__tests__/view/register-style-elements.test.tspackages/website/docs/demo-and-examples.mdpackages/website/docs/getting-started.mdxpackages/website/docs/intro.mdpackages/website/docs/usage/cell-handlers.mdpackages/website/docs/usage/codecs.mdpackages/website/docs/usage/css-and-images.mdpackages/website/docs/usage/edge-styles.mdpackages/website/docs/usage/global-configuration.mdpackages/website/docs/usage/graph.mdpackages/website/docs/usage/i18n.mdpackages/website/docs/usage/image-bundles.mdpackages/website/docs/usage/migrate-from-mxgraph.mdpackages/website/docs/usage/perimeters.mdpackages/website/docs/usage/plugins.mdpackages/website/docs/usage/tree-shaking.md
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.
|
|
Review feedback addressed in 1f8e05c. All seven points were valid; here is what changed for each.
Qualify the plugin-loading statement in 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 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 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, Validated locally: 561 tests over 62 suites, lint, and the Docusaurus build with |



Closes #781
Overview
Tree-shaking is one of the reasons maxGraph exists, but the documentation only mentioned it in passing, scattered over the
Graphand 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-Shakingpage in theUsagesection, covering:sideEffectsdeclaration, the explicit registration of the built-ins, and how this improved release after releaseGraphbased application, which trims whatGraphloads instead of adding to an empty graph, so the application keeps running and can be measured at every stepThe 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
Graphloads. 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
GraphtoBaseGraph, including bundle measurement and troubleshooting tips.