@bazel/esbuild

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

Installation

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 from npm automatically and exposed via toolchains. Add the esbuild_repositories rule to the WORKSPACE:

load("@npm//@bazel/esbuild:esbuild_repositories.bzl", "esbuild_repositories")

esbuild_repositories()

As esbuild is being fetched from npm, the load statement above can cause eager fetches of the @npm external repository. To work around this, it's possible to fetch the @bazel/esbuild package via an http_archive

http_archive(
    name = "bazel_esbuild",
    urls = [
        "https://registry.npmjs.org/@bazel/esbuild/-/esbuild-4.0.0.tgz",
    ],
    strip_prefix = "package",
)

load("@bazel_esbuild//:esbuild_repositories.bzl", "esbuild_repositories")

esbuild_repositories()

Overview

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("@npm//@bazel/esbuild:index.bzl", "esbuild")
load("@npm//@bazel/typescript:index.bzl", "ts_project")

ts_project(
    name = "lib",
    srcs = ["a.ts"],
)

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

The above will create three output files, bundle.js, bundle.js.map 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("@npm//@bazel/esbuild:index.bzl", "esbuild")
load("@npm//@bazel/typescript:index.bzl", "ts_project")

ts_project(
    name = "lib",
    srcs = ["a.ts"],
    deps = [
        "@npm//foo",
    ],
)

