Spell out tree-shaking, sideEffects: false, and polyfills

📚 Docs or angular.io bug report

Description

To obtain the benefits of webpack tree-shaking, the recommendation is to correctly set the sideEffects: property in package.json files for libraries and apps.

In a recent Angular.io blog post about strict mode and improving build size, it’s recommended that sideEffects: false be set in the app package.json. Also, if you create a new app using ng g app --strict you’ll get this projects/app/src/app/project.json:

{
  "name": "app",
  "private": true,
  "description_1": "This is a special package.json file that is not used by package managers.",
  "description_2": "It is used to tell the tools and bundlers whether the code under this directory is free of code with non-local side-effect. Any code that does have non-local side-effects can't be well optimized (tree-shaken) and will result in unnecessary increased payload size.",
  "description_3": "It should be safe to set this option to 'false' for new applications, but existing code bases could be broken when built with the production config if the application code does contain non-local side-effects that the application depends on.",
  "description_4": "To learn more about this file see: https://angular.io/config/app-package-json.",
  "sideEffects": false
}

My experience with polyfills.ts is that it’s side-effect-ful (by definition it’s side-effect-ful, and it imports zone like so:

import 'zone.js/dist/zone';

Request

Please add documentation clarifying whether polyfills should be listed as a sideEffects file or not, and if not, why.

What’s the affected URL?**

https://angular.io/guide/strict-mode

[johncrim]

FYI, my app completely broke when built with --prod only using a package.json with sideEffects: false - it wouldn’t start at all, no errors on the console. Based on my testing, I have found the following, which may be useful in the docs:

• The impact of a sideEffects: field are only present in --prod mode - so make sure you test in prod (obvious, but worth spelling out for some).
• The main.ts file is side-effect-ful, meaning you don’t want it tree-shaken. If it is tree-shaken the app won’t start.
• The polyfills.ts file is also side-effect-ful, so you probably don’t want it tree-shaken. But I haven’t done much testing to verify that it doesn’t work when tree-shaken - so far it seems to work even when tree-shaken, but it could be working b/c it mostly references zone.js, and zone.js doesn’t have "sideEffects": false (I also created this issue for that).
• If your app package.json is in a subdirectory of the directory containing main.ts and polyfills.ts (and it should also be in a directory containing all your other app typescript files), then you don’t need to exclude them from the “no side-effects” list, so you can use:

   "sideEffects": false

• If your app package.json is in the directory containing main.ts and polyfills.ts, or in a parent directory of that directory, then you need to mark them as side-effects files, like:

  "sideEffects": [
    "main.ts",
    "polyfills.ts"
  ]

Hope that helps.

[alan-agius4]

Thanks for reporting this issue. This issue is now obsolete due to changes in the recent releases.