Built-in rules

These rules are available without any npm installation, via the WORKSPACE install of the build_bazel_rules_nodejs workspace. This is necessary to bootstrap Bazel to run the package manager to download other rules from NPM.

node_repositories

To be run in user’s WORKSPACE to install rules_nodejs dependencies.

This rule sets up node, npm, and yarn. The versions of these tools can be specified in one of three ways

Simplest Usage

Specify no explicit versions. This will download and use the latest NodeJS & Yarn that were available when the version of rules_nodejs you’re using was released. Note that you can skip calling node_repositories in your WORKSPACE file - if you later try to yarn_install or npm_install, we’ll automatically select this simple usage for you.

Forced version(s)

You can select the version of NodeJS and/or Yarn to download & use by specifying it when you call node_repositories, using a value that matches a known version (see the default values)

Using a custom version

You can pass in a custom list of NodeJS and/or Yarn repositories and URLs for node_resositories to use.

Custom NodeJS versions

To specify custom NodeJS versions, use the node_repositories attribute

node_repositories(
    node_repositories = {
        "10.10.0-darwin_amd64": ("node-v10.10.0-darwin-x64.tar.gz", "node-v10.10.0-darwin-x64", "00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e"),
        "10.10.0-linux_amd64": ("node-v10.10.0-linux-x64.tar.xz", "node-v10.10.0-linux-x64", "686d2c7b7698097e67bcd68edc3d6b5d28d81f62436c7cf9e7779d134ec262a9"),
        "10.10.0-windows_amd64": ("node-v10.10.0-win-x64.zip", "node-v10.10.0-win-x64", "70c46e6451798be9d052b700ce5dadccb75cf917f6bf0d6ed54344c856830cfb"),
    },
)

These can be mapped to a custom download URL, using node_urls

node_repositories(
    node_version = "10.10.0",
    node_repositories = {"10.10.0-darwin_amd64": ("node-v10.10.0-darwin-x64.tar.gz", "node-v10.10.0-darwin-x64", "00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e")},
    node_urls = ["https://mycorpproxy/mirror/node/v{version}/{filename}"],
)

A Mac client will try to download node from https://mycorpproxy/mirror/node/v10.10.0/node-v10.10.0-darwin-x64.tar.gz and expect that file to have sha256sum 00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e

Custom Yarn versions

To specify custom Yarn versions, use the yarn_repositories attribute

node_repositories(
    yarn_repositories = {
        "1.12.1": ("yarn-v1.12.1.tar.gz", "yarn-v1.12.1", "09bea8f4ec41e9079fa03093d3b2db7ac5c5331852236d63815f8df42b3ba88d"),
    },
)

Like node_urls, the yarn_urls attribute can be used to provide a list of custom URLs to use to download yarn

node_repositories(
    yarn_repositories = {
        "1.12.1": ("yarn-v1.12.1.tar.gz", "yarn-v1.12.1", "09bea8f4ec41e9079fa03093d3b2db7ac5c5331852236d63815f8df42b3ba88d"),
    },
    yarn_version = "1.12.1",
    yarn_urls = [
        "https://github.com/yarnpkg/yarn/releases/download/v{version}/{filename}",
    ],
)

Will download yarn from https://github.com/yarnpkg/yarn/releases/download/v1.2.1/yarn-v1.12.1.tar.gz and expect the file to have sha256sum 09bea8f4ec41e9079fa03093d3b2db7ac5c5331852236d63815f8df42b3ba88d.

Using a local version

To avoid downloads, you can check in vendored copies of NodeJS and/or Yarn and set vendored_node and or vendored_yarn to point to those before calling node_repositories. You can also point to a location where node is installed on your computer, but we don’t recommend this because it leads to version skew between you, your coworkers, and your Continuous Integration environment. It also ties your build to a single platform, preventing you from cross-compiling into a Linux docker image on Mac for example.

See the the repositories documentation for how to use the resulting repositories.

Manual install

You can optionally pass a package_json array to node_repositories. This lets you use Bazel’s version of yarn or npm, yet always run the package manager yourself. This is an advanced scenario you can use in place of the npm_install or yarn_install rules, but we don’t recommend it, and might remove it in the future.

