Tree-Shaking Scripts

This folder contains the supported maintenance scripts for the @babylonjs/core tree-shaking split. These scripts keep the pure import surface, side-effect metadata, generated barrels, generated warning stubs, and bundle smoke tests in sync.

Most contributors should use the npm run ... commands from the repository root instead of invoking the .mjs files directly. Direct script invocation is useful when debugging a single tool, running with --verbose, or using --dry-run before writing generated output.

The one-off migration helpers used to create the split live in migration/. They are kept for reference and follow-up migration work, but they are not part of the normal contributor workflow.

Quick Reference

Run this after changing files that affect tree-shaking behavior:

npm run check:treeshaking-all

Run this when source changes intentionally alter generated tree-shaking metadata:

npm run update:manifest
npm run generate:pure-barrels
npm run generate:side-effect-stubs
npm run check:treeshaking-all

How The Scripts Fit Together

Tree-shaking support is maintained through three related data sets:

1. scripts/treeshaking/side-effects-manifest.json records which @babylonjs/core source files have module-level side effects.
2. Generated pure.ts barrels expose side-effect-free import paths by re-exporting .pure.ts files, side-effect-free plain .ts files, and child pure.ts barrels.
3. Generated side-effect stubs add helpful missing-import warnings for methods and properties declared through .types.ts module augmentations.

The manifest is the input for both pure barrel generation and the public package sideEffects field. If a source file gains or loses module-level side effects, regenerate the manifest first, then regenerate or check the consumers of that manifest.

Package Wiring

The supported scripts are wired into the repository in a few places:

Supported Scripts

auditSideEffects.mjs

Scans packages/dev/core/src and reports files with module-level side effects. The scanner recognizes patterns such as RegisterClass(...), prototype assignments, shader store registration, node constructor registration, bare top-level calls, static class property assignments, and declare module augmentations.

Common commands:

npm run audit:side-effects
npm run update:manifest
node scripts/treeshaking/auditSideEffects.mjs --json
node scripts/treeshaking/auditSideEffects.mjs --out scripts/treeshaking/side-effects-manifest.json

Use npm run update:manifest when intentional source changes alter which files are side-effectful. The generated manifest should be committed when it changes.

checkManifestDrift.mjs

Regenerates the side-effects manifest into a temporary file and compares it to the committed side-effects-manifest.json. It exits nonzero when the committed manifest is stale.

Common command:

npm run check:manifest-drift

If this check fails, run npm run update:manifest, review the manifest diff, and then run npm run check:treeshaking-all.

syncSideEffects.mjs

Reads side-effects-manifest.json and synchronizes the public @babylonjs/core package sideEffects array. This tells bundlers which compiled package files must be retained for module-level side effects.

Common commands:

node scripts/treeshaking/syncSideEffects.mjs
npm run check:side-effects-sync
node scripts/treeshaking/syncSideEffects.mjs --dry-run --verbose

Normal mode writes packages/public/@babylonjs/core/package.json. --check mode validates the package file without writing.

generatePureBarrels.mjs

Generates pure.ts barrels beside index.ts files under packages/dev/core/src. Each generated barrel starts with the standard generated header and re-exports only side-effect-free modules.

Inputs include:

• Existing .pure.ts files.
• The side-effects manifest.
• Existing index.ts export structure.
• Child directory pure.ts barrels.

Common commands:

npm run generate:pure-barrels
npm run check:pure-barrels
node scripts/treeshaking/generatePureBarrels.mjs --dry-run --verbose

Normal mode writes generated pure.ts barrels and formats them. --check mode compares on-disk generated barrels with expected content and also reports stale generated barrels that are no longer expected.

generateSideEffectStubs.mjs

Generates missing-side-effect warning stubs for public methods and properties declared by .types.ts module augmentations. These stubs make an unregistered augmented API fail with a helpful warning instead of a plain TypeError.

The script:

• Scans every .types.ts file under packages/dev/core/src.
• Parses declare module blocks and their exported interfaces.
• Resolves each augmentation target to a .pure.ts or .ts file.
• Injects generated regions between GENERATED_SIDE_EFFECT_STUBS markers.
• Prunes child-class stubs when an ancestor prototype already provides the same warning stub.

