---

title: esbuild layout: default toc: true nav: rule

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

Add an http_archive fetching the esbuild binary for each platform that you need to support.

_ESBUILD_VERSION = "0.8.34"
http_archive(
    name = "esbuild_darwin",
    urls = [
        "https://registry.npmjs.org/esbuild-darwin-64/-/esbuild-darwin-64-%s.tgz" % _ESBUILD_VERSION,
    ],
    strip_prefix = "package",
    build_file_content = """exports_files(["bin/esbuild"])""",
    sha256 = "3bf980b5175df873dd84fd614d57722f3b1b9c7e74929504e26192d23075d5c3",
)

http_archive(
    name = "esbuild_windows",
    urls = [
        "https://registry.npmjs.org/esbuild-windows-64/-/esbuild-windows-64-%s.tgz" % _ESBUILD_VERSION,
    ],
    strip_prefix = "package",
    build_file_content = """exports_files(["esbuild.exe"])""",
    sha256 = "826cd58553e7b6910dd22aba001cd72af34e05c9c3e9af567b5b2a6b1c9f3941",
)

http_archive(
    name = "esbuild_linux",
    urls = [
        "https://registry.npmjs.org/esbuild-linux-64/-/esbuild-linux-64-%s.tgz" % _ESBUILD_VERSION,
    ],
    strip_prefix = "package",
    build_file_content = """exports_files(["bin/esbuild"])""",
    sha256 = "9dff3f5b06fd964a1cbb6aa9ea5ebf797767f1bd2bac71e084fb0bbefeba24a3",
)

These can then be referenced on the tool attribute of the esbuild rule.

esbuild(
    name = "bundle",
    ...
    tool = select({
        "@bazel_tools//src/conditions:darwin": "@esbuild_darwin//:bin/esbuild",
        "@bazel_tools//src/conditions:windows": "@esbuild_windows//:esbuild.exe",
        "@bazel_tools//src/conditions:linux_x86_64": "@esbuild_linux//:bin/esbuild",
    }),
)

It might be useful to wrap this locally in a macro for better reuseability, see packages/esbuild/test/tests.bzl for an example.

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_library")

ts_library(
    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_library")

ts_library(
    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 helper macro around the esbuild_bundle rule

For a full list of attributes, see the esbuild_bundle rule

PARAMETERS

The name used for this rule and output files

If True, produce a code split bundle in an output directory

Defaults to False

All other args from esbuild_bundle