Skip to content

2.0.0
Compare
Choose a tag to compare
@gregmagolan gregmagolan released this 20 Jul 21:32
· 35 commits to 1.x since this release
2.0.0
e09c2a5

It's been about 7 months since we released 1.0 and we'd like to be on a twice-yearly major release cadence.

We've been working hard to make cleanups to our APIs, so following our semantic versioning policy it is time for these breaking changes to roll out to you. We have done our best to make it convenient for you to upgrade.

To upgrade, edit your WORKSPACE:

http_archive(
    name = "build_bazel_rules_nodejs",
    sha256 = "5bf77cc2d13ddf9124f4c1453dd96063774d755d4fc75d922471540d1c9a8ea8",
    urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/2.0.0/rules_nodejs-2.0.0.tar.gz"],
)

and update all your @bazel-scoped npm packages.
Where possible, we have added notes about additional code changes you need to make in the 2.0 upgrade wiki. These should make it quicker for you to get upgraded.

Branching

We have decided to stop using a branch named master. Our new branching strategy is:

  • 1.x is code from releases prior to 2.0
  • stable will have 2.x releases
  • When we are ready to make breaking changes for 3.0, we will put them on feature branches and have a new branch for integrating them.

We are sorry that master was our default for so long. This caused a bunch of confusion because examples were updated with 2.0 breaking changes, but those releases were not tagged as "latest" yet.

We look forward to support from GitHub to redirect all links with master to the new default branch, at which time we'll remove the branch and update Pull Requests that target it.

New features

Cypress integration testing

There is a new custom cypress_web_test rule in the @bazel/cypress package.
See the example added in https://github.com/bazelbuild/rules_nodejs/tree/2.0.0/examples/cypress

Thanks to @mrmeku for this awesome contribution!

React and Vue examples

React users should start from https://github.com/bazelbuild/rules_nodejs/blob/2.0.0/docs/examples.md#react as there are multiple ways you can build your React app under Bazel. The rules_nodejs team expects to invest more here soon.

A very basic Vue example is available as well. Thanks to @Smokrow for getting this started.

generated_file_test rule

Typically under Bazel you should leave the outputs in the bazel-out folder and reference them there.

However there are some cases where you really need to check generated files into your repo, for example:

  • want code reviewer to see the change in the generated file, like a golden file for tests that assert on the generated content

  • strange-shaped bootstrap problems where you can't run Bazel before referencing the output

See the docs for generated_file_test

Relatedly, @longlho added an example for using Jest with snapshot files

stdout/stderr/exit code capture

When running a tool to produce outputs, you typically use the npm_package_bin rule, or an auto-generated rule provided from an npm package in the index.bzl file.

You can now use stdout = "some_label" or stderr = "other_label" and the stdout and stderr of the program will be redirected into the file you specify. You can then depend on these in another downstream rule. Similarly you can capture the exit code with exit_code_out = "some_label", in this case the action will return zero (success) and you can depend on the exit code from another target.

This is useful for interacting with a tool that only produces output on stdout rather than provide a --outfile-style flag to let you control the path.

It can also be useful to redirect spammy writes so they don't clog the Bazel log, or transform the outputs with another tool.

Thanks to @mattem for contributing this!

TypeScript (ts_project)

ts_project now has additional attributes to match TypeScript. Use out_dir to specify where JS is written (allows you to write multiple .js outputs for each .ts input, for example different module formats). Use declaration_dir to specify output .d.ts locations and root_dir to specify a subdirectory of the source package.

There is a new output_group for "types" so you can depend on just the .d.ts outputs, see https://github.com/bazelbuild/rules_nodejs/blob/2.0.0/packages/typescript/test/ts_project/output_group/BUILD.bazel

It also correctly handles .json inputs, adding them to the appropriate output sets along with emitted .js files.
See https://github.com/bazelbuild/rules_nodejs/tree/2.0.0/packages/typescript/test/ts_project/json

Thanks to @longlho and @mistic for contributing these!

Breaking changes

Loading custom rules from npm packages

Generated rules have always been loaded from the package directly. For example you load Babel like this:

load("@npm//@babel/cli:index.bzl", "babel")

However custom rules like ts_library have been loaded from a non-standard repository like @npm_bazel_typescript. Not only was this inconsistent, it caused problems:

  • These non-standard repositories are created by a install_bazel_dependencies call in WORKSPACE, which happens for all builds whether they depend on JS outputs or not. So in a monorepo, backend engineers are waiting for npm installs.
  • If you didn't name your dependency repository @npm, you had to override attributes like the compiler on ts_library. This made it annoying to have more than one yarn_install/npm_install.
  • It was very difficult to use rules_nodejs from source rather than the distribution.

