Skip to main content
Version: 1.34.x

npm_import

Repository rule to fetch npm packages.

Load this with,

load("@aspect_rules_js//npm:repositories.bzl", "npm_import")

This uses Bazel's downloader to fetch the packages. You can use this to redirect all fetches through a store like Artifactory.

See <https://blog.aspect.dev/configuring-bazels-downloader> for more info about how it works and how to configure it.

See npm_translate_lock for the primary user-facing API to fetch npm packages for a given lockfile.

Macros and Functions

npm_import

Import a single npm package into Bazel.

Normally you'd want to use npm_translate_lock to import all your packages at once. It generates npm_import rules. You can create these manually if you want to have exact control.

Bazel will only fetch the given package from an external registry if the package is required for the user-requested targets to be build/tested.

This is a repository rule, which should be called from your WORKSPACE file or some .bzl file loaded from it. For example, with this code in WORKSPACE:

npm_import(
name = "npm__at_types_node__15.12.2",
package = "@types/node",
version = "15.12.2",
integrity = "sha512-zjQ69G564OCIWIOHSXyQEEDpdpGl+G348RAKY0XXy9Z5kU9Vzv1GMNnkar/ZJ8dzXB3COzD9Mo9NtRZ4xfgUww==",
)

This is similar to Bazel rules in other ecosystems named "_import" like apple_bundle_import, scala_import, java_import, and py_import. go_repository is also a model for this rule.

The name of this repository should contain the version number, so that multiple versions of the same package don't collide. (Note that the npm ecosystem always supports multiple versions of a library depending on where it is required, unlike other languages like Go or Python.)

To consume the downloaded package in rules, it must be "linked" into the link package in the package's BUILD.bazel file:

load("@npm__at_types_node__15.12.2__links//:defs.bzl", npm_link_types_node = "npm_link_imported_package")

npm_link_types_node(name = "node_modules")

This links @types/node into the node_modules of this package with the target name :node_modules/@types/node.

A :node_modules/@types/node/dir filegroup target is also created that provides the the directory artifact of the npm package. This target can be used to create entry points for binary target or to access files within the npm package.

NB: You can choose any target name for the link target but we recommend using the node_modules/@scope/name and node_modules/name convention for readability.

When using npm_translate_lock, you can link all the npm dependencies in the lock file for a package:

load("@npm//:defs.bzl", "npm_link_all_packages")

npm_link_all_packages(name = "node_modules")

This creates :node_modules/name and :node_modules/@scope/name targets for all direct npm dependencies in the package. It also creates :node_modules/name/dir and :node_modules/@scope/name/dir filegroup targets that provide the the directory artifacts of their npm packages. These target can be used to create entry points for binary target or to access files within the npm package.

If you have a mix of npm_link_all_packages and npm_link_imported_package functions to call you can pass the npm_link_imported_package link functions to the imported_links attribute of npm_link_all_packages to link them all in one call. For example,

load("@npm//:defs.bzl", "npm_link_all_packages")
load("@npm__at_types_node__15.12.2__links//:defs.bzl", npm_link_types_node = "npm_link_imported_package")

npm_link_all_packages(
name = "node_modules",
imported_links = [
npm_link_types_node,
]
)

This has the added benefit of adding the imported_links to the convienence :node_modules target which includes all direct dependencies in that package.

NB: You can pass an name to npm_link_all_packages and this will change the targets generated to "{name}/@scope/name" and "{name}/name". We recommend using "node_modules" as the convention for readability.

To change the proxy URL we use to fetch, configure the Bazel downloader:

  1. Make a file containing a rewrite rule like

    rewrite (registry.nodejs.org)/(.*) artifactory.build.internal.net/artifactory/$1/$2

  2. To understand the rewrites, see UrlRewriterConfig in Bazel sources.

  3. Point bazel to the config with a line in .bazelrc like common --experimental_downloader_config=.bazel_downloader_config

Read more about the downloader config: https://blog.aspect.dev/configuring-bazels-downloader

Example usage (generated):

load("@aspect_rules_js//npm:defs.bzl", "npm_import")

npm_import(
# Name for this repository rule
name = "",
# Name of the npm package, such as `acorn` or `@types/node`
package = None,
# Version of the npm package, such as `8.4.0`
version = None,
)

name

Required.

Name for this repository rule

package

Required.

Name of the npm package, such as acorn or @types/node

version

Required.

Version of the npm package, such as 8.4.0

deps

Optional. Default: {}

A dict other npm packages this one depends on where the key is the package name and value is the version

extra_build_content

Optional. Default: ""

