Relocate deprecated API shims so the ESM engine tree-shakes - #9251
Open
willeastcott wants to merge 1 commit into
Open
Relocate deprecated API shims so the ESM engine tree-shakes#9251willeastcott wants to merge 1 commit into
willeastcott wants to merge 1 commit into
Conversation
deprecated.js was the one module listed in package.json sideEffects, and its module-scope prototype patches statically imported AppBase, StandardMaterial, ForwardRenderer, RigidBodyComponentSystem and more. As a result, any import from the ESM package retained most of the engine: a Vec3-only app bundled to 882 KB (229 KB gzip). Each shim now lives on the class it patches as a regular member with @ignore/@deprecated JSDoc (matching Entity#getGuid), so it ships only when the class does and behaves identically. Shims with runtime-computed names (StandardMaterial vertex-color/tint aliases, StandardMaterialOptions litOptions forwarding) remain module-scope helper loops, and the ForwardRenderer#renderComposition patch stays in app-base.js because it needs getApplication and scene code must not import from framework. deprecated.js keeps only side-effect-free aliases and helper functions, and package.json now declares sideEffects: false. Type declarations: the anisotropy entry is removed from the rollup-types-fixup synthesis list since the real accessor now provides the typing (this also fixes its doc text, which was mis-sliced from anisotropyIntensity). Three StandardMaterial setters assign their target properties via Object.assign because tsc declaration emit synthesizes duplicate members from literal this.x assignments to fixup-managed props. A canary test bundles 'import { Vec3 }' against the built ESM tree and fails if it exceeds 10 KB, so a future module-scope side effect cannot silently regress tree-shaking. Measured (esbuild, minified): Vec3-only app 882 KB -> 3.2 KB (229 KB -> 1.1 KB gzip); minimal engine-only cube app 1129 KB -> 1056 KB (297 KB -> 279 KB gzip); full-namespace bundle unchanged. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Build size reportThis PR changes the size of the minified bundles.
|
27 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Any import from the ESM package currently retains most of the engine:
deprecated.jsis the one module listed insideEffects, and its module-scope prototype patches statically importAppBase,StandardMaterial,ForwardRenderer,RigidBodyComponentSystemand more — so bundlers must keep that entire graph even forimport { Vec3 } from 'playcanvas'.This PR moves every prototype-patch shim onto the class it patches, as a regular member with
@ignore/@deprecatedJSDoc (the existingEntity#getGuididiom). Each shim now ships only when its class does and behaves identically at runtime.deprecated.jskeeps only side-effect-free aliases and helper functions, andpackage.jsonnow declares"sideEffects": false.Measured with esbuild (minified), same tree before/after:
import { Vec3 }only@playcanvas/reactand web-components inherit the win automatically. UMD builds are unaffected (all exports retained, shims applied identically).Notes for reviewers:
StandardMaterialvertex-color/tint aliases,StandardMaterialOptionslitOptions forwarding). These are invisible to tsc, so they don't affect the d.ts.ForwardRenderer#renderCompositionis patched fromapp-base.jsbecause it needsgetApplicationand scene code must not import from framework.anisotropyentry is removed from therollup-types-fixupsynthesis list — the real accessor now provides the typing. This also fixes its d.ts doc text, which was previously mis-sliced fromanisotropyIntensity's@propertydoc.StandardMaterialsetters assign their target properties viaObject.assignbecause tsc declaration emit synthesizes duplicate member declarations from literalthis.x = ...assignments to fixup-managed dynamic props.@deprecated-tagged (previously invisible to TypeScript users);@ignorekeeps them out of the API docs, as withEntity#getGuid.test/bundles/treeshake.test.mjsbundlesimport { Vec3 }against the built ESM tree and fails above 10 KB, so a future module-scope side effect can't silently regress tree-shaking.Verified: full unit suite (2337 passing, failures identical to
mainbaseline), all 61 bundle tests (exports parity across all 11 targets, smoke, canary),build:types+test:types, lint, publint, plus a runtime check that all 27 shim behaviors and deprecated exports are unchanged.Checklist
🤖 Generated with Claude Code