evanw/esbuild v0.13.0

on GitHub

This release contains backwards-incompatible changes. Since esbuild is before version 1.0.0, these changes have been released as a new minor version to reflect this (as recommended by npm). You should either be pinning the exact version of esbuild in your package.json file or be using a version range syntax that only accepts patch upgrades such as ~0.12.0. See the documentation about semver for more information.

• Allow tree shaking to be force-enabled and force-disabled (#1518, #1610, #1611, #1617)

  This release introduces a breaking change that gives you more control over when tree shaking happens ("tree shaking" here refers to declaration-level dead code removal). Previously esbuild's tree shaking was automatically enabled or disabled for you depending on the situation and there was no manual override to change this. Specifically, tree shaking was only enabled either when bundling was enabled or when the output format was set to iife (i.e. wrapped in an immediately-invoked function expression). This was done to avoid issues with people appending code to output files in the cjs and esm formats and expecting that code to be able to reference code in the output file that isn't otherwise referenced.

  You now have the ability to explicitly force-enable or force-disable tree shaking to bypass this default behavior. This is a breaking change because there is already a setting for tree shaking that does something else, and it has been moved to a separate setting instead. The previous setting allowed you to control whether or not to ignore manual side-effect annotations, which is related to tree shaking since only side-effect free code can be removed as dead code. Specifically you can annotate function calls with /* @__PURE__ */ to indicate that they can be removed if they are not used, and you can annotate packages with "sideEffects": false to indicate that imports of that package can be removed if they are not used. Being able to ignore these annotations is necessary because they are sometimes incorrect. This previous setting has been moved to a separate setting because it actually impacts dead-code removal within expressions, which also applies when minifying with tree-shaking disabled.

  Old behavior

  • CLI
    • Ignore side-effect annotations: --tree-shaking=ignore-annotations
  • JS
    • Ignore side-effect annotations: treeShaking: 'ignore-annotations'
  • Go
    • Ignore side-effect annotations: TreeShaking: api.TreeShakingIgnoreAnnotations

  New behavior

  • CLI
    • Ignore side-effect annotations: --ignore-annotations
    • Force-disable tree shaking: --tree-shaking=false
    • Force-enable tree shaking: --tree-shaking=true
  • JS
    • Ignore side-effect annotations: ignoreAnnotations: true
    • Force-disable tree shaking: treeShaking: false
    • Force-enable tree shaking: treeShaking: true
  • Go
    • Ignore side-effect annotations: IgnoreAnnotations: true
    • Force-disable tree shaking: TreeShaking: api.TreeShakingFalse
    • Force-enable tree shaking: TreeShaking: api.TreeShakingTrue

• The npm package now uses optionalDependencies to install the platform-specific binary executable (#286, #291, #319, #347, #369, #547, #565, #789, #921, #1193, #1270, #1382, #1422, #1450, #1485, #1546, #1547, #1574, #1609)

  This release changes esbuild's installation strategy in an attempt to improve compatibility with edge cases such as custom registries, custom proxies, offline installations, read-only file systems, or when post-install scripts are disabled. It's being treated as a breaking change out of caution because it's a significant change to how esbuild works with JS package managers, and hasn't been widely tested yet.

  The old installation strategy manually downloaded the correct binary executable in a post-install script. The binary executable is hosted in a separate platform-specific npm package such as esbuild-darwin-64. The install script first attempted to download the package via the npm command in case npm had custom network settings configured. If that didn't work, the install script attempted to download the package from https://registry.npmjs.org/ before giving up. This was problematic for many reasons including:

  • Not all of npm's settings can be forwarded due to npm bugs such as npm/cli#2284, and npm has said these bugs will never be fixed.
  • Some people have configured their network environments such that downloading from https://registry.npmjs.org/ will hang instead of either succeeding or failing.
  • The installed package was broken if you used npm --ignore-scripts because then the post-install script wasn't run. Some people enable this option so that malicious packages must be run first before being able to do malicious stuff.

  The new installation strategy automatically downloads the correct binary executable using npm's optionalDependencies feature to depend on all esbuild packages for all platforms but only have the one for the current platform be installed. This is a built-in part of the package manager so my assumption is that it should work correctly in all of these edge cases that currently don't work. And if there's an issue with this, then the problem is with the package manager instead of with esbuild so this should hopefully reduce the maintenance burden on esbuild itself. Changing to this installation strategy has these drawbacks:

  • Old versions of certain package managers (specifically npm and yarn) print lots of useless log messages during the installation, at least one for each platform other than the current one. These messages are harmless and can be ignored. However, they are annoying. There is nothing I can do about this. If you have this problem, one solution is to upgrade your package manager to a newer version.

  • Installation will be significantly slower in old versions of npm, old versions of pnpm, and all versions of yarn. These package managers download all packages for all platforms even though they aren't needed and actually cannot be used. This problem has been fixed in npm and pnpm and the problem has been communicated to yarn: yarnpkg/berry#3317. If you have this problem, one solution is to use a newer version of npm or pnpm as your package manager.

  • This installation strategy does not work if you use npm --no-optional since then the package with the binary executable is not installed. If you have this problem, the solution is to not pass the --no-optional flag when installing packages.

  • There is still a small post-install script but it's now optional in that the esbuild package should still function correctly if post-install scripts are disabled (such as with npm --ignore-scripts). This post-install script optimizes the installed package by replacing the esbuild JavaScript command shim with the actual binary executable at install time. This avoids the overhead of launching another node process when using the esbuild command. So keep in mind that installing with --ignore-scripts will result in a slower esbuild command.

  Despite the drawbacks of the new installation strategy, I believe this change is overall a good thing to move forward with. It should fix edge case scenarios where installing esbuild currently doesn't work at all, and this only comes at the expense of the install script working in a less-optimal way (but still working) if you are using an old version of npm. So I'm going to switch installation strategies and see how it goes.

  The platform-specific binary executables are still hosted on npm in the same way, so anyone who wrote code that downloads builds from npm using the instructions here should not have to change their code: https://esbuild.github.io/getting-started/#download-a-build. However, note that these platform-specific packages no longer specify the bin field in package.json so the esbuild command will no longer be automatically put on your path. The bin field had to be removed because of a collision with the bin field of the esbuild package (now that the esbuild package depends on all of these platform-specific packages as optional dependencies).

In addition to the breaking changes above, the following features are also included in this release:

• Treat x guarded by typeof x !== 'undefined' as side-effect free

  This is a small tree-shaking (i.e. dead code removal) improvement. Global identifier references are considered to potentially have side effects since they will throw a reference error if the global identifier isn't defined, and code with side effects cannot be removed as dead code. However, there's a somewhat-common case where the identifier reference is guarded by a typeof check to check that it's defined before accessing it. With this release, code that does this will now be considered to have no side effects which allows it to be tree-shaken:

  // Original code
  var __foo = typeof foo !== 'undefined' && foo;
  var __bar = typeof bar !== 'undefined' && bar;
  console.log(__bar);
  
  // Old output (with --bundle, which enables tree-shaking)
  var __foo = typeof foo !== 'undefined' && foo;
  var __bar = typeof bar !== 'undefined' && bar;
  console.log(__bar);
  
  // New output (with --bundle, which enables tree-shaking)
  var __bar = typeof bar !== 'undefined' && bar;
  console.log(__bar);