@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

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("//@bazel/esbuild:index.bzl", "esbuild")
load("//packages/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("//@bazel/esbuild:index.bzl", "esbuild")
load("//packages/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(name, output_dir, kwargs)

esbuild helper macro around the esbuild_bundle rule

For a full list of attributes, see the esbuild_bundle rule

PARAMETERS

name

The name used for this rule and output files

output_dir

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

Defaults to False

kwargs

All other args from esbuild_bundle

Changelog

3.2.0 (2021-02-13)

Bug Fixes

• multi-linker linking when only output files in sandbox (ebb9481)
• builtin: fix coverage source file paths (ae4ec78)
• docs: fix formatting of nodejs_binary#chdir (1caced8)
• docs: fix regex that replaces //packages with @bazel (c31c0b6)
• docs: version selector shows 3.x (38f4f78)
• typescript: allow up to typescript 4.2, add tests for 3.7-4.1 (ea168a7)
• typescript: fixed build for external ts_project targets (c89e0aa)
• version number not edited after release candidate (ac2bb62)

Features

• add esbuild package (e7e5286)
• builtin: add coverage all: true support (8386b97)
• support for nested node_modules in linker (2c2cc6e)