From f6181a575c9a79029717866c4ca5410e7430c30e Mon Sep 17 00:00:00 2001 From: Alex Eagle Date: Mon, 1 Feb 2021 17:44:23 -0800 Subject: [PATCH] docs: update docs for release --- docs/Built-ins.html | 135 +++++++++++++++++++++++++++++++++------ docs/Built-ins.md | 130 +++++++++++++++++++++++++++++++------ docs/Concatjs.html | 5 +- docs/Concatjs.md | 3 +- docs/Cypress.html | 2 +- docs/Jasmine.html | 2 +- docs/Labs.html | 83 +----------------------- docs/Labs.md | 87 ------------------------- docs/Protractor.html | 2 +- docs/Rollup.html | 2 +- docs/Terser.html | 2 +- docs/TypeScript.html | 29 ++++----- docs/TypeScript.md | 27 ++++---- docs/changing-rules.html | 4 +- docs/debugging.html | 2 +- docs/dependencies.html | 2 +- docs/examples.html | 18 +++++- docs/index.html | 2 +- docs/install.html | 6 +- docs/repositories.html | 2 +- docs/search.html | 2 +- docs/stamping.html | 2 +- 22 files changed, 288 insertions(+), 261 deletions(-) diff --git a/docs/Built-ins.html b/docs/Built-ins.html index 6d329ff657..1f05136c4f 100755 --- a/docs/Built-ins.html +++ b/docs/Built-ins.html @@ -316,7 +316,7 @@

node_urls

The {version} parameter is substituted with the node_version attribute, and {filename} with the matching entry from the node_repositories attribute.

-

Defaults to ["https://mirror.bazel.build/nodejs.org/dist/v{version}/{filename}", "https://nodejs.org/dist/v{version}/{filename}"]

+

Defaults to ["https://nodejs.org/dist/v{version}/{filename}"]

node_version

@@ -387,7 +387,7 @@

yarn_urls

Each entry is a template, similar to the node_urls attribute, using yarn_version and yarn_repositories in the substitutions.

-

Defaults to ["https://mirror.bazel.build/github.com/yarnpkg/yarn/releases/download/v{version}/{filename}", "https://github.com/yarnpkg/yarn/releases/download/v{version}/{filename}"]

+

Defaults to ["https://github.com/yarnpkg/yarn/releases/download/v{version}/{filename}"]

yarn_version

@@ -400,7 +400,7 @@

nodejs_binary

USAGE

