Title: Allow third-party packages declaring `sideEffects: false` to opt out of `topLevelSafeMode` · Issue #33893 · angular/angular-cli · GitHub
Open Graph Title: Allow third-party packages declaring `sideEffects: false` to opt out of `topLevelSafeMode` · Issue #33893 · angular/angular-cli
X Title: Allow third-party packages declaring `sideEffects: false` to opt out of `topLevelSafeMode` · Issue #33893 · angular/angular-cli
Description: Command build Description markTopLevelPure only runs in its aggressive mode for files under node_modules/@angular/. For every other package the safe mode is active, and in safe mode no top-level call expression is ever annotated as pure ...
Open Graph Description: Command build Description markTopLevelPure only runs in its aggressive mode for files under node_modules/@angular/. For every other package the safe mode is active, and in safe mode no top-level ca...
X Description: Command build Description markTopLevelPure only runs in its aggressive mode for files under node_modules/@angular/. For every other package the safe mode is active, and in safe mode no top-level ca...
Opengraph URL: https://github.com/angular/angular-cli/issues/33893
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Allow third-party packages declaring `sideEffects: false` to opt out of `topLevelSafeMode`","articleBody":"### Command\n\nbuild\n\n### Description\n\n`markTopLevelPure` only runs in its aggressive mode for files under `node_modules/@angular/`. For every other package the safe mode is active, and in safe mode **no top-level call expression is ever annotated** as pure — only `new` expressions whose callee is in a one-entry allow-list (`InjectionToken`).\n\nThe consequence is that a third-party library cannot be tree-shaken past any top-level function call, even when it correctly declares `sideEffects: false`. And because the pure annotation has to sit at the **call site**, the authors of the called helper cannot fix it from their side either.\n\nThis hits a common pattern in styling libraries — `class-variance-authority`, `tailwind-variants`, and any `defineX()`-style helper:\n\n```ts\n// my-lib/ui/button.cva.ts — the package declares \"sideEffects\": false\nexport const buttonVariants = cva([\"inline-flex items-center\", /* … */]);\n```\n\nEvery such call and its string payload is retained in the consumer's bundle, whether or not the component that uses it is imported.\n\nRelevant code on `main`:\n\n- `packages/angular/build/src/tools/esbuild/javascript-transformer-worker.ts:211-213`\n ```ts\n const safeAngularPackage =\n sideEffectFree && /[\\\\/]node_modules[\\\\/]@angular[\\\\/]/.test(filename);\n const topLevelSafeMode = !safeAngularPackage;\n ```\n- `packages/angular/build/src/tools/oxc/oxc-transform.ts:727` — `if (!pureAnnotate || functionDepth > 0 || classDepth > 0 || topLevelSafeMode) return;`\n- `packages/angular/build/src/tools/oxc/oxc-transform.ts:761-773` — in safe mode only `sideEffectFreeConstructors` is annotated, and that set is `new Set(['InjectionToken'])`.\n\nWorth noting that `sideEffectFree` already derives from the package's own `sideEffects: false` declaration — the field is read, and then trust is narrowed to first-party packages by the path test.\n\n**Impact, measured.** An Angular component library (23 components, `sideEffects: false`, ng-packagr FESM, 35 top-level `cva()` calls), consumed through its published FESM and bundled with the production pipeline (linker → advanced optimizations → esbuild `--minify`):\n\n| imported symbol | as published | with the 35 `cva()` calls manually annotated `/*#__PURE__*/` |\n| --- | --- | --- |\n| a 2-line pure string helper | 76 858 B | **1 472 B** |\n| a component using no variants | 77 229 B | **2 451 B** |\n| a simple button component | 77 452 B | **7 005 B** |\n| the most complex component | 86 513 B | **17 642 B** |\n\nTo be precise about what that figure is: it is what a **minimal** import retains, i.e. the cost of variants belonging to components the consumer never imports. It is not universal waste — an application that uses most of the library needs those variants anyway.\n\n**Measured counter-example**, same library: a real application importing 26 of its symbols (20 of them components) saw its production build change by 198 bytes out of 14 MB when the call sites were annotated — nothing. So the impact scales with how much of the library goes unused. That is the common case for a component library consumed selectively, and it is why the behaviour seems worth changing, but I would rather state the bound than overstate it.\n\nWorth noting too that this only affects consumers of the **published FESM**. Inside a workspace, where each `*.cva.ts` is still its own module, `sideEffects: false` already lets the whole module be dropped and no annotation is needed — the problem is specific to the flattened bundle, where elimination has to happen statement by statement.\n\n**Why the library side cannot solve it.** Same bundle, same function, esbuild 0.28.1:\n\n```js\n// lib.mjs\n// @__NO_SIDE_EFFECTS__\nexport function h(x) { return { v: x }; }\n\n// mid.mjs\nimport { h } from \"./lib.mjs\";\nexport const tiny = 1;\nexport const b1 = h(\"HHHH…\"); // retained\nexport const b2 = /*@__PURE__*/ h(\"KKKK…\"); // eliminated\n```\n\nImporting only `tiny` keeps `b1` and drops `b2`. All three documented forms of `/*@__NO_SIDE_EFFECTS__*/` (line comment before `function`, block comment before `function`, block comment before the arrow of a `const`) left the call in place. Only the call-site annotation works — and the call site belongs to the consuming library, not to the helper. For reference, `cva@1.0.0-beta.8` does declare `sideEffects: false` and still ships no annotations, so an upstream release of the helper does not address this.\n\nI searched open and closed issues for `markTopLevelPure`, `safeAngularPackage`, `pure-toplevel-functions` and related tree-shaking terms before filing, and found nothing covering this.\n\n### Describe the solution you'd like\n\nSome way for an application to opt specific third-party packages into the aggressive mode — i.e. to disable `topLevelSafeMode` for packages it chooses to trust. What shape that takes, and whether it belongs in the build configuration at all, is for you to judge.\n\nThe reason for suggesting an opt-in rather than a change of default: some packages declare `sideEffects: false` incorrectly, so enabling the aggressive mode across all of `node_modules` could break existing apps. An opt-in leaves that call with the team that knows its own dependencies.\n\n### Describe alternatives you've considered\n\n1. **Drop the `node_modules/@angular/` path test**, letting the aggressive mode follow the `sideEffects: false` declaration a package already makes. Semantically the most correct reading of the field — it is precisely a promise that importing the module has no observable side effect — but it changes the default for every dependency at once, with the breakage risk noted above.\n2. **Extend `sideEffectFreeConstructors` into a call-expression allow-list** (e.g. `cva`, `tv`). Cheap, but arbitrary and endless, and it privileges specific libraries.\n3. **Annotate every top-level call site in the library.** This does work — the annotation survives `tsc` and `ng-packagr` into the published FESM. We tried it across three libraries (69 call sites) and then dropped it, because for our own main consumer the benefit measured as zero (the counter-example above); we were not willing to carry the churn and a lint rule for a gain we could not demonstrate. It is also invisible from the outside: nothing in the current behaviour hints that a library author should do this, which is why option 1 or 2 — or simply documenting it — seems more useful than leaving each library to rediscover it.\n","author":{"url":"https://github.com/hebus","@type":"Person","name":"hebus"},"datePublished":"2026-08-20T16:12:47Z","url":"https://github.com/angular/angular-cli/issues/33893"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:516e20ea-2f80-9339-0cd6-b7aa0f9793bf |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | DC3C:1FE434:13423A2:196BBEB:6B01EE13 |
| html-safe-nonce | 13c0ad6f5ccc2205e7dc0f92a6b2d7fefdda2aaab1b2a0adce37caf6e6239bfc |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJEQzNDOjFGRTQzNDoxMzQyM0EyOjE5NkJCRUI6NkIwMUVFMTMiLCJ2aXNpdG9yX2lkIjoiODUyNzAzOTE3ODYxMjAxMDUxNSIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | e27bf2ff090b31802dea9888072a8bdf98ceef6af4d7055a47a875294f2f4d1b |
| hovercard-subject-tag | issue:5205528220 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/angular/angular-cli/33893/issue_layout |
| twitter:image | https://opengraph.githubassets.com/74264fe0d9da8bbb7d63d0402d39f34758967261b5c6b62773b9d8e9ea9dc88c/angular/angular-cli/issues/33893 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/74264fe0d9da8bbb7d63d0402d39f34758967261b5c6b62773b9d8e9ea9dc88c/angular/angular-cli/issues/33893 |
| og:image:alt | Command build Description markTopLevelPure only runs in its aggressive mode for files under node_modules/@angular/. For every other package the safe mode is active, and in safe mode no top-level ca... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | hebus |
| hostname | github.com |
| expected-hostname | github.com |
| None | 87e774ee7c6b3bee0490394e4d3e57ec9dbc956f74b87ea685dc8996c1676456 |
| turbo-cache-control | no-preview |
| go-import | github.com/angular/angular-cli git https://github.com/angular/angular-cli.git |
| octolytics-dimension-user_id | 139426 |
| octolytics-dimension-user_login | angular |
| octolytics-dimension-repository_id | 36891867 |
| octolytics-dimension-repository_nwo | angular/angular-cli |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 36891867 |
| octolytics-dimension-repository_network_root_nwo | angular/angular-cli |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 423dbb54c5e7bfecc838eb387c1435eb3d0e760d |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width