npm.md

Npm

Better_rules_javascript can use npm packages.

• Guide
  • Strategy
  • Yarn
  • IDE
  • Limitations
• //npm:rules.bzl
  • npm_publish
  • yarn_audit_test
  • yarn_resolve
  • npm_package
• //npm:workspace.bzl
  • npm
  • npm_import_external_rule
  • npm_import_rule
  • package_repo_name

Guide

Strategy

A package manager resolves the dependency graph. The information is converted to Bazel repositories. This approach integrates well into the Bazel ecosystem and avoid excessive downloads. Compare with rules_jvm_external.

better_rules_javascript uses Yarn 2.

Yarn

Install

Create a package.json.

package.json

{
  "dependencies": {
    "@org/package": "^1.0.0"
  }
}

Create a yarn_resolve target.

BUILD.bazel

yarn_resolve(
    name = "resolve_npm",
)

Resolve packages and generate npm_data.bzl

bazel run :resolve_npm

Load the repositories.

WORKSPACE.bazel

load("@better_rules_javascript//npm:workspace.bzl", "npm")
load(":npm_data.bzl", npm_packages = "PACKAGES", npm_roots = "ROOTS")
npm("npm", npm_packages, npm_roots)

Plugins

Several types of files can be distributed in NPM packages: JavaScript, TypeScript, CSS, etc.

To support these, the npm repositories can be customized via "plugins."

The defaults are:

load("@better_rules_javascript//commonjs:workspace.bzl", "cjs_npm_plugin")
load("@better_rules_javascript//js:workspace.bzl", "js_npm_plugin")

npm(
  name = "npm",
  packages = npm_packages,
  roots = npm_roots,
  plugins = [
    cjs_npm_plugin(),
    js_npm_plugin(),
  ]
)

If you use TypeScript, replace js_npm_plugin() with ts_npm_plugin().

Usage

JS libraries are available as @npm//<package_name>:lib.

For example,

BUILD.bazel

js_library(
    name = "example",
    deps = ["@npm//@org/package:lib"],
)

IDE

To make these accessible to the IDE in node_modules, see Node.js docs.

Limitations

Post-install scripts, including native dependencies (node-gyp), are not supported.

To support those, filter the package from PACKAGES, and instead use Bazel rules to replicate the build process.

//npm:rules.bzl

npm_publish

npm_publish(name, src)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
src	-	Label	required

yarn_audit_test

yarn_audit_test(name, data, path)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
data	-	List of labels	optional	[]
path	Package relative path	String	optional	""

yarn_resolve

yarn_resolve(name, output, path, refresh)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
output	Package-relative output path	String	optional	"npm_data.bzl"
path	Package-relative path to package.json and yarn.lock directory	String	optional	""
refresh	Whether to refresh	Boolean	optional	True

npm_package

npm_package(name, srcs, visibility, kwargs)

PARAMETERS

Name	Description	Default Value
name	-	none
srcs	-	none
visibility	-	None
kwargs	-	none

//npm:workspace.bzl

npm

npm(name, packages, roots, plugins, auth_patterns, netrc)

Npm repositories.

PARAMETERS

Name	Description	Default Value
name	Namespace	none
packages	Packages	none
roots	Roots	none
plugins	Plugins	[struct(alias_build = <function alias_build>, package_build = <function package_build>), struct(alias_build = <function alias_build>, package_build = <function package_build>)]
auth_patterns	Auth patterns	None
netrc	Netrc	None

npm_import_external_rule

npm_import_external_rule(plugins)

Create a npm_import_external rule.

PARAMETERS

Name	Description	Default Value
plugins	-	none

npm_import_rule

npm_import_rule(plugins)

Create an npm import rule.

PARAMETERS

Name	Description	Default Value
plugins	-	none

package_repo_name

package_repo_name(prefix, name)

Repository name for npm package.

Replaces characters not permitted in Bazel repository names.

PARAMETERS

Name	Description	Default Value
prefix	Namespace	none
name	ID	none