Releases: bazel-contrib/rules_nodejs
2.0.1
Upgrade with
http_archive(
name = "build_bazel_rules_nodejs",
sha256 = "0f2de53628e848c1691e5729b515022f5a77369c76a09fbe55611e12731c90e3",
urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/2.0.1/rules_nodejs-2.0.1.tar.gz"],
)
and update @bazel
-scoped packages
Bug Fixes
2.0.0
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.0stable
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 inWORKSPACE
, 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 thecompiler
onts_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 yourWORKSPACE
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, thehide_build_files
attribute was removed frompkg_npm
, andalways_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 fromnodejs_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 withyarn add -D jasmine jasmine-core
-
jasmine_node_test
no longer has thecoverage
attribute. We plan to publish updated docs for runningbazel 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_bina...
2.0.0-rc.3
It's been about 6 months since we released 1.0.
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.
We will add extra notes about code changes you need to make in the 2.0 upgrade wiki.
To upgrade:
http_archive(
name = "build_bazel_rules_nodejs",
sha256 = "41b5d9796db19a022bc4a4ca7e9e9f72d92195643ccd875dff325c5e980ee470",
urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/2.0.0-rc.3/rules_nodejs-2.0.0-rc.3.tar.gz"],
)
and update all your @bazel-scoped npm packages.
Branching
We have decided to stop using a branch named master
. In the future our branching strategy is:
1.x
is code from releases prior to 2.0stable
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 packages were not published 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.
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 inWORKSPACE
, 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 thecompiler
onts_library
since the default values were cross-repository. This made it annoying to have more than one dependency repository. - 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 yourWORKSPACE
then you should always load from it,load("@my_deps//@bazel/typescript:index.bzl)"
- Use of
install_bazel_dependencies
throws a warning since it's no longer needed. - You can use rules_nodejs from source (TODO: doc link)
Built-ins
-
rules_nodejs now requires Bazel 2.1 or greater. This adds support for
.bazelignore
in external repositories. As a result, thehide_build_files
attribute was removed frompkg_npm
, andalways_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 fromnodejs_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 withyarn add -D jasmine jasmine-core
-
jasmine_node_test
no longer has thecoverage
attribute. We plan to publish updated docs for runningbazel 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. You can use templated_args = ["--nobazel_node_patches"]
to escape from that feature.
Angular
We no longer recommend depending on the deprecated @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)
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 fromctx.actions.run
to ourrun_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. Usedeclaration_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
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-rc.3/examples/cypress
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 (TODO:link) for generated_file_test
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.
TypeScript (ts_project)
ts_project has an outdir
attribute so you can write multiple .js outputs for each .ts input, for example different module formats.
There is a new output_gr...
2.0.0-rc.2
replaced with 2.0.0-rc.3
2.0.0-rc.1
replaced with 2.0.0-rc.2
2.0.0-rc.0
replaced with 2.0.0-rc.1
1.7.0
To upgrade:
http_archive(
name = "build_bazel_rules_nodejs",
sha256 = "84abf7ac4234a70924628baa9a73a5a5cbad944c4358cf9abdb4aab29c9a5b77",
urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/1.7.0/rules_nodejs-1.7.0.tar.gz"],
)
and update all your @bazel-scoped npm packages to the matching versions.
yarn: yarn upgrade --scope @bazel
npm: there is no built-in command but you can try npx update-by-scope @bazel
Features
- angular: introduce an Angular CLI builder (5ac842e)
Bug Fixes
1.6.1
To upgrade:
http_archive(
name = "build_bazel_rules_nodejs",
sha256 = "d14076339deb08e5460c221fae5c5e9605d2ef4848eee1f0c81c9ffdc1ab31c1",
urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/1.6.1/rules_nodejs-1.6.1.tar.gz"],
)
and update all your @bazel-scoped npm packages to the matching versions.
yarn: yarn upgrade --scope @bazel
npm: there is no built-in command but you can try npx update-by-scope @bazel
Bug Fixes
- builtin: fix linker issue when running test with "local" tag on osx & linux (#1835) (801935d)
- builtin: fix regression in 1.6.0 in linker linking root package when under runfiles (00e13e2), closes #1823 #1850
- typescript: allow for ts_library(use_angular_plugin) to be used with worker mode and no linker (#1839) (495f665)
Examples
1.6.0
📰 We plan to start merging breaking changes on master, so we expect this will be the last 1.x release (unless there are some bug fixes needed in 1.6.1 etc). We'll add likely 2.0 candidates to the milestone
To upgrade:
http_archive(
name = "build_bazel_rules_nodejs",
sha256 = "f9e7b9f42ae202cc2d2ce6d698ccb49a9f7f7ea572a78fd451696d03ef2ee116",
urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/1.6.0/rules_nodejs-1.6.0.tar.gz"],
)
and update all your @bazel-scoped npm packages to the matching versions.
yarn: yarn upgrade --scope @bazel
npm: there is no built-in command but you can try npx update-by-scope @bazel
Features
- builtin: export version to npm/yarn install (011278e)
- jasmine: check pkg version to rules_nodejs (22bebbc) - this makes it easier to avoid version skew, thanks @Toxicable !
- typescript: wire up use_angular_plugin attribute - this effectively deprecates the
ng_module
rule which is published from the Angular repo. see changes in commit: (520493d) - typescript: You can now generate tsconfig files for use with
ts_project
, see example
Bug Fixes
- builtin: always symlink node_modules at
execroot/my_wksp/node_modules
even when running in runfiles (#1805) (5c2f6c1) - builtin: don't allow symlinks to escape or enter bazel managed node_module folders (#1800) (4554ce7)
- builtin: fix for pkg_npm single directory artifact dep case (5a7c1a7)
- builtin: fix node patches lstat short-circuit logic (#1818) (b0627be)
- builtin: fix npm_version_check.js when running outside of bazel (#1802) (afabe89)
- builtin: look in the execroot for nodejs_binary source entry_points (#1816) (b84d65e), closes #1787 #1787
- builtin: preserve lone $ in templated_args for legacy support (#1772) (72c14d8)
- builtin: under runfiles linker should link node_modules folder at root of runfiles tree (13510ad)
- rollup: fix worker not picking up config file changes (a19eb2b), closes #1790 - Thanks @jbedard
- typescript: don't mix worker mode and linker (55c6c4a), closes #1803 #1803
- typescript: include extended tsconfigs in _TsConfigInfo (cd8520d), closes #1754
Examples
- examples: add support for server side rendering with universal (c09ca89) - Thanks @flolu
- examples: build and consume an Angular workspace library (#1633) (b459d6d) - this shows how to use Angular CLI toolchain to build a lib and an app that depends on it. Thanks @alan-agius4
Documentation
1.5.0
To upgrade:
http_archive(
name = "build_bazel_rules_nodejs",
sha256 = "d0c4bb8b902c1658f42eb5563809c70a06e46015d64057d25560b0eb4bdc9007",
urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/1.5.0/rules_nodejs-1.5.0.tar.gz"],
)
and update all your @bazel-scoped npm packages to the matching versions.
yarn: yarn upgrade --scope @bazel
npm: there is no built-in command but you can try npx update-by-scope @bazel
New stuff
- The
ts_project
rule is a simple wrapper around the TypeScript compiler,tsc
. This is an alternative tots_library
but not a replacement. Read more about the trade-offs at https://bazelbuild.github.io/rules_nodejs/TypeScript#alternatives or read the API docs pkg_npm
can now be used as a dependency within your repo as well as for publishing to npm. It provides aLinkablePackageInfo
which is our internal API to pass package name/path to downstream compilations, essentially providing the "Lerna" feature.- There is experimental support for Bazel's "worker mode" in
rollup_bundle
, which essentially puts Rollup in watch mode. Add thesupports_workers = True
attribute to opt-in. (Thanks contributor 👨💻 @jbedard ) - Better support for pre-defined label variables like
$(rootpath)
and$(execpath)
- we no longer recommend using$(location)
at all. ts_proto_library
(in our labs package, so no stability guarantee) now consumes aproto_library
and generatests_library
-compatible type declarations as well as es5/es6 source files. These files are generated viaprotoc
using theprotoc-gen-grpc-web
plugin. Correspondingly,grpc-web
compatible HTTP services are generated if the consumed proto library has an RPC service definition. See https://github.com/bazelbuild/rules_nodejs/tree/master/examples/protocol_buffers for a full example of how to use the rule, and https://github.com/grpc/grpc-web for more information about the generate grpc-web services. (Thanks contributor 👨💻 @mrmeku )
Features
- builtin: add LinkablePackageInfo to pkg_npm, js_library & ts_library (1023852)
- builtin: add support for predefined variables and custom variable to params_file (34b8cf4)
-
builtin: support
$(rootpath), $ (execpath), predefined & custom variables in templated_args (5358d56) - labs: introduce a new ts_proto_library with grpc support (8b43896)
- rollup: add worker support to rollup_bundle (66db579)
- typescript: add devmode_target, devmode_module, prodmode_target & prodmode_module attributes (#1687) (1a83a7f)
- typescript: add ts_project rule (#1710) (26f6698)
Bug Fixes
- builtin: entry point of a .tsx file is .js (#1732) (24607ed), closes #1730
- builtin: fix for nodejs_binary entry point in bazel-out logic (#1739) (a6e29c2) (863c7de)
closes #1606 - jasmine: user templated_args should be passed to jasmine after 3 internal templated_args (#1743) (baa68c1)
- typescript: fix ts_library to allow deps with module_name but no module_root attrs (#1738) (0b5ad2a)
- typescript: pass rootDir to ts_project tsc actions (#1748) (13caf8b)