load("@build_bazel_rules_nodejs//:index.bzl", "node_repositories")
node_repositories(package_json = ["//:package.json", "//subpkg:package.json"])

Running bazel run @nodejs//:yarn_node_repositories in this repo would create /node_modules and /subpkg/node_modules.

Note that the dependency installation scripts will run in each subpackage indicated by the package_json attribute.

node_repositories(name, node_repositories, node_urls, node_version, package_json, preserve_symlinks,
                  vendored_node, vendored_yarn, yarn_repositories, yarn_urls, yarn_version)

ATTRIBUTES

nodejs_binary

Runs some JavaScript code in NodeJS.

nodejs_binary(name, configuration_env_vars, data, default_env_vars, entry_point,
              link_workspace_root, node_modules, templated_args)

ATTRIBUTES

nodejs_binary(
    name = "my_binary",
    ...
    entry_point = ":file.js",
)

ts_library(
    name = "main",
    srcs = ["main.ts"],
)

nodejs_binary(
    name = "bin",
    data = [":main"]
    entry_point = ":main.ts",
)

filegroup(
    name = "entry_file",
    srcs = ["main.js"],
)

nodejs_binary(
    name = "my_binary",
    entry_point = ":entry_file",
)

nodejs_binary(
    name = "history-server",
    entry_point = "@npm//:node_modules/history-server/modules/cli.js",
    data = ["@npm//history-server"],
)

nodejs_binary(
    name = "my_binary",
    ...
    node_modules = "//:node_modules",
)

nodejs_binary(
    name = "my_binary",
    ...
    data = [
        "@npm//foo",
        "@npm//bar",
        ...
    ],
)

jasmine_node_test(
    name = "my_test",
    ...
    deps = [
        "@npm//jasmine",
        "@npm//foo",
        "@npm//bar",
        ...
    ],
)

nodejs_test(
    name = "my_test",
    data = [":bootstrap.js"],
    templated_args = ["--node_options=--require=$$(rlocation $(rootpath :bootstrap.js))"],
)

nodejs_test(
    name = "my_test",
    data = [":some_file"],
    entry_point = ":my_test.js",
    templated_args = ["$(rootpath :some_file)"],
)

const runfiles = require(process.env['BAZEL_NODE_RUNFILES_HELPER']);
const args = process.argv.slice(2);
const some_file = runfiles.resolveWorkspaceRelative(args[0]);

nodejs_test

Identical to nodejs_binary, except this can be used with bazel test as well. When the binary returns zero exit code, the test passes; otherwise it fails.

nodejs_test is a convenient way to write a novel kind of test based on running your own test runner. For example, the ts-api-guardian library has a way to assert the public API of a TypeScript program, and uses nodejs_test here: https://github.com/angular/angular/blob/master/tools/ts-api-guardian/index.bzl

If you just want to run a standard test using a test runner from npm, use the generated *_test target created by npm_install/yarn_install, such as mocha_test. Some test runners like Karma and Jasmine have custom rules with added features, e.g. jasmine_node_test.

Bazel always runs tests with a working directory set to your workspace root. If your test needs to run in a different directory, you can write a process.chdir helper script and invoke it before the test with a --require argument, like templated_args = ["--node_options=--require=./$(rootpath chdir.js)"]. See rules_nodejs/internal/node/test/chdir for an example.

To debug a Node.js test, we recommend saving a group of flags together in a “config”. Put this in your tools/bazel.rc so it’s shared with your team:

# Enable debugging tests with --config=debug
test:debug --test_arg=--node_options=--inspect-brk --test_output=streamed --test_strategy=exclusive --test_timeout=9999 --nocache_test_results

Now you can add --config=debug to any bazel test command line. The runtime will pause before executing the program, allowing you to connect a remote debugger.

nodejs_test(name, configuration_env_vars, data, default_env_vars, entry_point, expected_exit_code,
            link_workspace_root, node_modules, templated_args)

ATTRIBUTES

