v0.14.11

Compare Source

• Fix a bug with enum inlining (#​1903)

  The new TypeScript enum inlining behavior had a bug where it worked correctly if you used export enum Foo but not if you used enum Foo and then later export { Foo }. This release fixes the bug so enum inlining now works correctly in this case.

• Warn about module.exports.foo = ... in ESM (#​1907)

  The module variable is treated as a global variable reference instead of as a CommonJS module reference in ESM code, which can cause problems for people that try to use both CommonJS and ESM exports in the same file. There has been a warning about this since version 0.14.9. However, the warning only covered cases like exports.foo = bar and module.exports = bar but not module.exports.foo = bar. This last case is now handled;

  ▲ [WARNING] The CommonJS "module" variable is treated as a global variable in an ECMAScript module and may not work as expected
  
      example.ts:2:0:
        2 │ module.exports.b = 1
          ╵ ~~~~~~
  
    This file is considered to be an ECMAScript module because of the "export" keyword here:
  
      example.ts:1:0:
        1 │ export let a = 1
          ╵ ~~~~~~
  

• Enable esbuild's CLI with Deno (#​1913)

  This release allows you to use Deno as an esbuild installer, without also needing to use esbuild's JavaScript API. You can now use esbuild's CLI with Deno:

  deno run --allow-all "https://deno.land/x/esbuild@v0.14.11/mod.js" --version
  

v0.14.10

Compare Source

• Enable tree shaking of classes with lowered static fields (#​175)

  If the configured target environment doesn't support static class fields, they are converted into a call to esbuild's __publicField function instead. However, esbuild's tree-shaking pass treated this call as a side effect, which meant that all classes with static fields were ineligible for tree shaking. This release fixes the problem by explicitly ignoring calls to the __publicField function during tree shaking side-effect determination. Tree shaking is now enabled for these classes:

  // Original code
  class Foo { static foo = 'foo' }
  class Bar { static bar = 'bar' }
  new Bar()
  
  // Old output (with --tree-shaking=true --target=es6)
  class Foo {
  }
  __publicField(Foo, "foo", "foo");
  class Bar {
  }
  __publicField(Bar, "bar", "bar");
  new Bar();
  
  // New output (with --tree-shaking=true --target=es6)
  class Bar {
  }
  __publicField(Bar, "bar", "bar");
  new Bar();

• Treat --define:foo=undefined as an undefined literal instead of an identifier (#​1407)

  References to the global variable undefined are automatically replaced with the literal value for undefined, which appears as void 0 when printed. This allows for additional optimizations such as collapsing undefined ?? bar into just bar. However, this substitution was not done for values specified via --define:. As a result, esbuild could potentially miss out on certain optimizations in these cases. With this release, it's now possible to use --define: to substitute something with an undefined literal:

  // Original code
  let win = typeof window !== 'undefined' ? window : {}
  
  // Old output (with --define:window=undefined --minify)
  let win=typeof undefined!="undefined"?undefined:{};
  
  // New output (with --define:window=undefined --minify)
  let win={};

• Add the --drop:debugger flag (#​1809)

  Passing this flag causes all debugger; statements to be removed from the output. This is similar to the drop_debugger: true flag available in the popular UglifyJS and Terser JavaScript minifiers.

• Add the --drop:console flag (#​28)

  Passing this flag causes all console.xyz() API calls to be removed from the output. This is similar to the drop_console: true flag available in the popular UglifyJS and Terser JavaScript minifiers.

  WARNING: Using this flag can introduce bugs into your code! This flag removes the entire call expression including all call arguments. If any of those arguments had important side effects, using this flag will change the behavior of your code. Be very careful when using this flag. If you want to remove console API calls without removing arguments with side effects (which does not introduce bugs), you should mark the relevant API calls as pure instead like this: --pure:console.log --minify.

• Inline calls to certain no-op functions when minifying (#​290, #​907)

  This release makes esbuild inline two types of no-op functions: empty functions and identity functions. These most commonly arise when most of the function body is eliminated as dead code. In the examples below, this happens because we use --define:window.DEBUG=false to cause dead code elimination inside the function body of the resulting if (false) statement. This inlining is a small code size and performance win but, more importantly, it allows for people to use these features to add useful abstractions that improve the development experience without needing to worry about the run-time performance impact.

  An identity function is a function that just returns its argument. Here's an example of inlining an identity function:

  // Original code
  function logCalls(fn) {
    if (window.DEBUG) return function(...args) {
      console.log('calling', fn.name, 'with', args)
      return fn.apply(this, args)
    }
    return fn
  }
  export const foo = logCalls(function foo() {})
  
  // Old output (with --minify --define:window.DEBUG=false --tree-shaking=true)
  function o(n){return n}export const foo=o(function(){});
  
  // New output (with --minify --define:window.DEBUG=false --tree-shaking=true)
  export const foo=function(){};

  An empty function is a function with an empty body. Here's an example of inlining an empty function:

  // Original code
  function assertNotNull(val: Object | null): asserts val is Object {
    if (window.DEBUG && val === null) throw new Error('null assertion failed');
  }
  export const val = getFoo();
  assertNotNull(val);
  console.log(val.bar);
  
  // Old output (with --minify --define:window.DEBUG=false --tree-shaking=true)
  function l(o){}export const val=getFoo();l(val);console.log(val.bar);
  
  // New output (with --minify --define:window.DEBUG=false --tree-shaking=true)
  export const val=getFoo();console.log(val.bar);

  To get this behavior you'll need to use the function keyword to define your function since that causes the definition to be hoisted, which eliminates concerns around initialization order. These features also work across modules, so functions are still inlined even if the definition of the function is in a separate module from the call to the function. To get cross-module function inlining to work, you'll need to have bundling enabled and use the import and export keywords to access the function so that esbuild can see which functions are called. And all of this has been added without an observable impact to compile times.

  I previously wasn't able to add this to esbuild easily because of esbuild's low-pass compilation approach. The compiler only does three full passes over the data for speed. The passes are roughly for parsing, binding, and printing. It's only possible to inline something after binding but it needs to be inlined before printing. Also the way module linking was done made it difficult to roll back uses of symbols that were inlined, so the symbol definitions were not tree shaken even when they became unused due to inlining.

  The linking issue was somewhat resolved when I fixed #​128 in the previous release. To implement cross-module inlining of TypeScript enums, I came up with a hack to defer certain symbol uses until the linking phase, which happens after binding but before printing. Another hack is that inlining of TypeScript enums is done directly in the printer to avoid needing another pass.

  The possibility of these two hacks has unblocked these simple function inlining use cases that are now handled. This isn't a fully general approach because optimal inlining is recursive. Inlining something may open up further inlining opportunities, which either requires multiple iterations or a worklist algorithm, both of which don't work when doing late-stage inlining in the printer. But the function inlining that esbuild now implements is still useful even though it's one level deep, and so I believe it's still worth adding.

v0.14.9

Compare Source

• Implement cross-module tree shaking of TypeScript enum values (#​128)

  If your bundle uses TypeScript enums across multiple files, esbuild is able to inline the enum values as long as you export and import the enum using the ES module export and import keywords. However, this previously still left the definition of the enum in the bundle even when it wasn't used anymore. This was because esbuild's tree shaking (i.e. dead code elimination) is based on information recorded during parsing, and at that point we don't know which imported symbols are inlined enum values and which aren't.

  With this release, esbuild will now remove enum definitions that become unused due to cross-module enum value inlining. Property accesses off of imported symbols are now tracked separately during parsing and then resolved during linking once all inlined enum values are known. This behavior change means esbuild's support for cross-module inlining of TypeScript enums is now finally complete. Here's an example:

  // entry.ts
  import { Foo } from './enum'
  console.log(Foo.Bar)
  
  // enum.ts
  export enum Foo { Bar }

  Bundling the example code above now results in the enum definition being completely removed from the bundle:

  // Old output (with --bundle --minify --format=esm)
  var r=(o=>(o[o.Bar=0]="Bar",o))(r||{});console.log(0);
  
  // New output (with --bundle --minify --format=esm)
  console.log(0);

• Fix a regression with export {} from and CommonJS (#​1890)

  This release fixes a regression that was introduced by the change in 0.14.7 that avoids calling the __toESM wrapper for import statements that are converted to require calls and that don't use the default or __esModule export names. The previous change was correct for the import {} from syntax but not for the export {} from syntax, which meant that in certain cases with re-exported values, the value of the default import could be different than expected. This release fixes the regression.

• Warn about using module or exports in ESM code (#​1887)

  CommonJS export variables cannot be referenced in ESM code. If you do this, they are treated as global variables instead. This release includes a warning for people that try to use both CommonJS and ES module export styles in the same file. Here's an example:

  export enum Something {
    a,
    b,
  }
  module.exports = { a: 1, b: 2 }

  Running esbuild on that code now generates a warning that looks like this:

  ▲ [WARNING] The CommonJS "module" variable is treated as a global variable in an ECMAScript module and may not work as expected
  
      example.ts:5:0:
        5 │ module.exports = { a: 1, b: 2 }
          ╵ ~~~~~~
  
    This file is considered to be an ECMAScript module because of the "export" keyword here:
  
      example.ts:1:0:
        1 │ export enum Something {
          ╵ ~~~~~~
  

v0.14.8

Compare Source

• Add a resolve API for plugins (#​641, #​1652)

  Plugins now have access to a new API called resolve that runs esbuild's path resolution logic and returns the result to the caller. This lets you write plugins that can reuse esbuild's complex built-in path resolution logic to change the inputs and/or adjust the outputs. Here's an example:

  let examplePlugin = {
    name: 'example',
    setup(build) {
      build.onResolve({ filter: /^example$/ }, async () => {
        const result = await build.resolve('./foo', { resolveDir: '/bar' })
        if (result.errors.length > 0) return result
        return { ...result, external: true }
      })
    },
  }

  This plugin intercepts imports to the path example, tells esbuild to resolve the import ./foo in the directory /bar, and then forces whatever path esbuild returns to be considered external. Here are some additional details:

  • If you don't pass the optional resolveDir parameter, esbuild will still run onResolve plugin callbacks but will not attempt any path resolution itself. All of esbuild's path resolution logic depends on the resolveDir parameter including looking for packages in node_modules directories (since it needs to know where those node_modules directories might be).

  • If you want to resolve a file name in a specific directory, make sure the input path starts with ./. Otherwise the input path will be treated as a package path instead of a relative path. This behavior is identical to esbuild's normal path resolution logic.

  • If path resolution fails, the errors property on the returned object will be a non-empty array containing the error information. This function does not always throw an error when it fails. You need to check for errors after calling it.

  • The behavior of this function depends on the build configuration. That's why it's a property of the build object instead of being a top-level API call. This also means you can't call it until all plugin setup functions have finished since these give plugins the opportunity to adjust the build configuration before it's frozen at the start of the build. So the new resolve function is going to be most useful inside your onResolve and/or onLoad callbacks.

  • There is currently no attempt made to detect infinite path resolution loops. Calling resolve from within onResolve with the same parameters is almost certainly a bad idea.

• Avoid the CJS-to-ESM wrapper in some cases (#​1831)

  Import statements are converted into require() calls when the output format is set to CommonJS. To convert from CommonJS semantics to ES module semantics, esbuild wraps the return value in a call to esbuild's __toESM() helper function. However, the conversion is only needed if it's possible that the exports named default or __esModule could be accessed.

  This release avoids calling this helper function in cases where esbuild knows it's impossible for the default or __esModule exports to be accessed, which results in smaller and faster code. To get this behavior, you have to use the import {} from import syntax:

  // Original code
  import { readFile } from "fs";
  readFile();
  
  // Old output (with --format=cjs)
  var __toESM = (module, isNodeMode) => {
    ...
  };
  var import_fs = __toESM(require("fs"));
  (0, import_fs.readFile)();
  
  // New output (with --format=cjs)
  var import_fs = require("fs");
  (0, import_fs.readFile)();

• Strip overwritten function declarations when minifying (#​610)

  JavaScript allows functions to be re-declared, with each declaration overwriting the previous declaration. This type of code can sometimes be emitted by automatic code generators. With this release, esbuild now takes this behavior into account when minifying to drop all but the last declaration for a given function:

  // Original code
  function foo() { console.log(1) }
  function foo() { console.log(2) }
  
  // Old output (with --minify)
  function foo(){console.log(1)}function foo(){console.log(2)}
  
  // New output (with --minify)
  function foo(){console.log(2)}

• Add support for the Linux IBM Z 64-bit Big Endian platform (#​1864)

  With this release, the esbuild package now includes a Linux binary executable for the IBM System/390 64-bit architecture. This new platform was contributed by @​shahidhs-ibm.

• Allow whitespace around : in JSX elements (#​1877)

  This release allows you to write the JSX <rdf:Description rdf:ID="foo" /> as <rdf : Description rdf : ID="foo" /> instead. Doing this is not forbidden by the JSX specification. While this doesn't work in TypeScript, it does work with other JSX parsers in the ecosystem, so support for this has been added to esbuild.