Common commands:

npm run generate:side-effect-stubs
node scripts/treeshaking/generateSideEffectStubs.mjs --check
node scripts/treeshaking/generateSideEffectStubs.mjs --dry-run --verbose

Normal mode writes generated regions and removes stale generated regions. --check mode validates existing regions without writing and reports stale generated regions that should be removed.

verifyTreeShaking.mjs

Runs the core generated-invariant checks in sequence:

1. Manifest drift.
2. Pure barrels.
3. Side-effect stubs.

Common command:

npm run check:treeshaking

This is the check used by root lint:check and lint:check-ci. It does not run the bundle smoke tests or the public package sideEffects sync check; use npm run check:treeshaking-all for the larger verification set.

bundleSmokeTest.mjs

Builds representative entry points with Rollup and Webpack and checks that bundle sizes stay within expected bounds. The tests cover cases such as pure utility imports, pure package barrels, side-effectful wrapper imports, pure registration imports, and explicit registration calls.

Common command:

npm run test:treeshaking

Prerequisites:

• packages/dev/core/dist must exist.
• Rollup and Webpack must be available from the repository dependencies.

This script writes temporary files under scripts/treeshaking/.tmp while running and removes them afterward.

injectPureAnnotations.mjs

Post-processes compiled .pure.js files and injects missing /*#__PURE__*/ annotations for top-level call expressions where TypeScript dropped the annotation during emit. This is especially important for static class field initializers that compile into top-level assignments.

Common commands:

npm run inject:pure-annotations
node scripts/treeshaking/injectPureAnnotations.mjs --dry-run --verbose

The script intentionally does not annotate decorator helper calls such as __decorate(...), because those calls mutate prototypes and must not be removed as pure work.

splitRegisterClass.mjs

Transforms files whose only module-level side effect is RegisterClass(...) into the tree-shaking split shape:

• file.pure.ts contains the implementation.
• file.ts is the compatibility wrapper that re-exports the pure implementation and performs RegisterClass(...).

Common commands:

npm run split:register-class
node scripts/treeshaking/splitRegisterClass.mjs --dry-run --file Maths/math.color.ts --verbose

This is a source-modifying maintenance script. Use --dry-run first, review the diff carefully, and run the generated checks afterward.

catalogStaticHelpers.mjs

Reports static helper coverage for selected high-priority classes by comparing class static methods and properties against exported free functions in related *.functions.ts files.

Common commands:

npm run catalog:static-helpers
node scripts/treeshaking/catalogStaticHelpers.mjs --verbose

This is an analysis/reporting tool. It does not write files and is not part of the normal lint or build verification path.

Generated Files And Artifacts

Common Workflows

After Adding Or Removing A .pure.ts File

npm run generate:pure-barrels
npm run check:treeshaking-all

Review and commit any generated pure.ts barrel changes.

After Adding Or Removing A Module-Level Side Effect

npm run update:manifest
node scripts/treeshaking/syncSideEffects.mjs
npm run generate:pure-barrels
npm run check:treeshaking-all

Review and commit manifest, package sideEffects, and generated barrel changes as appropriate.

After Adding A .types.ts Module Augmentation

npm run generate:side-effect-stubs
npm run check:treeshaking-all

Review and commit any generated stub region changes.

Before Opening Or Updating A Tree-Shaking PR

npm run check:treeshaking-all

For broader repository confidence, also run the standard repo checks documented at the root of the project.

Check Modes And Write Modes

Several scripts support both write mode and check mode:

Prefer check mode in CI and write mode during local maintenance. When a check fails, run the matching write command, review the diff, and rerun npm run check:treeshaking-all.

Migration Scripts

The scripts in migration/ were created for one-time migration phases while building the tree-shaking split. They may still be useful for investigation or future large migrations, but they are not CI-supported maintenance commands. Do not add new lint, build, or test dependencies on migration scripts without first promoting and documenting the script as supported tooling in this README.