docs/esbuild.md

<!-- *********************
  DO NOT EDIT THIS FILE
  It is a generated build output from Stardoc.
  Instead you must edit the .bzl file where the rules are declared,
  or possibly a markdown file next to the .bzl file
 ********************* -->

# esbuild rules for Bazel

The esbuild rules runs the [esbuild](https://github.com/evanw/esbuild) bundler tool with Bazel.
esbuild is an extremely fast JavaScript bundler written in Go, its [current benchmarks](https://esbuild.github.io/faq/#benchmark-details) 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.

```python
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. 

```python
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.

```python
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**

<pre>
esbuild(<a href="#esbuild-name">name</a>, <a href="#esbuild-args">args</a>, <a href="#esbuild-args_json">args_json</a>, <a href="#esbuild-config">config</a>, <a href="#esbuild-define">define</a>, <a href="#esbuild-define_settings">define_settings</a>, <a href="#esbuild-deps">deps</a>, <a href="#esbuild-entry_point">entry_point</a>, <a href="#esbuild-entry_points">entry_points</a>,
        <a href="#esbuild-external">external</a>, <a href="#esbuild-format">format</a>, <a href="#esbuild-launcher">launcher</a>, <a href="#esbuild-link_workspace_root">link_workspace_root</a>, <a href="#esbuild-max_threads">max_threads</a>, <a href="#esbuild-metafile">metafile</a>, <a href="#esbuild-minify">minify</a>, <a href="#esbuild-output">output</a>,
        <a href="#esbuild-output_css">output_css</a>, <a href="#esbuild-output_dir">output_dir</a>, <a href="#esbuild-output_map">output_map</a>, <a href="#esbuild-platform">platform</a>, <a href="#esbuild-sourcemap">sourcemap</a>, <a href="#esbuild-sources_content">sources_content</a>, <a href="#esbuild-splitting">splitting</a>, <a href="#esbuild-srcs">srcs</a>,
        <a href="#esbuild-stamp">stamp</a>, <a href="#esbuild-target">target</a>)
</pre>

Runs the esbuild bundler under Bazel

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

**ATTRIBUTES**


<h4 id="esbuild-name">name</h4>

(*<a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory*): A unique name for this target.


<h4 id="esbuild-args">args</h4>

(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>*): 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 `{}`

<h4 id="esbuild-args_json">args_json</h4>

(*String*): Internal use only

Defaults to `""`

<h4 id="esbuild-config">config</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): 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.  The dependencies of this attribute must provide: Unknown Provider


Defaults to `None`

<h4 id="esbuild-define">define</h4>

(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>*): A dict of global identifier replacements. Values are subject to $(location ...) expansion.
Example:
```python
esbuild(
    name = "bundle",
    define = {
        "process.env.NODE_ENV": "production"
    },
)
```

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

Defaults to `{}`

<h4 id="esbuild-define_settings">define_settings</h4>

(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: Label -> String</a>*): A dict of labels of Starlark build settings and identifiers to be replaced with their values.
Example:
```python
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`](https://github.com/bazelbuild/bazel-skylib/blob/6e30a77347071ab22ce346b6d20cf8912919f644/rules/common_settings.bzl#L24).
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.  The dependencies of this attribute must provide: Unknown Provider


Defaults to `{}`

<h4 id="esbuild-deps">deps</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): A list of direct dependencies that are required to build the bundle

Defaults to `[]`

<h4 id="esbuild-entry_point">entry_point</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): 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`

<h4 id="esbuild-entry_points">entry_points</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): 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 `[]`

<h4 id="esbuild-external">external</h4>

(*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 `[]`

<h4 id="esbuild-format">format</h4>

(*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 `""`

<h4 id="esbuild-launcher">launcher</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>, mandatory*): Internal use only


<h4 id="esbuild-link_workspace_root">link_workspace_root</h4>

(*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`

<h4 id="esbuild-max_threads">max_threads</h4>

(*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`

<h4 id="esbuild-metafile">metafile</h4>

(*Boolean*): if true, esbuild creates a metafile along the output

Defaults to `True`

<h4 id="esbuild-minify">minify</h4>

(*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`

<h4 id="esbuild-output">output</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): Name of the output file when bundling


<h4 id="esbuild-output_css">output_css</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): 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'.


<h4 id="esbuild-output_dir">output_dir</h4>

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

Defaults to `False`

<h4 id="esbuild-output_map">output_map</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): Name of the output source map when bundling


<h4 id="esbuild-platform">platform</h4>

(*String*): The platform to bundle for.

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

Defaults to `"browser"`

<h4 id="esbuild-sourcemap">sourcemap</h4>

(*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 `""`

<h4 id="esbuild-sources_content">sources_content</h4>

(*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`

<h4 id="esbuild-splitting">splitting</h4>

(*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`

<h4 id="esbuild-srcs">srcs</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>*): Source files to be made available to esbuild

Defaults to `[]`

<h4 id="esbuild-stamp">stamp</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): 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][stamp] 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][stamp] flag.
        Stamped binaries are not rebuilt unless their dependencies change.
    [stamp]: https://docs.bazel.build/versions/main/user-manual.html#flag--stamp  The dependencies of this attribute must provide: StampSettingInfo


Defaults to `@rules_nodejs//nodejs/stamp:use_stamp_flag`

<h4 id="esbuild-target">target</h4>

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

<pre>
configure_esbuild_toolchain(<a href="#configure_esbuild_toolchain-name">name</a>, <a href="#configure_esbuild_toolchain-binary">binary</a>, <a href="#configure_esbuild_toolchain-exec_compatible_with">exec_compatible_with</a>)
</pre>

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

**PARAMETERS**


<h4 id="configure_esbuild_toolchain-name">name</h4>

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



<h4 id="configure_esbuild_toolchain-binary">binary</h4>

label for the esbuild binary



<h4 id="configure_esbuild_toolchain-exec_compatible_with">exec_compatible_with</h4>

list of platform constraints




## esbuild_config

**USAGE**

<pre>
esbuild_config(<a href="#esbuild_config-name">name</a>, <a href="#esbuild_config-config_file">config_file</a>, <a href="#esbuild_config-srcs">srcs</a>, <a href="#esbuild_config-deps">deps</a>, <a href="#esbuild_config-kwargs">kwargs</a>)
</pre>

Macro for an esbuild configuration file and its assoicated dependencies

**PARAMETERS**


<h4 id="esbuild_config-name">name</h4>

Unique name for this rule



<h4 id="esbuild_config-config_file">config_file</h4>

The configuration file / entrypoint



<h4 id="esbuild_config-srcs">srcs</h4>

List of source files referenced by the configuration

Defaults to `[]`

<h4 id="esbuild_config-deps">deps</h4>

List of dependencies required for this configuration

Defaults to `[]`

<h4 id="esbuild_config-kwargs">kwargs</h4>

Any other common attributes




## esbuild_repositories

**USAGE**

<pre>
esbuild_repositories(<a href="#esbuild_repositories-npm_repository">npm_repository</a>, <a href="#esbuild_repositories-name">name</a>, <a href="#esbuild_repositories-npm_args">npm_args</a>, <a href="#esbuild_repositories-kwargs">kwargs</a>)
</pre>

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](https://github.com/bazelbuild/bazel/blob/4.2.1/src/main/java/com/google/devtools/build/lib/bazel/repository/downloader/UrlRewriterConfig.java#L66)

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


**PARAMETERS**


<h4 id="esbuild_repositories-npm_repository">npm_repository</h4>

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



<h4 id="esbuild_repositories-name">name</h4>

currently unused

Defaults to `""`

<h4 id="esbuild_repositories-npm_args">npm_args</h4>

additional args to pass to the npm install rule

Defaults to `[]`

<h4 id="esbuild_repositories-kwargs">kwargs</h4>

additional named parameters to the npm_install rule