Skip to content

Migrating to 5.0

Jump to bottom
Alex Eagle edited this page Nov 7, 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.

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",
    ...
)

exports_directories_only

This is now enabled by default, as it is a major performance improvement for all node actions that use npm packages.

If it causes problems, we recommend turning it off by setting exports_directories_only to False on your npm_install/yarn_install. Leave yourself a TODO here. Then after the rest of the 5.0 upgrade has landed, you can return to getting this working.

Some rules only work by referencing labels nested inside npm packages and therefore require turning off exports_directories_only

Related, the default for package_path of npm_install/yarn_install is now the folder containing the package.json file. If yours is nested but you expect to resolve from it in parent directories, you can return to the previous default with package_path = "/". See https://github.com/bazelbuild/rules_nodejs/issues/3291

Yarn custom repositories

The yarn_repositories attribute was renamed to yarn_releases, as we now have a yarn_repositories repository rule.

Doc: https://bazelbuild.github.io/rules_nodejs/Core.html#yarn_repositories-yarn_releases

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 update rules_docker to https://github.com/bazelbuild/rules_docker/releases/tag/v0.23.0 or greater (to get this commit) 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.

You may also need to add more rootDirs entries to tsconfig since there is another output directory, see https://github.com/bazelbuild/rules_docker/pull/1963#issuecomment-1022315924

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",
)

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.
  • To run node from the command line, use @nodejs_host//:node as documented here: https://bazelbuild.github.io/rules_nodejs/repositories.html#nodejs_host
  • If use used @nodejs//:yarn, this is now in a dedicated external yarn repository: @yarn//:yarn by default, or whatever name you give to a yarn_repositories rule.

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