-nodejs_binary(name, configuration_env_vars, data, default_env_vars, entry_point,
+nodejs_binary(name, chdir, configuration_env_vars, data, default_env_vars, entry_point,
               link_workspace_root, templated_args)
@@ -412,6 +412,23 @@

name

(Name, mandatory): A unique name for this target.

+

chdir

+ +

(String): Working directory to run the binary or test in, relative to the workspace. + By default, Bazel always runs in the workspace root. + Due to implementation details, this argument must be underneath this package directory.

+ +
    To run in the directory containing the `nodejs_binary` / `nodejs_test` use
+    `chdir = package_name()`
+    (or if you're in a macro, use `native.package_name()`)
+    
+    WARNING: this will affect other paths passed to the program, either as arguments or in configuration files,
+    which are workspace-relative.
+    You may need `../../` segments to re-relativize such paths to the new working directory.
+
+ +

Defaults to ""

+

configuration_env_vars

(List of strings): Pass these configuration environment variables to the resulting binary. @@ -592,8 +609,8 @@

nodejs_test

USAGE

-nodejs_test(name, configuration_env_vars, data, default_env_vars, entry_point, expected_exit_code,
-            link_workspace_root, templated_args)
+nodejs_test(name, chdir, configuration_env_vars, data, default_env_vars, entry_point,
+            expected_exit_code, link_workspace_root, templated_args)

Identical to nodejs_binary, except this can be used with bazel test as well. @@ -608,11 +625,8 @@

nodejs_test

*_test target created by npm_install/yarn_install, such as mocha_test. Some test runners like Karma and Jasmine have custom rules with added features, e.g. jasmine_node_test.

-

Bazel always runs tests with a working directory set to your workspace root. -If your test needs to run in a different directory, you can write a process.chdir helper script -and invoke it before the test with a --require argument, like -templated_args = ["--node_options=--require=./$(rootpath chdir.js)"]. -See rules_nodejs/internal/node/test/chdir for an example.

+

By default, Bazel runs tests with a working directory set to your workspace root. +Use the chdir attribute to change the working directory before the program starts.

To debug a Node.js test, we recommend saving a group of flags together in a “config”. Put this in your tools/bazel.rc so it’s shared with your team:

@@ -630,6 +644,23 @@

name

(Name, mandatory): A unique name for this target.

+

chdir

+ +

(String): Working directory to run the binary or test in, relative to the workspace. + By default, Bazel always runs in the workspace root. + Due to implementation details, this argument must be underneath this package directory.

+ +
    To run in the directory containing the `nodejs_binary` / `nodejs_test` use
+    `chdir = package_name()`
+    (or if you're in a macro, use `native.package_name()`)
+    
+    WARNING: this will affect other paths passed to the program, either as arguments or in configuration files,
+    which are workspace-relative.
+    You may need `../../` segments to re-relativize such paths to the new working directory.
+
+ +

Defaults to ""

+

configuration_env_vars

(List of strings): Pass these configuration environment variables to the resulting binary. @@ -983,7 +1014,7 @@

pkg_npm

USAGE

-pkg_npm(name, deps, nested_packages, node_context_data, package_name, srcs, substitutions,
+pkg_npm(name, deps, nested_packages, node_context_data, package_name, srcs, substitutions, tgz,
         vendor_external)
@@ -1017,7 +1048,7 @@

pkg_npm

Usage:

-

pkg_npm yields three labels. Build the package directory using the default label:

+

pkg_npm yields four labels. Build the package directory using the default label:

$ bazel build :my_package
 Target //:my_package up-to-date:
@@ -1045,6 +1076,25 @@ 
pkg_npm

 
 
bazel run my_package.publish -- --tag=next

 
+
It is also possible to use the resulting tar file file from the .pack as an action input via the .tar label.
+To make use of this label, the tgz attribute must be set, and the generating pkg_npm rule must have a valid package.json file
+as part of its sources:

+
+
pkg_npm(
+    name = "my_package",
+    srcs = ["package.json"],
+    deps = [":my_typescript_lib"],
+    tgz = "my_package.tgz",
+)
+
+my_rule(
+    name = "foo",
+    srcs = [
+        "//:my_package.tar",
+    ],
+)
+

+
 
ATTRIBUTES

 
 
name

@@ -1097,6 +1147,15 @@ 
substitutions

 
 
Defaults to {}

 
+
tgz

+
+
(String): If set, will create a .tgz file that can be used as an input to another rule, the tar will be given the name assigned to this attribute.

+
+
    NOTE: If this attribute is set, a valid `package.json` file must be included in the sources of this target
+

+
+
Defaults to ""

+
 
vendor_external

 
 
(List of strings): External workspaces whose contents should be vendored into this workspace.
@@ -1567,7 +1626,7 @@ 
npm_package_bin

 
 
 npm_package_bin(tool, package, package_bin, data, outs, args, output_dir, link_workspace_root,
-                kwargs)
+                chdir, kwargs)
 

 
 
Run an arbitrary npm package binary (e.g. a program under node_modules/.bin/*) under Bazel.

@@ -1577,11 +1636,8 @@ 
npm_package_bin

 
This is like a genrule() except that it runs our launcher script that first
 links the node_modules tree before running the program.

 
-
Bazel always runs actions with a working directory set to your workspace root.
-If your tool needs to run in a different directory, you can write a process.chdir helper script
-and invoke it before the action with a --require argument, like
-args = ["--node_options=--require=./$(execpath chdir.js)"]
-See rules_nodejs/internal/node/test/chdir for an example.

+
By default, Bazel runs actions with a working directory set to your workspace root.
+Use the chdir attribute to change the working directory before the program runs.

 
 
This is a great candidate to wrap with a macro, as documented:
 https://docs.bazel.build/versions/master/skylark/macros.html#full-example

@@ -1684,8 +1740,39 @@ 
 
 
Defaults to False

 
+
chdir

+
+
Working directory to run the binary or test in, relative to the workspace.

+
+
By default, Bazel always runs in the workspace root.

+
+
To run in the directory containing the npm_package_bin under the source tree, use
+chdir = package_name()
+(or if you’re in a macro, use native.package_name()).

+
+
To run in the output directory where the npm_package_bin writes outputs, use
+chdir = "$(RULEDIR)"

+
+
WARNING: this will affect other paths passed to the program, either as arguments or in configuration files,
+which are workspace-relative.
+You may need ../../ segments to re-relativize such paths to the new working directory.
+In a BUILD file you could do something like this to point to the output path:

+
+
_package_segments = len(package_name().split("/"))
+npm_package_bin(
+    ...
+    chdir = package_name(),
+    # ../.. segments to re-relative paths from the chdir back to workspace
+    args = ["/".join([".."] * _package_segments + ["$@"])],
+)
+

+
+
Defaults to None

+
 
kwargs

 
+
additional undocumented keyword args

+
 
params_file

 
 
USAGE

@@ -2076,7 +2163,7 @@ 
run_node

 
USAGE

 
 
-run_node(ctx, inputs, arguments, executable, kwargs)
+run_node(ctx, inputs, arguments, executable, chdir, kwargs)
 

 
 
Helper to replace ctx.actions.run

@@ -2101,8 +2188,16 @@ 
executable

 
 
stringy representation of the executable this action will run, eg eg. “my_executable” rather than ctx.executable.my_executable

 
+
chdir

+
+
directory we should change to be the working dir

+
+
Defaults to None

+
 
kwargs

 
+
all other args accepted by ctx.actions.run

+
 
node_modules_aspect

 
 
USAGE

@@ -2192,7 +2287,7 @@ 
name

   

   

     

-      
© 2020 The rules_nodejs authors

+      
© 2021 The rules_nodejs authors

     

   

 

diff --git a/docs/Built-ins.md b/docs/Built-ins.md
index f3f41be1e3..86b5c1bab2 100755
--- a/docs/Built-ins.md
+++ b/docs/Built-ins.md
@@ -169,7 +169,7 @@ Each entry is a template for downloading a node distribution.
 The `{version}` parameter is substituted with the `node_version` attribute,
 and `{filename}` with the matching entry from the `node_repositories` attribute.
 
-Defaults to `["https://mirror.bazel.build/nodejs.org/dist/v{version}/{filename}", "https://nodejs.org/dist/v{version}/{filename}"]`
+Defaults to `["https://nodejs.org/dist/v{version}/{filename}"]`
 
 
node_version

 
@@ -241,7 +241,7 @@ Defaults to `{}`
 
 Each entry is a template, similar to the `node_urls` attribute, using `yarn_version` and `yarn_repositories` in the substitutions.
 
-Defaults to `["https://mirror.bazel.build/github.com/yarnpkg/yarn/releases/download/v{version}/{filename}", "https://github.com/yarnpkg/yarn/releases/download/v{version}/{filename}"]`
+Defaults to `["https://github.com/yarnpkg/yarn/releases/download/v{version}/{filename}"]`
 
 
yarn_version

 
@@ -256,7 +256,7 @@ Defaults to `"1.19.1"`
 **USAGE**
 
 
-nodejs_binary(name, configuration_env_vars, data, default_env_vars, entry_point,
+nodejs_binary(name, chdir, configuration_env_vars, data, default_env_vars, entry_point,
               link_workspace_root, templated_args)
 

 
@@ -270,6 +270,22 @@ Runs some JavaScript code in NodeJS.
 (*Name, mandatory*): A unique name for this target.
 
 
+
chdir

+
+(*String*): Working directory to run the binary or test in, relative to the workspace.
+        By default, Bazel always runs in the workspace root.
+        Due to implementation details, this argument must be underneath this package directory.
+
+        To run in the directory containing the `nodejs_binary` / `nodejs_test` use
+        `chdir = package_name()`
+        (or if you're in a macro, use `native.package_name()`)
+        
+        WARNING: this will affect other paths passed to the program, either as arguments or in configuration files,
+        which are workspace-relative.
+        You may need `../../` segments to re-relativize such paths to the new working directory.
+
+Defaults to `""`
+
 
configuration_env_vars

 
 (*List of strings*): Pass these configuration environment variables to the resulting binary.
@@ -454,8 +470,8 @@ Defaults to `[]`
 **USAGE**
 
 
-nodejs_test(name, configuration_env_vars, data, default_env_vars, entry_point, expected_exit_code,
-            link_workspace_root, templated_args)
+nodejs_test(name, chdir, configuration_env_vars, data, default_env_vars, entry_point,
+            expected_exit_code, link_workspace_root, templated_args)
 

 
 
@@ -471,11 +487,8 @@ If you just want to run a standard test using a test runner from npm, use the ge
 *_test target created by npm_install/yarn_install, such as `mocha_test`.
 Some test runners like Karma and Jasmine have custom rules with added features, e.g. `jasmine_node_test`.
 
-Bazel always runs tests with a working directory set to your workspace root.
-If your test needs to run in a different directory, you can write a `process.chdir` helper script
-and invoke it before the test with a `--require` argument, like
-`templated_args = ["--node_options=--require=./$(rootpath chdir.js)"]`.
-See rules_nodejs/internal/node/test/chdir for an example.
+By default, Bazel runs tests with a working directory set to your workspace root.
+Use the `chdir` attribute to change the working directory before the program starts.
 
 To debug a Node.js test, we recommend saving a group of flags together in a "config".
 Put this in your `tools/bazel.rc` so it's shared with your team:
@@ -497,6 +510,22 @@ remote debugger.
 (*Name, mandatory*): A unique name for this target.
 
 
+
chdir

+
+(*String*): Working directory to run the binary or test in, relative to the workspace.
+        By default, Bazel always runs in the workspace root.
+        Due to implementation details, this argument must be underneath this package directory.
+
+        To run in the directory containing the `nodejs_binary` / `nodejs_test` use
+        `chdir = package_name()`
+        (or if you're in a macro, use `native.package_name()`)
+        
+        WARNING: this will affect other paths passed to the program, either as arguments or in configuration files,
+        which are workspace-relative.
+        You may need `../../` segments to re-relativize such paths to the new working directory.
+
+Defaults to `""`
+
 
configuration_env_vars

 
 (*List of strings*): Pass these configuration environment variables to the resulting binary.
@@ -861,7 +890,7 @@ Defaults to `3600`
 **USAGE**
 
 
-pkg_npm(name, deps, nested_packages, node_context_data, package_name, srcs, substitutions,
+pkg_npm(name, deps, nested_packages, node_context_data, package_name, srcs, substitutions, tgz,
         vendor_external)
 

 
@@ -897,7 +926,7 @@ See the [stamping documentation](https://github.com/bazelbuild/rules_nodejs/blob
 
 Usage:
 
-`pkg_npm` yields three labels. Build the package directory using the default label:
+`pkg_npm` yields four labels. Build the package directory using the default label:
 
 ```sh
 $ bazel build :my_package
@@ -928,6 +957,26 @@ You can pass arguments to npm by escaping them from Bazel using a double-hyphen,
 
 `bazel run my_package.publish -- --tag=next`
 
+It is also possible to use the resulting tar file file from the `.pack` as an action input via the `.tar` label.
+To make use of this label, the `tgz` attribute must be set, and the generating `pkg_npm` rule must have a valid `package.json` file
+as part of its sources:
+
+```python
+pkg_npm(
+    name = "my_package",
+    srcs = ["package.json"],
+    deps = [":my_typescript_lib"],
+    tgz = "my_package.tgz",
+)
+
+my_rule(
+    name = "foo",
+    srcs = [
+        "//:my_package.tar",
+    ],
+)
+```
+
 
 **ATTRIBUTES**
 
@@ -984,6 +1033,14 @@ See the section on stamping in the [README](stamping)
 
 Defaults to `{}`
 
+
tgz

+
+(*String*): If set, will create a `.tgz` file that can be used as an input to another rule, the tar will be given the name assigned to this attribute.
+
+        NOTE: If this attribute is set, a valid `package.json` file must be included in the sources of this target
+
+Defaults to `""`
+
 
vendor_external

 
 (*List of strings*): External workspaces whose contents should be vendored into this workspace.
@@ -1503,7 +1560,7 @@ used for undocumented legacy features
 
 
 npm_package_bin(tool, package, package_bin, data, outs, args, output_dir, link_workspace_root,
-                kwargs)
+                chdir, kwargs)
 

 
 Run an arbitrary npm package binary (e.g. a program under node_modules/.bin/*) under Bazel.
@@ -1513,11 +1570,8 @@ It must produce outputs. If you just want to run a program with `bazel run`, use
 This is like a genrule() except that it runs our launcher script that first
 links the node_modules tree before running the program.
 
-Bazel always runs actions with a working directory set to your workspace root.
-If your tool needs to run in a different directory, you can write a `process.chdir` helper script
-and invoke it before the action with a `--require` argument, like
-`args = ["--node_options=--require=./$(execpath chdir.js)"]`
-See rules_nodejs/internal/node/test/chdir for an example.
+By default, Bazel runs actions with a working directory set to your workspace root.
+Use the `chdir` attribute to change the working directory before the program runs.
 
 This is a great candidate to wrap with a macro, as documented:
 https://docs.bazel.build/versions/master/skylark/macros.html#full-example
@@ -1616,8 +1670,39 @@ If source files need to be required then they can be copied to the bin_dir with
 
 Defaults to `False`
 
+
chdir

+
+Working directory to run the binary or test in, relative to the workspace.
+
+By default, Bazel always runs in the workspace root.
+
+To run in the directory containing the `npm_package_bin` under the source tree, use
+`chdir = package_name()`
+(or if you're in a macro, use `native.package_name()`).
+
+To run in the output directory where the npm_package_bin writes outputs, use
+`chdir = "$(RULEDIR)"`
+
+WARNING: this will affect other paths passed to the program, either as arguments or in configuration files,
+which are workspace-relative.
+You may need `../../` segments to re-relativize such paths to the new working directory.
+In a `BUILD` file you could do something like this to point to the output path:
+
+```python
+_package_segments = len(package_name().split("/"))
+npm_package_bin(
+    ...
+    chdir = package_name(),
+    # ../.. segments to re-relative paths from the chdir back to workspace
+    args = ["/".join([".."] * _package_segments + ["$@"])],
+)
+```
+
+Defaults to `None`
+
 
kwargs

 
+additional undocumented keyword args
 
 
 
@@ -2068,7 +2153,7 @@ Defaults to `[]`
 **USAGE**
 
 
-run_node(ctx, inputs, arguments, executable, kwargs)
+run_node(ctx, inputs, arguments, executable, chdir, kwargs)
 

 
 Helper to replace ctx.actions.run
@@ -2103,8 +2188,15 @@ stringy representation of the executable this action will run, eg eg. "my_execut
 
 
 
+
chdir

+
+directory we should change to be the working dir
+
+Defaults to `None`
+
 
kwargs

 
+all other args accepted by ctx.actions.run
 
 
 
diff --git a/docs/Concatjs.html b/docs/Concatjs.html
index 4549898682..14310da9b7 100755
--- a/docs/Concatjs.html
+++ b/docs/Concatjs.html
@@ -230,7 +230,8 @@ 
Serving JS in development mo
 
To use concatjs_devserver, you simply load the rule, and call it with deps that
 point to your ts_library target(s):

 
-
load("@npm//@bazel/typescript:index.bzl", "concatjs_devserver", "ts_library")
+
load("@npm//@bazel/concatjs:index.bzl", "concatjs_devserver")
+load("@npm//@bazel/typescript:index.bzl", "ts_library")
 
 ts_library(
     name = "app",
@@ -588,7 +589,7 @@ 
kwargs

   

   

     

-      
© 2020 The rules_nodejs authors

+      
© 2021 The rules_nodejs authors

     

   

 

diff --git a/docs/Concatjs.md b/docs/Concatjs.md
index 3505b40697..616a72bf48 100755
--- a/docs/Concatjs.md
+++ b/docs/Concatjs.md
@@ -67,7 +67,8 @@ To use `concatjs_devserver`, you simply `load` the rule, and call it with `deps`
 point to your `ts_library` target(s):
 
 ```python
-load("@npm//@bazel/typescript:index.bzl", "concatjs_devserver", "ts_library")
+load("@npm//@bazel/concatjs:index.bzl", "concatjs_devserver")
+load("@npm//@bazel/typescript:index.bzl", "ts_library")
 
 ts_library(
     name = "app",
diff --git a/docs/Cypress.html b/docs/Cypress.html
index 236e46f48d..33044f1052 100755
--- a/docs/Cypress.html
+++ b/docs/Cypress.html
@@ -323,7 +323,7 @@ 
repo_mapping

   

   

     

-      
© 2020 The rules_nodejs authors

+      
© 2021 The rules_nodejs authors

     

   

 

diff --git a/docs/Jasmine.html b/docs/Jasmine.html
index 8e7cef960b..30b33f9d3a 100755
--- a/docs/Jasmine.html
+++ b/docs/Jasmine.html
@@ -292,7 +292,7 @@ 
kwargs

   

   

     

-      
© 2020 The rules_nodejs authors

+      
© 2021 The rules_nodejs authors

     

   

 

diff --git a/docs/Labs.html b/docs/Labs.html
index a9ae2b81c8..d84cf5429d 100755
--- a/docs/Labs.html
+++ b/docs/Labs.html
@@ -189,86 +189,6 @@ 
Bazel nodejs Labs

   
  • Documentation is sparse
    • 
 
 
-
    protobufjs_ts_library
    
-
-
    USAGE
    
-
-
    -protobufjs_ts_library(name, deps, output_name)
-
    
-
-
    Wraps https://github.com/dcodeIO/protobuf.js for use in Bazel.
    
-
-
    ts_proto_library has identical outputs to ts_library, so it can be used anywhere
-a ts_library can appear, such as in the deps[] of another ts_library.
    
-
-
    Example:
    
-
-
    load("@npm//@bazel/typescript:index.bzl", "ts_library", "ts_proto_library")
-
-proto_library(
-    name = "car_proto",
-    srcs = ["car.proto"],
-)
-
-ts_proto_library(
-    name = "car",
-    deps = [":car_proto"],
-)
-
-ts_library(
-    name = "test_lib",
-    testonly = True,
-    srcs = ["car.spec.ts"],
-    deps = [":car"],
-)
-
    
-
-
    Note in this example we named the ts_proto_library rule car so that the
-result will be car.d.ts. This means our TypeScript code can just
-import {symbols} from './car'. Use the output_name attribute if you want to
-name the rule differently from the output file.
    
-
-
    The JavaScript produced by protobuf.js has a runtime dependency on a support library.
-Under devmode (e.g. concatjs_devserver, karma_web_test_suite) you’ll need to include these scripts
-in the bootstrap phase (before Require.js loads). You can use the label
-@npm//@bazel/labs/protobufjs:bootstrap_scripts to reference these scripts
-in the bootstrap attribute of karma_web_test_suite or concatjs_devserver.
    
-
-
    To complete the example above, you could write a karma_web_test_suite:
    
-
-
    load("@npm//@bazel/concatjs:index.bzl", "karma_web_test_suite")
-
-karma_web_test_suite(
-    name = "test",
-    deps = ["test_lib"],
-    bootstrap = ["@npm//@bazel/labs/protobufjs:bootstrap_scripts"],
-    browsers = [
-        "@io_bazel_rules_webtesting//browsers:chromium-local",
-        "@io_bazel_rules_webtesting//browsers:firefox-local",
-    ],
-)
-
    
-
-
    ATTRIBUTES
    
-
-
    name
    
-
-
    (Name, mandatory): A unique name for this target.
    
-
-
    deps
    
-
-
    (List of labels): proto_library targets
    
-
-
    Defaults to []
    
-
-
    output_name
    
-
-
    (String): Name of the resulting module, which you will import from.
-            If not specified, the name will match the target’s name.
    
-
-
    Defaults to ""
    
-
 
    ts_proto_library
    
 
 
    USAGE
    
@@ -302,7 +222,6 @@ 
    proto
    
           
         
         
       
    
@@ -314,7 +233,7 @@ 
    proto
    
   
    
   
    
     
    
-      
    © 2020 The rules_nodejs authors
    
+      
    © 2021 The rules_nodejs authors
    
     
    
   
    
 
    
diff --git a/docs/Labs.md b/docs/Labs.md
index d3d21e5956..406664c4ac 100755
--- a/docs/Labs.md
+++ b/docs/Labs.md
@@ -23,93 +23,6 @@ By using code in Labs, we trust that you understand:
 - Documentation is sparse
 
 
-## protobufjs_ts_library
-
-**USAGE**
-
-
    -protobufjs_ts_library(name, deps, output_name)
-
    
-
-Wraps https://github.com/dcodeIO/protobuf.js for use in Bazel.
-
-`ts_proto_library` has identical outputs to `ts_library`, so it can be used anywhere
-a `ts_library` can appear, such as in the `deps[]` of another `ts_library`.
-
-Example:
-
-```python
-load("@npm//@bazel/typescript:index.bzl", "ts_library", "ts_proto_library")
-
-proto_library(
-    name = "car_proto",
-    srcs = ["car.proto"],
-)
-
-ts_proto_library(
-    name = "car",
-    deps = [":car_proto"],
-)
-
-ts_library(
-    name = "test_lib",
-    testonly = True,
-    srcs = ["car.spec.ts"],
-    deps = [":car"],
-)
-```
-
-Note in this example we named the `ts_proto_library` rule `car` so that the
-result will be `car.d.ts`. This means our TypeScript code can just
-`import {symbols} from './car'`. Use the `output_name` attribute if you want to
-name the rule differently from the output file.
-
-The JavaScript produced by protobuf.js has a runtime dependency on a support library.
-Under devmode (e.g. `concatjs_devserver`, `karma_web_test_suite`) you'll need to include these scripts
-in the `bootstrap` phase (before Require.js loads). You can use the label
-`@npm//@bazel/labs/protobufjs:bootstrap_scripts` to reference these scripts
-in the `bootstrap` attribute of `karma_web_test_suite` or `concatjs_devserver`.
-
-To complete the example above, you could write a `karma_web_test_suite`:
-
-```python
-load("@npm//@bazel/concatjs:index.bzl", "karma_web_test_suite")
-
-karma_web_test_suite(
-    name = "test",
-    deps = ["test_lib"],
-    bootstrap = ["@npm//@bazel/labs/protobufjs:bootstrap_scripts"],
-    browsers = [
-        "@io_bazel_rules_webtesting//browsers:chromium-local",
-        "@io_bazel_rules_webtesting//browsers:firefox-local",
-    ],
-)
-```
-
-
-**ATTRIBUTES**
-
-
-
    name
    
-
-(*Name, mandatory*): A unique name for this target.
-
-
-
    deps
    
-
-(*List of labels*): proto_library targets
-
-Defaults to `[]`
-
-
    output_name
    
-
-(*String*): Name of the resulting module, which you will import from.
-            If not specified, the name will match the target's name.
-
-Defaults to `""`
-
-
-
 ## ts_proto_library
 
 **USAGE**
diff --git a/docs/Protractor.html b/docs/Protractor.html
index 8493337e97..0704ef1c5b 100755
--- a/docs/Protractor.html
+++ b/docs/Protractor.html
@@ -328,7 +328,7 @@ 
    kwargs
    
   
    
   
    
     
    
-      
    © 2020 The rules_nodejs authors
    
+      
    © 2021 The rules_nodejs authors
    
     
    
   
    
 
    
diff --git a/docs/Rollup.html b/docs/Rollup.html
index f723663155..5232083bc4 100755
--- a/docs/Rollup.html
+++ b/docs/Rollup.html
@@ -564,7 +564,7 @@ 
    supports_workers
    
   
    
   
    
     
    
-      
    © 2020 The rules_nodejs authors
    
+      
    © 2021 The rules_nodejs authors
    
     
    
   
    
 
    
diff --git a/docs/Terser.html b/docs/Terser.html
index d68a4af2ac..262664154f 100755
--- a/docs/Terser.html
+++ b/docs/Terser.html
@@ -328,7 +328,7 @@ 
    terser_bin
    
   
    
   
    
     
    
-      
    © 2020 The rules_nodejs authors
    
+      
    © 2021 The rules_nodejs authors
    
     
    
   
    
 
    
diff --git a/docs/TypeScript.html b/docs/TypeScript.html
index 05a2f878c6..37c0cdf00c 100755
--- a/docs/TypeScript.html
+++ b/docs/TypeScript.html
@@ -296,8 +296,7 @@ 
    User-managed npm dependencies
    
 )
 
    
 
-
    See https://github.com/bazelbuild/rules_nodejs#dependencies for more information on
-managing npm dependencies with Bazel.
    
+
    See the dependencies docs for more information on managing npm dependencies with Bazel.
    
 
 
    Customizing the TypeScript compiler binary
    
 
@@ -324,9 +323,7 @@ 
    Customizing the TypeScript c
 
    then refer to that target in the compiler attribute of your ts_library rule.
    
 
 
    Note that nodejs_binary targets generated by npm_install/yarn_install can include data dependencies
-on packages which aren’t declared as dependencies. For example, if you use [tsickle] to generate Closure Compiler-compatible JS, then it needs to be a data dependency of tsc_wrapped so that it can be loaded at runtime.
    
-
-
    tsickle
    
+on packages which aren’t declared as dependencies. For example, if you use tsickle to generate Closure Compiler-compatible JS, then it needs to be a data dependency of tsc_wrapped so that it can be loaded at runtime.
    
 
 
    Usage
    
 
@@ -686,7 +683,7 @@ 
    ts_project
    
 
     ts_project(name, tsconfig, srcs, args, deps, extends, allow_js, declaration, source_map,
            declaration_map, composite, incremental, emit_declaration_only, ts_build_info_file, tsc,
-           worker_tsc_bin, worker_typescript_module, validate, supports_workers, declaration_dir,
+           typescript_package, typescript_require_path, validate, supports_workers, declaration_dir,
            out_dir, root_dir, link_workspace_root, kwargs)
 
    
 
@@ -734,6 +731,7 @@ 
    ts_project
    
   
    "compilerOptions": {
     "rootDirs": [
         ".",
+        "../../bazel-out/host/bin/path/to",
         "../../bazel-out/darwin-fastbuild/bin/path/to",
         "../../bazel-out/k8-fastbuild/bin/path/to",
         "../../bazel-out/x64_windows-fastbuild/bin/path/to",
@@ -937,22 +935,21 @@ 
    tsc
    
 
 
    Defaults to None
    
 
-
    worker_tsc_bin
    
+
    typescript_package
    
 
-
    Label of the TypeScript compiler binary to run when running in worker mode.
    
+
    Label of the package containing all data deps of tsc.
    
 
-
    For example, tsc = "@my_deps//node_modules/typescript/bin/tsc"
-Or you can pass a custom compiler binary instead.
    
+
    For example, typescript_package = "@my_deps//typescript"
    
 
-
    Defaults to "@npm//:node_modules/typescript/bin/tsc"
    
+
    Defaults to "@npm//typescript"
    
 
-
    worker_typescript_module
    
+
    typescript_require_path
    
 
-
    Label of the package containing all data deps of worker_tsc_bin.
    
+
    Module name which resolves to typescript_package when required
    
 
-
    For example, tsc = "@my_deps//typescript"
    
+
    For example, typescript_require_path = "typescript"
    
 
-
    Defaults to "@npm//typescript"
    
+
    Defaults to "typescript"
    
 
 
    validate
    
 
@@ -1062,7 +1059,7 @@ 
    kwargs
    
   
    
   
    
     
    
-      
    © 2020 The rules_nodejs authors
    
+      
    © 2021 The rules_nodejs authors
    
     
    
   
    
 
    
diff --git a/docs/TypeScript.md b/docs/TypeScript.md
index 5adc71042b..b167bca85f 100755
--- a/docs/TypeScript.md
+++ b/docs/TypeScript.md
@@ -138,8 +138,7 @@ nodejs_binary(
 )
 ```
 
-See  for more information on
-managing npm dependencies with Bazel.
+See the [dependencies docs](dependencies.html) for more information on managing npm dependencies with Bazel.
 
 
 ## Customizing the TypeScript compiler binary
@@ -168,9 +167,7 @@ nodejs_binary(
 then refer to that target in the `compiler` attribute of your `ts_library` rule.
 
 Note that `nodejs_binary` targets generated by `npm_install`/`yarn_install` can include data dependencies
-on packages which aren't declared as dependencies. For example, if you use [tsickle] to generate Closure Compiler-compatible JS, then it needs to be a data dependency of `tsc_wrapped` so that it can be loaded at runtime.
-
-[tsickle](https://github.com/angular/tsickle)
+on packages which aren't declared as dependencies. For example, if you use [tsickle](https://github.com/angular/tsickle) to generate Closure Compiler-compatible JS, then it needs to be a data dependency of `tsc_wrapped` so that it can be loaded at runtime.
 
 
 ## Usage
@@ -558,7 +555,7 @@ Defaults to `False`
 
     ts_project(name, tsconfig, srcs, args, deps, extends, allow_js, declaration, source_map,
            declaration_map, composite, incremental, emit_declaration_only, ts_build_info_file, tsc,
-           worker_tsc_bin, worker_typescript_module, validate, supports_workers, declaration_dir,
+           typescript_package, typescript_require_path, validate, supports_workers, declaration_dir,
            out_dir, root_dir, link_workspace_root, kwargs)
 
    
 
@@ -604,6 +601,7 @@ Any code that works with `tsc` should work with `ts_project` with a few caveats:
 > "compilerOptions": {
 >     "rootDirs": [
 >         ".",
+>         "../../bazel-out/host/bin/path/to",
 >         "../../bazel-out/darwin-fastbuild/bin/path/to",
 >         "../../bazel-out/k8-fastbuild/bin/path/to",
 >         "../../bazel-out/x64_windows-fastbuild/bin/path/to",
@@ -809,22 +807,21 @@ Or you can pass a custom compiler binary instead.
 
 Defaults to `None`
 
-
    worker_tsc_bin
    
+
    typescript_package
    
 
-Label of the TypeScript compiler binary to run when running in worker mode.
+Label of the package containing all data deps of tsc.
 
-For example, `tsc = "@my_deps//node_modules/typescript/bin/tsc"`
-Or you can pass a custom compiler binary instead.
+For example, `typescript_package = "@my_deps//typescript"`
 
-Defaults to `"@npm//:node_modules/typescript/bin/tsc"`
+Defaults to `"@npm//typescript"`
 
-
    worker_typescript_module
    
+
    typescript_require_path
    
 
-Label of the package containing all data deps of worker_tsc_bin.
+Module name which resolves to typescript_package when required
 
-For example, `tsc = "@my_deps//typescript"`
+For example, `typescript_require_path = "typescript"`
 
-Defaults to `"@npm//typescript"`
+Defaults to `"typescript"`
 
 
    validate
    
 
diff --git a/docs/changing-rules.html b/docs/changing-rules.html
index 2312c39ed6..4fcfa567cb 100755
--- a/docs/changing-rules.html
+++ b/docs/changing-rules.html
@@ -191,7 +191,7 @@ 
    Patching the built-in release
    
 
 
    rules_nodejs has a distribution format which is a tgz published to GitHub, and this can make it tricky to make casual changes without forking the project and building your own release artifacts.
    
 
-
    Bazel has a handy patching mechanism that lets you easily apply a local patch to the release artifact for built-in rules: the patches attribute to http_archive.
    
+
    Bazel has a handy patching mechanism that lets you easily apply a local patch to the release artifact for built-in rules: the patches attribute to http_archive.
    
 
 
    First, make your changes in a clone of the rules_nodejs repo. Export a patch file simply using git diff:
    
 
@@ -241,7 +241,7 @@ 
    Patching the built-in release
    
   
    
   
    
     
    
-      
    © 2020 The rules_nodejs authors
    
+      
    © 2021 The rules_nodejs authors
    
     
    
   
    
 
    
diff --git a/docs/debugging.html b/docs/debugging.html
index d721e008a3..8d7038841e 100755
--- a/docs/debugging.html
+++ b/docs/debugging.html
@@ -257,7 +257,7 @@ 
    Debugging with VS Code
    
   
    
   
    
     
    
-      
    © 2020 The rules_nodejs authors
    
+      
    © 2021 The rules_nodejs authors
    
     
    
   
    
 
    
diff --git a/docs/dependencies.html b/docs/dependencies.html
index 41f7059b20..6cdd09d9be 100755
--- a/docs/dependencies.html
+++ b/docs/dependencies.html
@@ -475,7 +475,7 @@ 
    Using self-managed dependencies
    
   
    
   
    
     
    
-      
    © 2020 The rules_nodejs authors
    
+      
    © 2021 The rules_nodejs authors
    
     
    
   
    
 
    
diff --git a/docs/examples.html b/docs/examples.html
index 5f542b7215..859aa1459f 100755
--- a/docs/examples.html
+++ b/docs/examples.html
@@ -295,9 +295,21 @@ 
    Google Closure Compiler
    
 
 
    Protocol Buffers and gRPC
    
 
-
    Note: this is considered a “labs” feature in rules_nodejs, so support and stability are not great. gRPC is still a WIP.
    
+
    Note: this is under active development. Come chat in the #javascript channel on Slack to get the latest.
+Support and stability are not great but expected to improve.
    
 
-
    See examples/protocol_buffers
    
+
    There are many alternative implementations for protobuf and RPC.
+We generally intend to support all of them, with a small layer in rules_nodejs that allows you to build around any of those tools.
    
+
+
    https://github.com/rules-proto-grpc/rules_proto_grpc is an excellent, broad ruleset based on the tooling from http://grpc.io. We may point to this as the canonical example in the future.
    
+
+
    The @bazel/labs package has an experimental ts_proto_library rule.
+It integrates with the “concatjs” bundler and is suitable for projects using ts_library.
+However it’s not clear whether this will be promoted to a stable API.
+See the example in examples/protocol_buffers
    
+
+
    protobuf.js from https://github.com/dcodeIO is a simple alternative.
+See the example in examples/protobufjs
    
 
 
    Bazel-specific
    
 
@@ -372,7 +384,7 @@ 
    Bazel Persistent Workers
    
   
    
   
    
     
    
-      
    © 2020 The rules_nodejs authors
    
+      
    © 2021 The rules_nodejs authors
    
     
    
   
    
 
    
diff --git a/docs/index.html b/docs/index.html
index c4ee785ec9..40aee85a94 100755
--- a/docs/index.html
+++ b/docs/index.html
@@ -377,7 +377,7 @@ 
    Next steps
    
   
    
   
    
     
    
-      
    © 2020 The rules_nodejs authors
    
+      
    © 2021 The rules_nodejs authors
    
     
    
   
    
 
    
diff --git a/docs/install.html b/docs/install.html
index 7d1f916051..64ec5a7a3b 100755
--- a/docs/install.html
+++ b/docs/install.html
@@ -194,8 +194,8 @@ 
    Custom installation
    
 
    load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 http_archive(
     name = "build_bazel_rules_nodejs",
-    sha256 = "84b1d11b1f3bda68c24d992dc6e830bca9db8fa12276f2ca7fcb7761c893976b",
-    urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/3.0.0-rc.1/rules_nodejs-3.0.0-rc.1.tar.gz"],
+    sha256 = "6142e9586162b179fdd570a55e50d1332e7d9c030efd853453438d607569721d",
+    urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/3.0.0/rules_nodejs-3.0.0.tar.gz"],
 )
 
 load("@build_bazel_rules_nodejs//:index.bzl", "node_repositories")
@@ -362,7 +362,7 @@ 
    Cross-compilation
    
   
    
   
    
     
    
-      
    © 2020 The rules_nodejs authors
    
+      
    © 2021 The rules_nodejs authors
    
     
    
   
    
 
    
diff --git a/docs/repositories.html b/docs/repositories.html
index 3b4f018a6c..9d714b6f10 100755
--- a/docs/repositories.html
+++ b/docs/repositories.html
@@ -282,7 +282,7 @@ 
    Generated macros for
   
    
   
    
     
    
-      
    © 2020 The rules_nodejs authors
    
+      
    © 2021 The rules_nodejs authors
    
     
    
   
    
 
    
diff --git a/docs/search.html b/docs/search.html
index fbc161ffb8..8e266a2d1b 100755
--- a/docs/search.html
+++ b/docs/search.html
@@ -77,7 +77,7 @@
   
    
   
    
     
    
-      
    © 2020 The rules_nodejs authors
    
+      
    © 2021 The rules_nodejs authors
    
     
    
   
    
 
    
diff --git a/docs/stamping.html b/docs/stamping.html
index d515e49ea4..c2467d50cf 100755
--- a/docs/stamping.html
+++ b/docs/stamping.html
@@ -294,7 +294,7 @@ 
    Release script
    
   
    
   
    
     
    
-      
    © 2020 The rules_nodejs authors
    
+      
    © 2021 The rules_nodejs authors