nodejs_binary(
    name = "my_binary",
    ...
    entry_point = ":file.js",
)

ts_library(
    name = "main",
    srcs = ["main.ts"],
)

nodejs_binary(
    name = "bin",
    data = [":main"]
    entry_point = ":main.ts",
)

filegroup(
    name = "entry_file",
    srcs = ["main.js"],
)

nodejs_binary(
    name = "my_binary",
    entry_point = ":entry_file",
)

nodejs_binary(
    name = "history-server",
    entry_point = "@npm//:node_modules/history-server/modules/cli.js",
    data = ["@npm//history-server"],
)

nodejs_binary(
    name = "my_binary",
    ...
    node_modules = "//:node_modules",
)

nodejs_binary(
    name = "my_binary",
    ...
    data = [
        "@npm//foo",
        "@npm//bar",
        ...
    ],
)

jasmine_node_test(
    name = "my_test",
    ...
    deps = [
        "@npm//jasmine",
        "@npm//foo",
        "@npm//bar",
        ...
    ],
)

nodejs_test(
    name = "my_test",
    data = [":bootstrap.js"],
    templated_args = ["--node_options=--require=$$(rlocation $(rootpath :bootstrap.js))"],
)

nodejs_test(
    name = "my_test",
    data = [":some_file"],
    entry_point = ":my_test.js",
    templated_args = ["$(rootpath :some_file)"],
)

const runfiles = require(process.env['BAZEL_NODE_RUNFILES_HELPER']);
const args = process.argv.slice(2);
const some_file = runfiles.resolveWorkspaceRelative(args[0]);

npm_install

Runs npm install during workspace setup.

This rule will set the environment variable BAZEL_NPM_INSTALL to ‘1’ (unless it set to another value in the environment attribute). Scripts may use to this to check if yarn is being run by the npm_install repository rule.

npm_install(name, args, data, environment, included_files, manual_build_file_contents, package_json,
            package_lock_json, quiet, strict_visibility, symlink_node_modules, timeout)

ATTRIBUTES

pkg_npm

The pkg_npm rule creates a directory containing a publishable npm artifact.

Example:

load("@build_bazel_rules_nodejs//:index.bzl", "pkg_npm")

pkg_npm(
    name = "my_package",
    srcs = ["package.json"],
    deps = [":my_typescript_lib"],
    substitutions = {"//internal/": "//"},
)

You can use a pair of // BEGIN-INTERNAL ... // END-INTERNAL comments to mark regions of files that should be elided during publishing. For example:

function doThing() {
    // BEGIN-INTERNAL
    // This is a secret internal-only comment
    doInternalOnlyThing();
    // END-INTERNAL
}

With the Bazel stamping feature, pkg_npm will replace any placeholder version in your package with the actual version control tag. See the stamping documentation

Usage:

pkg_npm yields three labels. Build the package directory using the default label:

$ bazel build :my_package
Target //:my_package up-to-date:
  bazel-out/fastbuild/bin/my_package
$ ls -R bazel-out/fastbuild/bin/my_package

Dry-run of publishing to npm, calling npm pack (it builds the package first if needed):

$ bazel run :my_package.pack
INFO: Running command line: bazel-out/fastbuild/bin/my_package.pack
my-package-name-1.2.3.tgz
$ tar -tzf my-package-name-1.2.3.tgz

Actually publish the package with npm publish (also builds first):

# Check login credentials
$ bazel run @nodejs//:npm_node_repositories who
# Publishes the package
$ bazel run :my_package.publish

You can pass arguments to npm by escaping them from Bazel using a double-hyphen, for example:

bazel run my_package.publish -- --tag=next

pkg_npm(name, deps, nested_packages, node_context_data, package_name, replace_with_version, srcs,
        substitutions, vendor_external)

ATTRIBUTES

pkg_web

Assembles a web application from source files.

pkg_web(name, additional_root_paths, node_context_data, srcs, substitutions)

ATTRIBUTES

yarn_install

Runs yarn install during workspace setup.

This rule will set the environment variable BAZEL_YARN_INSTALL to ‘1’ (unless it set to another value in the environment attribute). Scripts may use to this to check if yarn is being run by the yarn_install repository rule.

