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 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.
npm_install(
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")
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.
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("//packages/esbuild:index.bzl", "esbuild")
load("//packages/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("//packages/esbuild:index.bzl", "esbuild")
load("//packages/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
Rules
esbuild
Runs the esbuild bundler under Bazel
For further information about esbuild, see https://esbuild.github.io/
Example usage (generated)
load("@build_bazel_rules_nodejs//packages/esbuild:index.bzl", "esbuild")
esbuild(
# A unique name for this target.
name = "",
# Internal use only
launcher = "",
)
name
A unique name for this target.
args
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
args_json
Internal use only
config
Configuration file used for esbuild, from the esbuild_config macro. Note that options set in this file may get overwritten. See https://github.com/bazelbuild/rules_nodejs/tree/stable/packages/esbuild/test/plugins/BUILD.bazel for examples of using esbuild_config and plugins.
define
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
define_settings
A dict of labels of Starlark build settings and identifiers to be replaced with their values. Example:
load("@bazel_skylib//rules:common_settings.bzl", "string_flag")
string_flag(
name = "api_endpoint",
build_setting_default = "https://example.com/v1",
)
esbuild(
name = "bundle",
define_settings = {
":api_endpoint": "API_ENDPOINT",
},
)
The build setting has to provide BuildSettingInfo
.
The value is automatically converted to a JS literal.
See https://docs.bazel.build/versions/main/skylark/config.html#predefined-settings for more details on Starlark build settings.
deps
A list of direct dependencies that are required to build the bundle
entry_point
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.
entry_points
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.
external
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
format
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
launcher
Internal use only
link_workspace_root
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.
max_threads
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.
metafile
if true, esbuild creates a metafile along the output
minify
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
output
Name of the output file when bundling
output_css
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
If true, esbuild produces an output directory containing all output files
output_map
Name of the output source map when bundling
platform
The platform to bundle for.
See https://esbuild.github.io/api/#platform for more details
sourcemap
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
sources_content
If False, omits the sourcesContent
field from generated source maps
See https://esbuild.github.io/api/#sources-content for more details
splitting
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
srcs
Source files to be made available to esbuild
stamp
Whether to encode build information into the output. Possible values:
@rules_nodejs//nodejs/stamp:always
: Always stamp the build information into the output, even in --nostamp builds. This setting should be avoided, since it potentially causes cache misses remote caching for any downstream actions that depend on it.@rules_nodejs//nodejs/stamp:never
: Always replace build information by constant values. This gives good build result caching.@rules_nodejs//nodejs/stamp:use_stamp_flag
: Embedding of build information is controlled by the --[no]stamp flag. Stamped binaries are not rebuilt unless their dependencies change.
target
Environment target (e.g. es2017, chrome58, firefox57, safari11, edge16, node10, esnext). Default es2015.
See https://esbuild.github.io/api/#target for more details
Macros and Functions
configure_esbuild_toolchain
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")
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 = [],
)
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_config
Macro for an esbuild configuration file and its assoicated dependencies
Example usage (generated)
load("@build_bazel_rules_nodejs//packages/esbuild:index.bzl", "esbuild_config")
esbuild_config(
# Unique name for this rule
name = "",
# The configuration file / entrypoint
config_file = "",
)
name
Unique name for this rule
config_file
The configuration file / entrypoint
srcs
List of source files referenced by the configuration
deps
List of dependencies required for this configuration
kwargs
Any other common attributes
esbuild_repositories
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 (registry.nodejs.org)/(.*) artifactory.build.internal.net/artifactory/$1/$2
You can find some documentation on the rewrite patterns in the Bazel sources: UrlRewriterConfig.java
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")
esbuild_repositories(
# the name of the repository where the @bazel/esbuild package is installed
npm_repository = None,
)
npm_repository
the name of the repository where the @bazel/esbuild package is installed by npm_install or yarn_install.
name
currently unused
npm_args
additional args to pass to the npm install rule
kwargs
additional named parameters to the npm_install rule