esbuild(
    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

esbuild

USAGE

esbuild(name, args, args_file, define, deps, entry_point, entry_points, external, format, launcher,
        link_workspace_root, max_threads, minify, output, output_css, output_dir, output_map,
        platform, sourcemap, sources_content, splitting, srcs, target)

Runs the esbuild bundler under Bazel

For further information about esbuild, see https://esbuild.github.io/

ATTRIBUTES

name

(Name, mandatory): A unique name for this target.

args

(Dictionary: String -> String): 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

Defaults to {}

args_file

(Label): A JSON file containing additional arguments that are passed to esbuild. Note: only one of args or args_file may be set

Defaults to None

define

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

esbuild(
    name = "bundle",
    define = {
        "process.env.NODE_ENV": "production"
    },
)

See https://esbuild.github.io/api/#define for more details

Defaults to {}

deps

(List of labels): A list of direct dependencies that are required to build the bundle

Defaults to []

entry_point

(Label): 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.

Defaults to None

entry_points

(List of labels): 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.

Defaults to []

external

(List of strings): A list of module names that are treated as external and not included in the resulting bundle

See https://esbuild.github.io/api/#external for more details

Defaults to []

format

(String): 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 https://esbuild.github.io/api/#format for more details

Defaults to ""

launcher

(Label, mandatory): Internal use only

link_workspace_root

(Boolean): 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.

Defaults to False

max_threads

(Integer): 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.

Defaults to 0

minify

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

Sets all --minify-* flags

See https://esbuild.github.io/api/#minify for more details

Defaults to False

output

(Label): Name of the output file when bundling

output_css

(Label): 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'.

output_dir

(Boolean): If true, esbuild produces an output directory containing all output files

Defaults to False

output_map

(Label): Name of the output source map when bundling

platform

(String): The platform to bundle for.

See https://esbuild.github.io/api/#platform for more details

Defaults to "browser"

sourcemap

(String): Defines where sourcemaps are output and how they are included in the bundle. By default, a separate .js.map file is generated and referenced by the bundle. If 'external', a separate .js.map 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 .js.map file is created.

See https://esbuild.github.io/api/#sourcemap for more details

Defaults to ""

sources_content

(Boolean): If False, omits the sourcesContent field from generated source maps

See https://esbuild.github.io/api/#sources-content for more details

Defaults to False

splitting

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

See https://esbuild.github.io/api/#splitting and https://esbuild.github.io/api/#entry-points for more details

Defaults to False

srcs

(List of labels): Source files to be made available to esbuild

Defaults to []

target

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

See https://esbuild.github.io/api/#target for more details

Defaults to "es2015"

configure_esbuild_toolchain

USAGE

configure_esbuild_toolchain(name, binary, exec_compatible_with)

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

PARAMETERS

name

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

binary

label for the esbuild binary

exec_compatible_with

list of platform constraints

esbuild_repositories

USAGE

esbuild_repositories(name)

Helper for fetching and setting up the esbuild versions and toolchains

PARAMETERS

name

currently unused

Defaults to ""

Changelog

4.0.0-beta.0 (2021-07-02)

Bug Fixes

• builtin: don't expose any darwin_arm64 repo or toolchains if not supported by the node version (6748383), closes #2779
• builtin: fix npm_install & yarn_install post_install_patches when symlink_node_modules is enabled (5fce733)
• builtin: generated nodejs repository for windows references non-existent file (4487698)
• builtin: propogate tags to both generated targets in generated_file_test (e980107)
• builtin: runfile resolution incorrect if entry starts similarly (3be2902)
• builtin: write stdout/stderr to correct path under chdir (#2681) (99760a5), closes #2680
• esbuild: prefer finding entry_point files in deps rather than srcs (#2692) (5f4bb15)
• esbuild: provide JSModuleInfo of output bundle (#2685) (82ef1a1)
• esbuild: update update script file paths after removal of _README.md (#2695) (f320ef0)
• jasmine: don't assume entry_point is a label as it may now be a dict (3fa2e5f)
• jasmine: unhanded promise rejection causes tests suit to pass (a511f3d), closes 3.7.0/lib/jasmine.js#L267 #2688
• terser: make terser resolve more robust by not assuming a single /terser/ segment in the path (95fc9ba)
• typescript: collect coverage in ts_project (8e7bc1c), closes #2762
• allow for only stderr to be set on npm_package_bin (a04a7ef)
• builtin: add two missing locations where Mac M1 support needs to be declared (ad20275), closes #2733
• builtin: support directory_file_path entry_point in nodejs_binary & nodejs_test when --bazel_patch_module_resolver is set (50e6d1d)
• typescript: fixed "output was not created" error for ts_project with supports_workers (9a3e5c9)
• typescript: repair error reporting when a ts_project is missing declaration=True (5f0be65)
• make generated_file_test .update's visibility same as test rule (#2677) (1ce9dce)

chore

• update Bazel minimum version to LTS (a9c5966)
• builtin: flip default for pkg_npm#validate (16a099e)

Code Refactoring

• typescript: tsconfig default to tsconfig.json (c6ae95c)

Features

• esbuild: allow for .ts, .tsx and .jsx entry points (e3edb28)
• labs: ts_proto_library directly exports commonjs (5f26d0f)
• add package_name to ts_library (d2d4d16)
• builtin: add validate attribute on pkg_npm (39eea25), closes #2782
• builtin: document how nodejs_binary#entry_point can use a direc… (#2579) (fcdcf63)
• cypress: cypress executable toolchain (#2668) (f1f5ee6)
• esbuild: add support for toolchains (#2704) (ae011bf)
• esbuild: filter ts declaration files by default (f83cf48)
• typescript: support typescript 4.3 (e576acd)
• add opt-in exports_directories_only mode to yarn_install and npm_install (defaults to False) (a7200aa)
• support dict style directory_file_path entry_point in nodejs_binary, nodejs_test & jasmine_node_test (5fafe19)
• support directory_file_path entry_point in npm_umd_bundle (8bee1b3)

Performance Improvements

• cypress: export cypress as a directory symlink (8ea7ff4)

BREAKING CHANGES

• builtin: The @bazel/runfiles lookupDirectory method has been removed. Use the resolve method instead
• for our 4.0, rules_nodejs requires the current LTS of Bazel. This is a policy restriction to save us time tracking down support issues on older versions of Bazel, not a technical one. You can patch this check out locally if you really need to continue using older Bazel, but this puts you on unsupported track.
• builtin: Just follow the printed instructions to either set the right package_name or disable the validation
• typescript: ts_project tsconfig attribute now defaults to just 'tsconfig.json' rather than '[name].json'