esbuild rules for Bazel

The esbuild rules runs the esbuild bundler tool with Bazel. esbuild is an extremely fast JavaScript bundler written in Go, its current benchmarks show it can be 320x faster that other bundlers


Add the @bazel/esbuild npm packages to your devDependencies in package.json.

npm install --save-dev @bazel/esbuild

or using yarn

yarn add -D @bazel/esbuild

The esbuild binary is fetched automatically for your platform and is exposed via Bazel toolchains. To do this, add the esbuild_repositories rule to your WORKSPACE. You'll need to point it to the repository created by npm_install or yarn_install where the @bazel/esbuild package is fetched. (Typically, this is npm). Set the npm_repository attribute to the name of that repository.

    name = "npm",
    # @bazel/esbuild is a dependency in this package.json
    package_json = "//:package.json",
    package_lock_json = "//:package-lock.json",

load("@build_bazel_rules_nodejs//toolchains/esbuild:esbuild_repositories.bzl", "esbuild_repositories")

esbuild_repositories(npm_repository = "npm")  # Note, npm is the default value for npm_repository

To avoid eagerly fetching all the npm dependencies, this load statement comes from the "Built-in" @build_bazel_rules_nodejs repository rather than from @npm. In rules_nodejs 5.0 we intend to fix this layering violation by having the whole esbuild support distributed independently of rules_nodejs, and not require any package to be installed from npm.

See the API docs for esbuild_repositories for ways to customize how Bazel downloads the esbuild package from npm. Alternatively, advanced users can override the download altogether by defining the esbuild repository earlier in your WORKSPACE file, so that the maybe inside esbuild_repositories is skipped.


The esbuild rule can take a JS or TS dependency tree and bundle it to a single file, or split across multiple files, outputting a directory.

load("//packages/esbuild:index.bzl", "esbuild")
load("//packages/typescript:index.bzl", "ts_project")

    name = "lib",
    srcs = ["a.ts"],

    name = "bundle",
    entry_point = "a.ts",
    deps = [":lib"],

The above will create three output files, bundle.js, and bundle_metadata.json which contains the bundle metadata to aid in debugging and resoloution tracing.

To create a code split bundle, set splitting = True on the esbuild rule.

load("//packages/esbuild:index.bzl", "esbuild")
load("//packages/typescript:index.bzl", "ts_project")

    name = "lib",
    srcs = ["a.ts"],
    deps = [

    name = "bundle",
    entry_point = "a.ts",
    deps = [":lib"],
    splitting = True,

This will create an output directory containing all the code split chunks, along with their sourcemaps files



Runs the esbuild bundler under Bazel

For further information about esbuild, see

Example usage (generated)

load("@build_bazel_rules_nodejs//packages/esbuild:index.bzl", "esbuild")

    # A unique name for this target.
    name = "",
    # Internal use only
    launcher = "",


A unique name for this target.


A dict of extra arguments that are included in the call to esbuild, where the key is the argument name. Values are subject to $(location ...) expansion


Internal use only


Configuration file used for esbuild, from the esbuild_config macro. Note that options set in this file may get overwritten. See for examples of using esbuild_config and plugins.


A dict of global identifier replacements. Values are subject to $(location ...) expansion. Example:

    name = "bundle",
    define = {
        "process.env.NODE_ENV": "production"

See for more details


A list of direct dependencies that are required to build the bundle


The bundle's entry point (e.g. your main.js or app.js or index.js)

This is a shortcut for the entry_points attribute with a single entry. Specify either this attribute or entry_point, but not both.


The bundle's entry points (e.g. your main.js or app.js or index.js)

Specify either this attribute or entry_point, but not both.


A list of module names that are treated as external and not included in the resulting bundle

See for more details


The output format of the bundle, defaults to iife when platform is browser and cjs when platform is node. If performing code splitting or multiple entry_points are specified, defaults to esm.

See for more details


Internal use only

Link the workspace root to the bin_dir to support absolute requires like 'my_wksp/path/to/file'. If source files need to be required then they can be copied to the bin_dir with copy_to_bin.


Sets the GOMAXPROCS variable to limit the number of threads that esbuild can run with. This can be useful if running many esbuild rule invocations in parallel, which has the potential to cause slowdown. For general use, leave this attribute unset.


if true, esbuild creates a metafile along the output


Minifies the bundle with the built in minification. Removes whitespace, shortens identifieres and uses equivalent but shorter syntax.

Sets all --minify-* flags

See for more details


Provides info about the build context, such as stamping.

By default it reads from the bazel command line, such as the --stamp argument. Use this to override values for this target, such as enabling or disabling stamping. You can use the node_context_data rule in @build_bazel_rules_nodejs//internal/node:context.bzl to create a NodeContextInfo.


Name of the output file when bundling


Declare a .css file will be output next to output bundle.

If your JS code contains import statements that import .css files, esbuild will place the content in a file next to the main output file, which you'll need to declare. If your output file is named 'foo.js', you should set this to 'foo.css'.


If true, esbuild produces an output directory containing all output files


Name of the output source map when bundling


The platform to bundle for.

See for more details


Defines where sourcemaps are output and how they are included in the bundle. By default, a separate file is generated and referenced by the bundle. If 'external', a separate file is generated but not referenced by the bundle. If 'inline', a sourcemap is generated and its contents are inlined into the bundle (and no external sourcemap file is created). If 'both', a sourcemap is inlined and a file is created.

See for more details


If False, omits the sourcesContent field from generated source maps

See for more details


If true, esbuild produces an output directory containing all the output files from code splitting for multiple entry points

See and for more details


Source files to be made available to esbuild


Environment target (e.g. es2017, chrome58, firefox57, safari11, edge16, node10, esnext). Default es2015.

See for more details

Macros and Functions


Defines a toolchain for esbuild given the binary path and platform constraints

Example usage (generated)

load("@build_bazel_rules_nodejs//packages/esbuild:index.bzl", "configure_esbuild_toolchain")

    # unique name for this toolchain, generally in the form "esbuild_platform_arch"
    name = "",
    # label for the esbuild binary
    binary = None,
    # list of platform constraints
    exec_compatible_with = [],


unique name for this toolchain, generally in the form "esbuild_platform_arch"


label for the esbuild binary


list of platform constraints


Macro for an esbuild configuration file and its assoicated dependencies

Example usage (generated)

load("@build_bazel_rules_nodejs//packages/esbuild:index.bzl", "esbuild_config")

    # Unique name for this rule
    name = "",
    # The configuration file / entrypoint
    config_file = "",


Unique name for this rule


The configuration file / entrypoint


List of source files referenced by the configuration


List of dependencies required for this configuration


Any other common attributes


Helper for fetching and setting up the esbuild versions and toolchains

This uses Bazel's downloader (via http_archive) to fetch the esbuild package from npm, separately from any npm_install/yarn_install in your WORKSPACE. To configure where the download is from, you make a file containing a rewrite rule like

rewrite (*)$1/$2

You can find some documentation on the rewrite patterns in the Bazel sources:

Then use the --experimental_downloader_config Bazel option to point to your file. For example if you created .bazel_downloader_config you might add to your .bazelrc file:

common --experimental_downloader_config=.bazel_downloader_config

Example usage (generated)

load("@build_bazel_rules_nodejs//packages/esbuild:index.bzl", "esbuild_repositories")



currently unused


the name of the repository where the @bazel/esbuild package is installed by npm_install or yarn_install.


additional args to pass to the npm install rule