v0.11.15

• Provide options for how to handle legal comments (#919)

  A "legal comment" is considered to be any comment that contains @license or @preserve or that starts with //! or /*!. These comments are preserved in output files by esbuild since that follows the intent of the original authors of the code.

  However, some people want to remove the automatically-generated license information before they distribute their code. To facilitate this, esbuild now provides several options for how to handle legal comments (via --legal-comments= in the CLI and legalComments in the JS API):

  • none: Do not preserve any legal comments
  • inline: Preserve all statement-level legal comments
  • eof: Move all statement-level legal comments to the end of the file
  • linked: Move all statement-level legal comments to a .LEGAL.txt file and link to them with a comment
  • external: Move all statement-level legal comments to a .LEGAL.txt file but to not link to them

  The default behavior is eof when bundling and inline otherwise.

• Add onStart and onEnd callbacks to the plugin API

  Plugins can now register callbacks to run when a build is started and ended:

  const result = await esbuild.build({
    ...
    incremental: true,
    plugins: [{
      name: 'example',
      setup(build) {
        build.onStart(() => console.log('build started'))
        build.onEnd(result => console.log('build ended', result))
      },
    }],
  })
  await result.rebuild()

  One benefit of onStart and onEnd is that they are run for all builds including rebuilds (relevant for incremental mode, watch mode, or serve mode), so they should be a good place to do work related to the build lifecycle.

  More details:

  • build.onStart()

    You should not use an onStart callback for initialization since it can be run multiple times. If you want to initialize something, just put your plugin initialization code directly inside the setup function instead.

    The onStart callback can be async and can return a promise. However, the build does not wait for the promise to be resolved before starting, so a slow onStart callback will not necessarily slow down the build. All onStart callbacks are also run concurrently, not consecutively. The returned promise is purely for error reporting, and matters when the onStart callback needs to do an asynchronous operation that may fail. If your plugin needs to wait for an asynchronous task in onStart to complete before any onResolve or onLoad callbacks are run, you will need to have your onResolve or onLoad callbacks block on that task from onStart.

    Note that onStart callbacks do not have the ability to mutate build.initialOptions. The initial options can only be modified within the setup function and are consumed once the setup function returns. All rebuilds use the same initial options so the initial options are never re-consumed, and modifications to build.initialOptions that are done within onStart are ignored.

  • build.onEnd()

    All onEnd callbacks are run in serial and each callback is given access to the final build result. It can modify the build result before returning and can delay the end of the build by returning a promise. If you want to be able to inspect the build graph, you should set build.initialOptions.metafile = true and the build graph will be returned as the metafile property on the build result object.