yarn_install(name, args, data, environment, included_files, manual_build_file_contents,
             package_json, quiet, strict_visibility, symlink_node_modules, timeout,
             use_global_yarn_cache, yarn_lock)

ATTRIBUTES

check_bazel_version

Verify the users Bazel version is at least the given one.

This can be used in rule implementations that depend on changes in Bazel, to warn users about a mismatch between the rule and their installed Bazel version.

This should not be used in users WORKSPACE files. To locally pin your Bazel version, just create the .bazelversion file in your workspace.

check_bazel_version(minimum_bazel_version, message)

PARAMETERS

copy_to_bin

Copies a source file to bazel-bin at the same workspace-relative path.

e.g. /foo/bar/a.txt -> /foo/bar/a.txt</code>

This is useful to populate the output folder with all files needed at runtime, even those which aren’t outputs of a Bazel rule.

This way you can run a binary in the output folder (execroot or runfiles_root) without that program needing to rely on a runfiles helper library or be aware that files are divided between the source tree and the output tree.

copy_to_bin(name, srcs, kwargs)

PARAMETERS

generated_file_test

Tests that a file generated by Bazel has identical content to a file in the workspace.

This is useful for testing, where a “snapshot” or “golden” file is checked in, so that you can code review changes to the generated output.

generated_file_test(name, generated, src, substring_search, src_dbg, kwargs)

PARAMETERS

js_library

Groups JavaScript code so that it can be depended on like an npm package.

Behavior

This rule doesn’t perform any build steps (“actions”) so it is similar to a filegroup. However it produces several Bazel “Providers” for interop with other rules.

Compare this to pkg_npm which just produces a directory output, and therefore can’t expose individual files to downstream targets and causes a cascading re-build of all transitive dependencies when any file changes

These providers are:

• DeclarationInfo so this target can be a dependency of a TypeScript rule
• NpmPackageInfo so this target can interop with rules that expect third-party npm packages
• LinkablePackageInfo for use with our “linker” that makes this package importable (similar to npm link)
• JsModuleInfo so rules like bundlers can collect the transitive set of .js files

js_library also copies any source files into the bazel-out folder. This is the same behavior as the copy_to_bin rule. By copying the complete package to the output tree, we ensure that the linker (our npm link equivalent) will make your source files available in the node_modules tree where resolvers expect them. It also means you can have relative imports between the files rather than being forced to use Bazel’s “Runfiles” semantics where any program might need a helper library to resolve files between the logical union of the source tree and the output tree.

Usage

js_library is intended to be used internally within Bazel, such as between two libraries in your monorepo.

Compare this to pkg_npm which is intended to publish your code for external usage outside of Bazel, like by publishing to npm or artifactory.

The typical example usage of js_library is to expose some sources with a package name:

ts_project(
    name = "compile_ts",
    srcs = glob(["*.ts"]),
)

js_library(
    name = "my_pkg",
    # Code that depends on this target can import from "@myco/mypkg"
    package_name = "@myco/mypkg",
    # Consumers might need fields like "main" or "typings"
    srcs = ["package.json"],
    # The .js and .d.ts outputs from above will be part of the package
    deps = [":compile_ts"],
)

To help work with “named AMD” modules as required by ts_devserver and other Google-style “concatjs” rules, js_library has some undocumented advanced features you can find in the source code or in our examples. These should not be considered a public API and aren’t subject to our usual support and semver guarantees.

js_library(name, srcs, package_name, deps, kwargs)

PARAMETERS

npm_package_bin