Instead here is the new behavior:

  • Load all rules from a dependency repository. For example if you npm_install(name="my_deps") in your WORKSPACE then you should always load from it, load("@my_deps//@bazel/typescript:index.bzl)" - see the 2.0 wiki for a command that automates this
  • Use of install_bazel_dependencies throws a warning since it's no longer needed.
  • You can use rules_nodejs from source. You just need to install our devDependencies from package.bzl and use labels like @build_bazel_rules_nodejs//packages/pkg. See the example

Built-ins

  • rules_nodejs now requires Bazel 2.1 or greater. This adds support for .bazelignore in external repositories. As a result, the hide_build_files attribute was removed from pkg_npm, and always_hide_bazel_files was removed from yarn_install and npm_install. These are no longer needed since 1.3.0. The @bazel/hide-build-files package is now deprecated and no longer published.

  • The install_source_map_support attribute is removed from nodejs_binary. source-map-support is vendored in at /third_party/github.com/source-map-support so it can always be installed. Simply remove any usage of that attribute.

  • jasmine is now a peerDependency of @bazel/jasmine. This lets you pick your own Jasmine version. Fix it with yarn add -D jasmine jasmine-core

  • jasmine_node_test no longer has the coverage attribute. We plan to publish updated docs for running bazel coverage on any arbitrary node program; follow #1885

Rollup

The peerDependency range on Rollup is now >=2.3.0 as Rollup introduced an API to parse the command line which we want to depend on.

Importing from the workspace root

We used to assume that your workspace name (defined with workspace(name="foo") in /WORKSPACE[.bazel]) matches the name of a package you publish to npm. Therefore that workspace name was always importable, like import from 'foo/path/to/thing'

This is now opt-in. Simply put an pkg_npm rule in your root /BUILD[.bazel] file with package_name = "foo" to declare that the root directory is an npm package named "foo".

Any nodejs_binary/nodejs_test processes with the linker enabled (--nobazel_patch_module_resolver is set) that were relying on standard node_module resolution to resolve manfest file paths such as my_workspace/path/to/output/file.js must now use the runfiles helper such as.

Previously:

const absPath = require.resolve('my_workspace/path/to/output/file.js');

With runfiles helper:

const runfiles = require(process.env['BAZEL_NODE_RUNFILES_HELPER']);
const absPath = runfiles.resolve('my_workspace/path/to/output/file.js');

Linking

Similar to the npm link workflow, we run a program
before node that creates symlinks to packages you depend on.
This is now enabled for all programs. If this breaks you, you can escape from this feature for now with a flag on nodejs_binary, nodejs_test, or npm_package_bin:

templated_args = ["--nobazel_run_linker"]

We also run a --require script to patch the node environment to understand Bazel's symlink layout. If this breaks you, you can use templated_args = ["--nobazel_node_patches"] to escape from that feature.

Angular

For most applications, we no longer recommend depending on the @angular/bazel package. The only rule needed from it was ng_module which you can replace with the faster equivalent ts_library(use_angular_plugin=True)

However if you publish Angular components to npm you may still want to use the ng_package rule. We have updated our examples to show this.

If you use Angular's old "View Engine" compiler/runtime, you'll have to stay on version 9.0.5 to keep Bazel compatibility.

More updates for Angular + Bazel users are described in this blog post

For Rules Authors

This section is only relevant if you maintain your own custom Bazel rule implementation (not macros)

  • If you use the generated nodejs_binary or nodejs_test rules in the npm
    workspace, for example @npm//typescript/bin:tsc, your custom rule must now link the
    node_modules directory into that process. To do this, you may need to change from ctx.actions.run to our run_node helper, as this sets up the action to run the linker program first.
    See 007a8f6#diff-e4cc9aaa33fff1541c61f173d77fe8d0

  • We removed the provide_declarations() factory function for DeclarationInfo. Use declaration_info() instead.

  • Added JSModuleInfo provider as the common provider for passing & consuming javascript sources and related files such as .js.map, .json, etc.

For 1.0 we added JSNamedModuleInfo and JSEcmaScriptModuleInfo which were provided by ts_library and consumed by rules that needed to differentiate between the two default flavors of ts_library outputs (named-UMD & esm). We left out JSModuleInfo as its use case was unclear at the time.

For 2.0 we're adding JSModuleInfo as generic javascript provided for the rules_nodejs ecosystem. It is not currently opinionated about the module format of the sources or the language level. Consumers of JSModuleInfo should be aware of what module format & language level is being produced if necessary.

The following rules provide JSModuleInfo:

  • ts_library (devmode named-UMD .js output flavor)
  • ts_proto_library (devmode named-UMD .js output flavor)
  • node_module_library (this is a behind the scenes rule used by yarn_install & npm_install)
  • js_library (.js, .js.map & . json files)
  • rollup_bundle
  • terser_minfied
  • ts_project

The following rules consume JSModuleInfo:

  • nodejs_binary & nodejs_test (along with derivate macros such as jasmine_node_test); these rules no longer consume JSNamedModuleInfo
  • npm_package_bin
  • pkg_npm; no longer consumes JSNamedModuleInfo
  • karma_web_test (for config file instead of JSNamedModuleInfo; JSNamedModuleInfo still used for test files)
  • protractor_web_test (for config & on_prepare files instead of JSModuleInfo; JSNamedModuleInfo still used for test files)
  • rollup_bundle (if JSEcmaScriptModuleInfo not provided)
  • terser_minified

Changelog

See https://github.com/bazelbuild/rules_nodejs/blob/2.0.0/CHANGELOG.md for pointers to commits and pull requests in this release.

Assets 3
Loading