Skip to content

Migrating to 5.0

Jump to bottom
Alex Eagle edited this page Jan 25, 2022 · 21 revisions

rules_nodejs dependencies

Prior to 5.0, the build_bazel_rules_nodejs workspace had zero starlark dependencies, because transitive handling of them in WORKSPACE was so difficult for users to get right. However now that Bazel 5.0 has bzlmod to manage these transitive dependencies, we feel it's the right time to add dependencies. (Documentation for using rules_nodejs with bzlmod will be added soon)

You need to update your WORKSPACE file to install the dependencies. Note that WORKSPACE ordering is critical, so if you need to override versions of rules_nodejs dependencies, you must do it before this code.

load("@build_bazel_rules_nodejs//:repositories.bzl", "build_bazel_rules_nodejs_dependencies")

build_bazel_rules_nodejs_dependencies()

New toolchains (optional)

You can optionally remove usage of node_repositories, which is now just a "syntax sugar" macro for the underlying rules. In its place, you can register toolchains:

load("@rules_nodejs//nodejs:repositories.bzl", "nodejs_register_toolchains")

nodejs_register_toolchains(
    # You can choose whatever name you like for the node toolchains, and can register more than one version.
    name = "nodejs",
)

npm_install and yarn_install are repository rules, which means they can't use Bazel's toolchain resolution to see what you registered. By default, they'll look for "nodejs", and so if you use name = "nodejs" like the example above, then no changes are needed.

If you choose a different name, you have to tell npm_install and yarn_install what it is, e.g.

npm_install(
    node_repository = "my_node",
    ...
)

Users of vendored_yarn and vendored_node

We've simplified these. You can now just pass a yarn attribute to yarn_install pointing to whatever yarn binary you'd like to use. For vendoring node (or building it from source) you can register the toolchain yourself rather than use our helper.

See the updated documentation and the example

Users of "user managed dependencies"

This was a very early method for manually running a bazel run command to install your npm dependencies, by passing a package_json list to node_repositories. We removed this feature. Please tell us in https://github.com/bazelbuild/rules_nodejs/issues/3176 if you still rely on it.

nodejs_image from rules_docker

Our toolchains refactor broke the nodejs_image rule, so you need to get new release of rules_docker after commit https://github.com/bazelbuild/rules_docker/commit/8a4f73fb29a64ba813087220b200f49a1ca10faa and add attribute to nodejs_image pointing to the node toolchain you registered, e.g. node_repository_name = "my_node_linux_amd64". Also add attribute include_node_repo_args = False.

Updated defaults

The default nodejs version is now 16.12.0. To go back to the previous default, put this in your WORKSPACE:

nodejs_register_toolchains(
    node_version = "14.17.5",
)

exports_directories_only

Some rules only work by referencing labels nested inside npm packages, so you must set exports_directories_only to False on your npm_install/yarn_install:

esbuild

Users must now explicitly set the value of the npm_repository attribute on the esbuild_repositories rule. Previously this defaulted to npm, but is now mandatory.

If your npm workspace was named npm, then the following will return you back to the default:

esbuild_repositories(
    npm_repository = "npm",
)

Moved

Dropped providers

todo Greg https://github.com/bazelbuild/rules_nodejs/commit/7f688a95c9002a9e5148f218dfa9f1ea6464f50a

Toolchain definition

The toolchain name is now controlled by the WORKSPACE file. The hard-coded @nodejs repo is no longer required, you may name it whatever you like.

In the examples below, we assume you used name "my_node" in your call to nodejs_register_toolchains.

Breaking changes:

  • If you explicitly used a label like @nodejs//:node, you can find a platform-specific variant at @my_node_linux_amd64//:node.
  • Custom rules should now use @rules_nodejs//nodejs:toolchain_type to request a nodejs toolchain.
  • Genrules should now use @my_node_toolchains//:resolved_toolchain.

See examples/toolchain for example of using the toolchain.

If you used our platform definitions, they have changed from e.g. --platforms=@build_bazel_rules_nodejs//toolchains/node:darwin_amd64 to --platforms=@rules_nodejs//nodejs:darwin_amd64"

However, the new toolchain declares compatibility with the execution platform (node running as a tool to produce outputs), not with the target platform. So there's no need to pass a --platforms flag at this time, since we still don't cross-compile anything to the target platform.

Angular

@bazel/angular is a minimal plugin for the Angular CLI builders system (aka. architect) teaching the ng command how to spawn bazel for build and test steps.

It has been moved from this repo and can now be found in https://github.com/just-jeb/angular-builders Thanks to @just-jeb for taking on maintenance of this code!

Labs

The @bazel/labs package has been removed, and is no longer published to npm. This repo doesn't contain support for protocol buffers or gRPC.

ts_library

The ts_library rule is now in the @bazel/concatjs package. The @build_bazel_rules_typescript workspace no longer exists, the code was moved into the concatjs package.

nodejs_binary attrs

repository_args todo https://github.com/bazelbuild/rules_nodejs/commit/90c7fe07e086c8ba63e0e75cb65a181b90e0960e node todo https://github.com/bazelbuild/rules_nodejs/commit/cb8374633a93724c4df4be19ebfa09a0c81339c2

Reduced maintenance scope

The concatjs package is now in "maintenance mode". Since no one from Google participates in rules_nodejs, it has been impossible for us to keep this code up-to-date with what Google develops internally, and it is a complex package that OSS maintainers don't have time for. In the future we will probably deprecate this package unless new maintainers want to take it over.

Clone this wiki locally