Additional content to append on the generated BUILD file at the root of the created repository, either as a string or a list of lines similar to https://github.com/bazelbuild/bazel-skylib/blob/main/docs/write_file_doc.md.

transitive_closure

Optional. Default: {}

A dict all npm packages this one depends on directly or transitively where the key is the package name and value is a list of version(s) depended on in the closure.

root_package

Optional. Default: ""

The root package where the node_modules virtual store is linked to. Typically this is the package that the pnpm-lock.yaml file is located when using npm_translate_lock.

Optional. Default: ""

The workspace name where links will be created for this package.

This is typically set in rule sets and libraries that are to be consumed as external repositories so links are created in the external repository and not the user workspace.

Can be left unspecified if the link workspace is the user workspace.

Optional. Default: {}

Dict of paths where links may be created at for this package to a list of link aliases to link as in each package. If aliases are an empty list this indicates to link as the package name.

Defaults to {} which indicates that links may be created in any package as specified by the direct attribute of the generated npm_link_package.

lifecycle_hooks

Optional. Default: []

List of lifecycle hook package.json scripts to run for this package if they exist.

lifecycle_hooks_execution_requirements

Optional. Default: ["no-sandbox"]

Execution requirements when running the lifecycle hooks.

For example:

lifecycle_hooks_execution_requirements: ["no-sandbox', "requires-network"]

This defaults to ["no-sandbox"] to limit the overhead of sandbox creation and copying the output TreeArtifact out of the sandbox.

lifecycle_hooks_env

Optional. Default: []

Environment variables set for the lifecycle hooks action for this npm package if there is one.

Environment variables are defined by providing an array of "key=value" entries.

For example:

lifecycle_hooks_env: ["PREBULT_BINARY=https://downloadurl"],

integrity

Optional. Default: ""

Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded.

This is the same as appears in the pnpm-lock.yaml, yarn.lock or package-lock.json file.

It is a security risk to omit the checksum as remote files can change.

At best omitting this field will make your build non-hermetic.

It is optional to make development easier but should be set before shipping.

url

Optional. Default: ""

Optional url for this package. If unset, a default npm registry url is generated from the package name and version.

May start with git+ssh:// or git+https:// to indicate a git repository. For example,

git+ssh://git@github.com/org/repo.git

If url is configured as a git repository, the commit attribute must be set to the desired commit.

commit

Optional. Default: ""

Specific commit to be checked out if url is a git repository.

package_visibility

Optional. Default: ["//visibility:public"]

Visibility of generated node_module link targets.

patch_args

Optional. Default: ["-p0"]

Arguments to pass to the patch tool.

-p1 will usually be needed for patches generated by git.

patches

Optional. Default: []

Patch files to apply onto the downloaded npm package.

custom_postinstall

Optional. Default: ""

Custom string postinstall script to run on the installed npm package. Runs after any existing lifecycle hooks if run_lifecycle_hooks is True.

npm_auth

Optional. Default: ""

Auth token to authenticate with npm. When using Bearer authentication.

npm_auth_basic

Optional. Default: ""

Auth token to authenticate with npm. When using Basic authentication.

This is typically the base64 encoded string "username:password".

npm_auth_username

Optional. Default: ""

Auth username to authenticate with npm. When using Basic authentication.

npm_auth_password

Optional. Default: ""

Auth password to authenticate with npm. When using Basic authentication.

bins

Optional. Default: {}

Dictionary of node_modules/.bin binary files to create mapped to their node entry points.

This is typically derived from the "bin" attribute in the package.json file of the npm package being linked.

For example:

bins = {
"foo": "./foo.js",
"bar": "./bar.js",
}

In the future, this field may be automatically populated by npm_translate_lock from information in the pnpm lock file. That feature is currently blocked on https://github.com/pnpm/pnpm/issues/5131.

dev

Optional. Default: False

Whether this npm package is a dev dependency

register_copy_directory_toolchains

Optional. Default: True

if True, @aspect_bazel_lib//lib:repositories.bzl register_copy_directory_toolchains() is called if the toolchain is not already registered

register_copy_to_directory_toolchains

Optional. Default: True

if True, @aspect_bazel_lib//lib:repositories.bzl register_copy_to_directory_toolchains() is called if the toolchain is not already registered

run_lifecycle_hooks

Optional. Default: None

If True, runs preinstall, install, postinstall and 'prepare' lifecycle hooks declared in this package.

Deprecated. Use lifecycle_hooks instead.

lifecycle_hooks_no_sandbox

Optional. Default: None

If True, adds "no-sandbox" to lifecycle_hooks_execution_requirements.

Deprecated. Add "no-sandbox" to lifecycle_hooks_execution_requirements instead.

kwargs

Optional.

Internal use only