v0.14.20

Compare Source

• Fix property mangling and keyword properties (#​1998)

  Previously enabling property mangling with --mangle-props= failed to add a space before property names after a keyword. This bug has been fixed:

  // Original code
  class Foo {
    static foo = {
      get bar() {}
    }
  }
  
  // Old output (with --minify --mangle-props=.)
  class Foo{statics={gett(){}}}
  
  // New output (with --minify --mangle-props=.)
  class Foo{static s={get t(){}}}

v0.14.19

Compare Source

• Special-case const inlining at the top of a scope (#​1317, #​1981)

  The minifier now inlines const variables (even across modules during bundling) if a certain set of specific requirements are met:

  • All const variables to be inlined are at the top of their scope
  • That scope doesn't contain any import or export statements with paths
  • All constants to be inlined are null, undefined, true, false, an integer, or a short real number
  • Any expression outside of a small list of allowed ones stops constant identification

  Practically speaking this basically means that you can trigger this optimization by just putting the constants you want inlined into a separate file (e.g. constants.js) and bundling everything together.

  These specific conditions are present to avoid esbuild unintentionally causing any behavior changes by inlining constants when the variable reference could potentially be evaluated before being declared. It's possible to identify more cases where constants can be inlined but doing so may require complex call graph analysis so it has not been implemented. Although these specific heuristics may change over time, this general approach to constant inlining should continue to work going forward.

  Here's an example:

  // Original code
  const bold = 1 << 0;
  const italic = 1 << 1;
  const underline = 1 << 2;
  const font = bold | italic | underline;
  console.log(font);
  
  // Old output (with --minify --bundle)
  (()=>{var o=1<<0,n=1<<1,c=1<<2,t=o|n|c;console.log(t);})();
  
  // New output (with --minify --bundle)
  (()=>{console.log(7);})();

v0.14.18

Compare Source

• Add the --mangle-cache= feature (#​1977)

  This release adds a cache API for the newly-released --mangle-props= feature. When enabled, all mangled property renamings are recorded in the cache during the initial build. Subsequent builds reuse the renamings stored in the cache and add additional renamings for any newly-added properties. This has a few consequences:

  • You can customize what mangled properties are renamed to by editing the cache before passing it to esbuild (the cache is a map of the original name to the mangled name).

  • The cache serves as a list of all properties that were mangled. You can easily scan it to see if there are any unexpected property renamings.

  • You can disable mangling for individual properties by setting the renamed value to false instead of to a string. This is similar to the --reserve-props= setting but on a per-property basis.

  • You can ensure consistent renaming between builds (e.g. a main-thread file and a web worker, or a library and a plugin). Without this feature, each build would do an independent renaming operation and the mangled property names likely wouldn't be consistent.

  Here's how to use it:

  • CLI

    $ esbuild example.ts --mangle-props=_$ --mangle-cache=cache.json

  • JS API

    let result = await esbuild.build({
      entryPoints: ['example.ts'],
      mangleProps: /_$/,
      mangleCache: {
        customRenaming_: '__c',
        disabledRenaming_: false,
      },
    })
    let updatedMangleCache = result.mangleCache

  • Go API

    result := api.Build(api.BuildOptions{
      EntryPoints: []string{"example.ts"},
      MangleProps: "_$",
      MangleCache: map[string]interface{}{
        "customRenaming_":   "__c",
        "disabledRenaming_": false,
      },
    })
    updatedMangleCache := result.MangleCache

  The above code would do something like the following:

  // Original code
  x = {
    customRenaming_: 1,
    disabledRenaming_: 2,
    otherProp_: 3,
  }
  
  // Generated code
  x = {
    __c: 1,
    disabledRenaming_: 2,
    a: 3
  };
  
  // Updated mangle cache
  {
    "customRenaming_": "__c",
    "disabledRenaming_": false,
    "otherProp_": "a"
  }

• Add opera and ie as possible target environments

  You can now target Opera and/or Internet Explorer using the --target= setting. For example, --target=opera45,ie9 targets Opera 45 and Internet Explorer 9. This change does not add any additional features to esbuild's code transformation pipeline to transform newer syntax so that it works in Internet Explorer. It just adds information about what features are supported in these browsers to esbuild's internal feature compatibility table.

• Minify typeof x !== 'undefined' to typeof x < 'u'

  This release introduces a small improvement for code that does a lot of typeof checks against undefined:

  // Original code
  y = typeof x !== 'undefined';
  
  // Old output (with --minify)
  y=typeof x!="undefined";
  
  // New output (with --minify)
  y=typeof x<"u";

  This transformation is only active when minification is enabled, and is disabled if the language target is set lower than ES2020 or if Internet Explorer is set as a target environment. Before ES2020, implementations were allowed to return non-standard values from the typeof operator for a few objects. Internet Explorer took advantage of this to sometimes return the string 'unknown' instead of 'undefined'. But this has been removed from the specification and Internet Explorer was the only engine to do this, so this minification is valid for code that does not need to target Internet Explorer.

v0.14.17

Compare Source

• Attempt to fix an install script issue on Ubuntu Linux (#​1711)

  There have been some reports of esbuild failing to install on Ubuntu Linux for a while now. I haven't been able to reproduce this myself due to lack of reproduction instructions until today, when I learned that the issue only happens when you install node from the Snap Store instead of downloading the official version of node.

  The problem appears to be that when node is installed from the Snap Store, install scripts are run with stderr not being writable? This then appears to cause a problem for esbuild's install script when it uses execFileSync to validate that the esbuild binary is working correctly. This throws the error EACCES: permission denied, write even though this particular command never writes to stderr.

  Node's documentation says that stderr for execFileSync defaults to that of the parent process. Forcing it to 'pipe' instead appears to fix the issue, although I still don't fully understand what's happening or why. I'm publishing this small change regardless to see if it fixes this install script edge case.

• Avoid a syntax error due to --mangle-props=. and super() (#​1976)

  This release fixes an issue where passing --mangle-props=. (i.e. telling esbuild to mangle every single property) caused a syntax error with code like this:

  class Foo {}
  class Bar extends Foo {
    constructor() {
      super();
    }
  }

  The problem was that constructor was being renamed to another method, which then made it no longer a constructor, which meant that super() was now a syntax error. I have added a workaround that avoids renaming any property named constructor so that esbuild doesn't generate a syntax error here.

  Despite this fix, I highly recommend not using --mangle-props=. because your code will almost certainly be broken. You will have to manually add every single property that you don't want mangled to --reserve-props= which is an excessive maintenance burden (e.g. reserve parse to use JSON.parse). Instead I recommend using a common pattern for all properties you intend to be mangled that is unlikely to appear in the APIs you use such as "ends in an underscore." This is an opt-in approach instead of an opt-out approach. It also makes it obvious when reading the code which properties will be mangled and which ones won't be.

v0.14.16

Compare Source

• Support property name mangling with some TypeScript syntax features

  The newly-released --mangle-props= feature previously only affected JavaScript syntax features. This release adds support for using mangle props with certain TypeScript syntax features:

  • TypeScript parameter properties

    Parameter properties are a TypeScript-only shorthand way of initializing a class field directly from the constructor argument list. Previously parameter properties were not treated as properties to be mangled. They should now be handled correctly:

    // Original code
    class Foo {
      constructor(public foo_) {}
    }
    new Foo().foo_;
    
    // Old output (with --minify --mangle-props=_)
    class Foo{constructor(c){this.foo_=c}}new Foo().o;
    
    // New output (with --minify --mangle-props=_)
    class Foo{constructor(o){this.c=o}}new Foo().c;

  • TypeScript namespaces

    Namespaces are a TypeScript-only way to add properties to an object. Previously exported namespace members were not treated as properties to be mangled. They should now be handled correctly:

    // Original code
    namespace ns {
      export let foo_ = 1;
      export function bar_(x) {}
    }
    ns.bar_(ns.foo_);
    
    // Old output (with --minify --mangle-props=_)
    var ns;(e=>{e.foo_=1;function t(a){}e.bar_=t})(ns||={}),ns.e(ns.o);
    
    // New output (with --minify --mangle-props=_)
    var ns;(e=>{e.e=1;function o(p){}e.t=o})(ns||={}),ns.t(ns.e);

• Fix property name mangling for lowered class fields

  This release fixes a compiler crash with --mangle-props= and class fields that need to be transformed to older versions of JavaScript. The problem was that doing this is an unusual case where the mangled property name must be represented as a string instead of as a property name, which previously wasn't implemented. This case should now work correctly:

  // Original code
  class Foo {
    static foo_;
  }
  Foo.foo_ = 0;
  
  // New output (with --mangle-props=_ --target=es6)
  class Foo {
  }
  __publicField(Foo, "a");
  Foo.a = 0;

v0.14.15

Compare Source

• Add property name mangling with --mangle-props= (#​218)

  ⚠️ Using this feature can break your code in subtle ways. Do not use this feature unless you know what you are doing, and you know exactly how it will affect both your code and all of your dependencies. ⚠️

  This release introduces property name mangling, which is similar to an existing feature from the popular UglifyJS and Terser JavaScript minifiers. This setting lets you pass a regular expression to esbuild to tell esbuild to automatically rename all properties that match this regular expression. It's useful when you want to minify certain property names in your code either to make the generated code smaller or to somewhat obfuscate your code's intent.

  Here's an example that uses the regular expression _$ to mangle all properties ending in an underscore, such as foo_:

  $ echo 'console.log({ foo_: 0 }.foo_)' | esbuild --mangle-props=_$
  console.log({ a: 0 }.a);
  

  Only mangling properties that end in an underscore is a reasonable heuristic because normal JS code doesn't typically contain identifiers like that. Browser APIs also don't use this naming convention so this also avoids conflicts with browser APIs. If you want to avoid mangling names such as __defineGetter__ you could consider using a more complex regular expression such as [^_]_$ (i.e. must end in a non-underscore followed by an underscore).

  This is a separate setting instead of being part of the minify setting because it's an unsafe transformation that does not work on arbitrary JavaScript code. It only works if the provided regular expression matches all of the properties that you want mangled and does not match any of the properties that you don't want mangled. It also only works if you do not under any circumstances reference a property name to be mangled as a string. For example, it means you can't use Object.defineProperty(obj, 'prop', ...) or obj['prop'] with a mangled property. Specifically the following syntax constructs are the only ones eligible for property mangling:

  Syntax	Example
  Dot property access	x.foo_
  Dot optional chain	x?.foo_
  Object properties	x = { foo_: y }
  Object methods	x = { foo_() {} }
  Class fields	class x { foo_ = y }
  Class methods	class x { foo_() {} }
  Object destructuring binding	let { foo_: x } = y
  Object destructuring assignment	({ foo_: x } = y)
  JSX element names	<X.foo_></X.foo_>
  JSX attribute names	<X foo_={y} />

  You can avoid property mangling for an individual property by quoting it as a string. However, you must consistently use quotes or no quotes for a given property everywhere for this to work. For example, print({ foo_: 0 }.foo_) will be mangled into print({ a: 0 }.a) while print({ 'foo_': 0 }['foo_']) will not be mangled.

  When using this feature, keep in mind that property names are only consistently mangled within a single esbuild API call but not across esbuild API calls. Each esbuild API call does an independent property mangling operation so output files generated by two different API calls may mangle the same property to two different names, which could cause the resulting code to behave incorrectly.

  If you would like to exclude certain properties from mangling, you can reserve them with the --reserve-props= setting. For example, this uses the regular expression ^__.*__$ to reserve all properties that start and end with two underscores, such as __foo__:

  $ echo 'console.log({ __foo__: 0 }.__foo__)' | esbuild --mangle-props=_$
  console.log({ a: 0 }.a);
  
  $ echo 'console.log({ __foo__: 0 }.__foo__)' | esbuild --mangle-props=_$ "--reserve-props=^__.*__$"
  console.log({ __foo__: 0 }.__foo__);
  

• Mark esbuild as supporting node v12+ (#​1970)

  Someone requested that esbuild populate the engines.node field in package.json. This release adds the following to each package.json file that esbuild publishes:

  "engines": {
    "node": ">=12"
  },

  This was chosen because it's the oldest version of node that's currently still receiving support from the node team, and so is the oldest version of node that esbuild supports: https://nodejs.org/en/about/releases/.

• Remove error recovery for invalid // comments in CSS (#​1965)

  Previously esbuild treated // as a comment in CSS and generated a warning, even though comments in CSS use /* ... */ instead. This allowed you to run esbuild on CSS intended for certain CSS preprocessors that support single-line comments.

  However, some people are changing from another build tool to esbuild and have a code base that relies on // being preserved even though it's nonsense CSS and causes the entire surrounding rule to be discarded by the browser. Presumably this nonsense CSS ended up there at some point due to an incorrectly-configured build pipeline and the site now relies on that entire rule being discarded. If esbuild interprets // as a comment, it could cause the rule to no longer be discarded or even cause something else to happen.

  With this release, esbuild no longer treats // as a comment in CSS. It still warns about it but now passes it through unmodified. This means it's no longer possible to run esbuild on CSS code containing single-line comments but it means that esbuild's behavior regarding these nonsensical CSS rules more accurately represents what happens in a browser.

v0.14.14

Compare Source

• Fix bug with filename hashes and the file loader (#​1957)

  This release fixes a bug where if a file name template has the [hash] placeholder (either --entry-names= or --chunk-names=), the hash that esbuild generates didn't include the content of the string generated by the file loader. Importing a file with the file loader causes the imported file to be copied to the output directory and causes the imported value to be the relative path from the output JS file to that copied file. This bug meant that if the --asset-names= setting also contained [hash] and the file loaded with the file loader was changed, the hash in the copied file name would change but the hash of the JS file would not change, which could potentially result in a stale JS file being loaded. Now the hash of the JS file will be changed too which fixes the reload issue.

• Prefer the import condition for entry points (#​1956)

  The exports field in package.json maps package subpaths to file paths. The mapping can be conditional, which lets it vary in different situations. For example, you can have an import condition that applies when the subpath originated from a JS import statement, and a require condition that applies when the subpath originated from a JS require call. These are supposed to be mutually exclusive according to the specification: https://nodejs.org/api/packages.html#conditional-exports.

  However, there's a situation with esbuild where it's not immediately obvious which one should be applied: when a package name is specified as an entry point. For example, this can happen if you do esbuild --bundle some-pkg on the command line. In this situation some-pkg does not originate from either a JS import statement or a JS require call. Previously esbuild just didn't apply the import or require conditions. But that could result in path resolution failure if the package doesn't provide a back-up default condition, as is the case with the is-plain-object package.

  Starting with this release, esbuild will now use the import condition in this case. This appears to be how Webpack and Rollup handle this situation so this change makes esbuild consistent with other tools in the ecosystem. Parcel (the other major bundler) just doesn't handle this case at all so esbuild's behavior is not at odds with Parcel's behavior here.

• Make parsing of invalid @keyframes rules more robust (#​1959)

  This improves esbuild's parsing of certain malformed @keyframes rules to avoid them affecting the following rule. This fix only affects invalid CSS files, and does not change any behavior for files containing valid CSS. Here's an example of the fix:

  /* Original code */
  @​keyframes x { . }
  @​keyframes y { 1% { a: b; } }
  
  /* Old output (with --minify) */
  @​keyframes x{y{1% {a: b;}}}
  
  /* New output (with --minify) */
  @​keyframes x{.}@​keyframes y{1%{a:b}}