Run an arbitrary npm package binary (e.g. a program under node_modules/.bin/*) under Bazel.

It must produce outputs. If you just want to run a program with bazel run, use the nodejs_binary rule.

This is like a genrule() except that it runs our launcher script that first links the node_modules tree before running the program.

Bazel always runs actions with a working directory set to your workspace root. If your tool needs to run in a different directory, you can write a process.chdir helper script and invoke it before the action with a --require argument, like args = ["--node_options=--require=./$(execpath chdir.js)"] See rules_nodejs/internal/node/test/chdir for an example.

This is a great candidate to wrap with a macro, as documented: https://docs.bazel.build/versions/master/skylark/macros.html#full-example

npm_package_bin(tool, package, package_bin, data, outs, args, output_dir, link_workspace_root,
                kwargs)

PARAMETERS

params_file

Generates a UTF-8 encoded params file from a list of arguments.

Handles variable substitutions for args.

params_file(name, out, args, data, newline, kwargs)

PARAMETERS

DeclarationInfo

DeclarationInfo(declarations, transitive_declarations, type_blacklisted_declarations)

The DeclarationInfo provider allows JS rules to communicate typing information. TypeScript’s .d.ts files are used as the interop format for describing types. package.json files are included as well, as TypeScript needs to read the “typings” property.

Do not create DeclarationInfo instances directly, instead use the declaration_info factory function.

Note: historically this was a subset of the string-typed “typescript” provider.

FIELDS

JSEcmaScriptModuleInfo

JSEcmaScriptModuleInfo(direct_sources, sources)

JavaScript files (and sourcemaps) that are intended to be consumed by downstream tooling.

They should use modern syntax and ESModules. These files should typically be named “foo.mjs”

Historical note: this was the typescript.es6_sources output

FIELDS

JSModuleInfo

JSModuleInfo(direct_sources, sources)

JavaScript files and sourcemaps.

FIELDS

JSNamedModuleInfo

JSNamedModuleInfo(direct_sources, sources)

JavaScript files whose module name is self-contained.

For example named AMD/UMD or goog.module format. These files can be efficiently served with the concatjs bundler. These outputs should be named “foo.umd.js” (note that renaming it from “foo.js” doesn’t affect the module id)

Historical note: this was the typescript.es5_sources output.

FIELDS

LinkablePackageInfo

LinkablePackageInfo(files, package_name, path, _tslibrary)

The LinkablePackageInfo provider provides information to the linker for linking pkg_npm built packages

FIELDS

NodeContextInfo

NodeContextInfo(stamp)

Provides data about the build context, like config_setting’s

FIELDS

NodeRuntimeDepsInfo

NodeRuntimeDepsInfo(deps, pkgs)

Stores runtime dependencies of a nodejs_binary or nodejs_test

These are files that need to be found by the node module resolver at runtime.

Historically these files were passed using the Runfiles mechanism. However runfiles has a big performance penalty of creating a symlink forest with FS API calls for every file in node_modules. It also causes there to be separate node_modules trees under each binary. This prevents user-contributed modules passed as deps[] to a particular action from being found by node module resolver, which expects everything in one tree.

In node, this resolution is done dynamically by assuming a node_modules tree will exist on disk, so we assume node actions/binary/test executions will do the same.

FIELDS

NpmPackageInfo

NpmPackageInfo(direct_sources, sources, workspace)

Provides information about npm dependencies

FIELDS

declaration_info

Constructs a DeclarationInfo including all transitive files needed to type-check from DeclarationInfo providers in a list of deps.

declaration_info(declarations, deps)

PARAMETERS

js_ecma_script_module_info

Constructs a JSEcmaScriptModuleInfo including all transitive sources from JSEcmaScriptModuleInfo providers in a list of deps.

Returns a single JSEcmaScriptModuleInfo.

js_ecma_script_module_info(sources, deps)

PARAMETERS

js_module_info

Constructs a JSModuleInfo including all transitive sources from JSModuleInfo providers in a list of deps.

Returns a single JSModuleInfo.

js_module_info(sources, deps)

PARAMETERS

js_named_module_info

Constructs a JSNamedModuleInfo including all transitive sources from JSNamedModuleInfo providers in a list of deps.

Returns a single JSNamedModuleInfo.

js_named_module_info(sources, deps)

PARAMETERS

run_node

Helper to replace ctx.actions.run

This calls node programs with a node_modules directory in place

run_node(ctx, inputs, arguments, executable, kwargs)

PARAMETERS

node_modules_aspect

node_modules_aspect(name)

ASPECT ATTRIBUTES

ATTRIBUTES