-DeclarationInfo(declarations, transitive_declarations, type_blacklisted_declarations) -- -The DeclarationInfo provider allows JS rules to communicate typing information. -TypeScript's .d.ts files are used as the interop format for describing types. -package.json files are included as well, as TypeScript needs to read the "typings" property. - -Do not create DeclarationInfo instances directly, instead use the declaration_info factory function. - -Note: historically this was a subset of the string-typed "typescript" provider. - - -**FIELDS** - -
-ExternalNpmPackageInfo(direct_sources, path, sources, workspace) -- -Provides information about one or more external npm packages - -**FIELDS** - -
-JSEcmaScriptModuleInfo(direct_sources, sources) -- -JavaScript files (and sourcemaps) that are intended to be consumed by downstream tooling. - -They should use modern syntax and ESModules. -These files should typically be named "foo.mjs" - -Historical note: this was the typescript.es6_sources output - -**FIELDS** - -
-JSModuleInfo(direct_sources, sources) -- -JavaScript files and sourcemaps. - -**FIELDS** - -
-JSNamedModuleInfo(direct_sources, sources) -- -JavaScript files whose module name is self-contained. - -For example named AMD/UMD or goog.module format. -These files can be efficiently served with the concatjs bundler. -These outputs should be named "foo.umd.js" -(note that renaming it from "foo.js" doesn't affect the module id) - -Historical note: this was the typescript.es5_sources output. - - -**FIELDS** - -
-LinkablePackageInfo(files, package_name, package_path, path, _tslibrary) -- -The LinkablePackageInfo provider provides information to the linker for linking pkg_npm built packages - -**FIELDS** - -
-NodeContextInfo(stamp) -- -Provides data about the build context, like config_setting's - -**FIELDS** - -
-NodeRuntimeDepsInfo(deps, pkgs) -- -Stores runtime dependencies of a nodejs_binary or nodejs_test - -These are files that need to be found by the node module resolver at runtime. - -Historically these files were passed using the Runfiles mechanism. -However runfiles has a big performance penalty of creating a symlink forest -with FS API calls for every file in node_modules. -It also causes there to be separate node_modules trees under each binary. This -prevents user-contributed modules passed as deps[] to a particular action from -being found by node module resolver, which expects everything in one tree. - -In node, this resolution is done dynamically by assuming a node_modules -tree will exist on disk, so we assume node actions/binary/test executions will -do the same. - - -**FIELDS** - -
-NpmPackageInfo(direct_sources, path, sources, workspace) -- -Provides information about one or more external npm packages - -**FIELDS** - -
-declaration_info(declarations, deps) -- -Constructs a DeclarationInfo including all transitive files needed to type-check from DeclarationInfo providers in a list of deps. - -**PARAMETERS** - - -
-js_ecma_script_module_info(sources, deps) -- -Constructs a JSEcmaScriptModuleInfo including all transitive sources from JSEcmaScriptModuleInfo providers in a list of deps. - -Returns a single JSEcmaScriptModuleInfo. - -**PARAMETERS** - - -
-js_module_info(sources, deps) -- -Constructs a JSModuleInfo including all transitive sources from JSModuleInfo providers in a list of deps. - -Returns a single JSModuleInfo. - -**PARAMETERS** - - -
-js_named_module_info(sources, deps) -- -Constructs a JSNamedModuleInfo including all transitive sources from JSNamedModuleInfo providers in a list of deps. - -Returns a single JSNamedModuleInfo. - -**PARAMETERS** - - -
-run_node(ctx, inputs, arguments, executable, chdir, kwargs) -- -Helper to replace ctx.actions.run - -This calls node programs with a node_modules directory in place - - -**PARAMETERS** - - -
-node_modules_aspect(name) -- - - -**ASPECT ATTRIBUTES** - -
-node_repositories(name, node_download_auth, node_repositories, node_urls, node_version, - package_json, preserve_symlinks, repo_mapping, vendored_node, vendored_yarn, - yarn_download_auth, yarn_repositories, yarn_urls, yarn_version) -- -To be run in user's WORKSPACE to install rules_nodejs dependencies. - -This rule sets up node, npm, and yarn. The versions of these tools can be specified in one of three ways - -### Simplest Usage - -Specify no explicit versions. This will download and use the latest NodeJS & Yarn that were available when the -version of rules_nodejs you're using was released. -Note that you can skip calling `node_repositories` in your WORKSPACE file - if you later try to `yarn_install` or `npm_install`, -we'll automatically select this simple usage for you. - -### Forced version(s) - -You can select the version of NodeJS and/or Yarn to download & use by specifying it when you call node_repositories, -using a value that matches a known version (see the default values) - -### Using a custom version - -You can pass in a custom list of NodeJS and/or Yarn repositories and URLs for node_resositories to use. - -#### Custom NodeJS versions - -To specify custom NodeJS versions, use the `node_repositories` attribute - -```python -node_repositories( - node_repositories = { - "10.10.0-darwin_amd64": ("node-v10.10.0-darwin-x64.tar.gz", "node-v10.10.0-darwin-x64", "00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e"), - "10.10.0-linux_amd64": ("node-v10.10.0-linux-x64.tar.xz", "node-v10.10.0-linux-x64", "686d2c7b7698097e67bcd68edc3d6b5d28d81f62436c7cf9e7779d134ec262a9"), - "10.10.0-windows_amd64": ("node-v10.10.0-win-x64.zip", "node-v10.10.0-win-x64", "70c46e6451798be9d052b700ce5dadccb75cf917f6bf0d6ed54344c856830cfb"), - }, -) -``` - -These can be mapped to a custom download URL, using `node_urls` - -```python -node_repositories( - node_version = "10.10.0", - node_repositories = {"10.10.0-darwin_amd64": ("node-v10.10.0-darwin-x64.tar.gz", "node-v10.10.0-darwin-x64", "00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e")}, - node_urls = ["https://mycorpproxy/mirror/node/v{version}/{filename}"], -) -``` - -A Mac client will try to download node from `https://mycorpproxy/mirror/node/v10.10.0/node-v10.10.0-darwin-x64.tar.gz` -and expect that file to have sha256sum `00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e` - -#### Custom Yarn versions - -To specify custom Yarn versions, use the `yarn_repositories` attribute - -```python -node_repositories( - yarn_repositories = { - "1.12.1": ("yarn-v1.12.1.tar.gz", "yarn-v1.12.1", "09bea8f4ec41e9079fa03093d3b2db7ac5c5331852236d63815f8df42b3ba88d"), - }, -) -``` - -Like `node_urls`, the `yarn_urls` attribute can be used to provide a list of custom URLs to use to download yarn - -```python -node_repositories( - yarn_repositories = { - "1.12.1": ("yarn-v1.12.1.tar.gz", "yarn-v1.12.1", "09bea8f4ec41e9079fa03093d3b2db7ac5c5331852236d63815f8df42b3ba88d"), - }, - yarn_version = "1.12.1", - yarn_urls = [ - "https://github.com/yarnpkg/yarn/releases/download/v{version}/{filename}", - ], -) -``` - -Will download yarn from https://github.com/yarnpkg/yarn/releases/download/v1.2.1/yarn-v1.12.1.tar.gz -and expect the file to have sha256sum `09bea8f4ec41e9079fa03093d3b2db7ac5c5331852236d63815f8df42b3ba88d`. - -If you don't use Yarn at all, you can skip downloading it by setting `yarn_urls = []`. - -### Using a local version - -To avoid downloads, you can check in vendored copies of NodeJS and/or Yarn and set vendored_node and or vendored_yarn -to point to those before calling node_repositories. You can also point to a location where node is installed on your computer, -but we don't recommend this because it leads to version skew between you, your coworkers, and your Continuous Integration environment. -It also ties your build to a single platform, preventing you from cross-compiling into a Linux docker image on Mac for example. - -See the [the repositories documentation](repositories.html) for how to use the resulting repositories. - -### Manual install - -You can optionally pass a `package_json` array to node_repositories. This lets you use Bazel's version of yarn or npm, yet always run the package manager yourself. -This is an advanced scenario you can use in place of the `npm_install` or `yarn_install` rules, but we don't recommend it, and might remove it in the future. - -``` -load("@build_bazel_rules_nodejs//:index.bzl", "node_repositories") -node_repositories(package_json = ["//:package.json", "//subpkg:package.json"]) -``` - -Running `bazel run @nodejs//:yarn_node_repositories` in this repo would create `/node_modules` and `/subpkg/node_modules`. - -Note that the dependency installation scripts will run in each subpackage indicated by the `package_json` attribute. - - -**ATTRIBUTES** - - -
For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`). - - -
-nodejs_binary(name, chdir, configuration_env_vars, data, default_env_vars, entry_point, env, - link_workspace_root, templated_args) -- -Runs some JavaScript code in NodeJS. - -**ATTRIBUTES** - - -
-nodejs_test(name, chdir, configuration_env_vars, data, default_env_vars, entry_point, env, - expected_exit_code, link_workspace_root, templated_args) -- - -Identical to `nodejs_binary`, except this can be used with `bazel test` as well. -When the binary returns zero exit code, the test passes; otherwise it fails. - -`nodejs_test` is a convenient way to write a novel kind of test based on running -your own test runner. For example, the `ts-api-guardian` library has a way to -assert the public API of a TypeScript program, and uses `nodejs_test` here: -https://github.com/angular/angular/blob/master/tools/ts-api-guardian/index.bzl - -If you just want to run a standard test using a test runner from npm, use the generated -*_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`. - -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: -```python -# Enable debugging tests with --config=debug -test:debug --test_arg=--node_options=--inspect-brk --test_output=streamed --test_strategy=exclusive --test_timeout=9999 --nocache_test_results -``` - -Now you can add `--config=debug` to any `bazel test` command line. -The runtime will pause before executing the program, allowing you to connect a -remote debugger. - - -**ATTRIBUTES** - - -
-npm_install(name, args, data, environment, generate_local_modules_build_files, included_files, - links, manual_build_file_contents, npm_command, package_json, package_lock_json, - package_path, patch_args, patch_tool, post_install_patches, pre_install_patches, quiet, - repo_mapping, strict_visibility, symlink_node_modules, timeout) -- -Runs npm install during workspace setup. - -This rule will set the environment variable `BAZEL_NPM_INSTALL` to '1' (unless it -set to another value in the environment attribute). Scripts may use to this to -check if yarn is being run by the `npm_install` repository rule. - -**ATTRIBUTES** - - -
For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`). - - -
-pkg_npm(name, deps, nested_packages, node_context_data, package_name, package_path, srcs, - substitutions, tgz, vendor_external) -- -The pkg_npm rule creates a directory containing a publishable npm artifact. - -Example: - -```python -load("@build_bazel_rules_nodejs//:index.bzl", "pkg_npm") - -pkg_npm( - name = "my_package", - srcs = ["package.json"], - deps = [":my_typescript_lib"], - substitutions = {"//internal/": "//"}, -) -``` - -You can use a pair of `// BEGIN-INTERNAL ... // END-INTERNAL` comments to mark regions of files that should be elided during publishing. -For example: - -```javascript -function doThing() { - // BEGIN-INTERNAL - // This is a secret internal-only comment - doInternalOnlyThing(); - // END-INTERNAL -} -``` - -With the Bazel stamping feature, pkg_npm will replace any placeholder version in your package with the actual version control tag. -See the [stamping documentation](https://github.com/bazelbuild/rules_nodejs/blob/master/docs/index.md#stamping) - -Usage: - -`pkg_npm` yields four labels. Build the package directory using the default label: - -```sh -$ bazel build :my_package -Target //:my_package up-to-date: - bazel-out/fastbuild/bin/my_package -$ ls -R bazel-out/fastbuild/bin/my_package -``` - -Dry-run of publishing to npm, calling `npm pack` (it builds the package first if needed): - -```sh -$ bazel run :my_package.pack -INFO: Running command line: bazel-out/fastbuild/bin/my_package.pack -my-package-name-1.2.3.tgz -$ tar -tzf my-package-name-1.2.3.tgz -``` - -Actually publish the package with `npm publish` (also builds first): - -```sh -# Check login credentials -$ bazel run @nodejs//:npm_node_repositories who -# Publishes the package -$ bazel run :my_package.publish -``` - -You can pass arguments to npm by escaping them from Bazel using a double-hyphen, for example: - -`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** - - -
-pkg_web(name, additional_root_paths, node_context_data, srcs, substitutions) -- -Assembles a web application from source files. - -**ATTRIBUTES** - - -
-yarn_install(name, args, data, environment, frozen_lockfile, generate_local_modules_build_files, - included_files, links, manual_build_file_contents, package_json, package_path, - patch_args, patch_tool, post_install_patches, pre_install_patches, quiet, repo_mapping, - strict_visibility, symlink_node_modules, timeout, use_global_yarn_cache, yarn_lock) -- -Runs yarn install during workspace setup. - -This rule will set the environment variable `BAZEL_YARN_INSTALL` to '1' (unless it -set to another value in the environment attribute). Scripts may use to this to -check if yarn is being run by the `yarn_install` repository rule. - -**ATTRIBUTES** - - -
For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`). - - -
-check_bazel_version(minimum_bazel_version, message) -- - Verify the users Bazel version is at least the given one. - -This can be used in rule implementations that depend on changes in Bazel, -to warn users about a mismatch between the rule and their installed Bazel -version. - -This should *not* be used in users WORKSPACE files. To locally pin your -Bazel version, just create the .bazelversion file in your workspace. - - -**PARAMETERS** - - -
-copy_to_bin(name, srcs, kwargs) -- -Copies a source file to bazel-bin at the same workspace-relative path. - -e.g. `
-generated_file_test(name, generated, src, substring_search, src_dbg, kwargs) -- -Tests that a file generated by Bazel has identical content to a file in the workspace. - -This is useful for testing, where a "snapshot" or "golden" file is checked in, -so that you can code review changes to the generated output. - - -**PARAMETERS** - - -
-js_library(name, srcs, package_name, package_path, deps, kwargs) -- -Groups JavaScript code so that it can be depended on like an npm package. - -`js_library` is intended to be used internally within Bazel, such as between two libraries in your monorepo. -This rule doesn't perform any build steps ("actions") so it is similar to a `filegroup`. -However it provides several Bazel "Providers" for interop with other rules. - -> Compare this to `pkg_npm` which just produces a directory output, and therefore can't expose individual -> files to downstream targets and causes a cascading re-build of all transitive dependencies when any file -> changes. Also `pkg_npm` is intended to publish your code for external usage outside of Bazel, like -> by publishing to npm or artifactory, while `js_library` is for internal dependencies within your repo. - -`js_library` also copies any source files into the bazel-out folder. -This is the same behavior as the `copy_to_bin` rule. -By copying the complete package to the output tree, we ensure that the linker (our `npm link` equivalent) -will make your source files available in the node_modules tree where resolvers expect them. -It also means you can have relative imports between the files -rather than being forced to use Bazel's "Runfiles" semantics where any program might need a helper library -to resolve files between the logical union of the source tree and the output tree. - -### Example - -A typical example usage of `js_library` is to expose some sources with a package name: - -```python -ts_project( - name = "compile_ts", - srcs = glob(["*.ts"]), -) - -js_library( - name = "my_pkg", - # Code that depends on this target can import from "@myco/mypkg" - package_name = "@myco/mypkg", - # Consumers might need fields like "main" or "typings" - srcs = ["package.json"], - # The .js and .d.ts outputs from above will be part of the package - deps = [":compile_ts"], -) -``` - -> To help work with "named AMD" modules as required by `concatjs_devserver` and other Google-style "concatjs" rules, -> `js_library` has some undocumented advanced features you can find in the source code or in our examples. -> These should not be considered a public API and aren't subject to our usual support and semver guarantees. - -### Outputs - -Like all Bazel rules it produces a default output by providing [DefaultInfo]. -You'll get these outputs if you include this in the `srcs` of a typical rule like `filegroup`, -and these will be the printed result when you `bazel build //some:js_library_target`. -The default outputs are all of: -- [DefaultInfo] produced by targets in `deps` -- A copy of all sources (InputArtifacts from your source tree) in the bazel-out directory - -When there are TypeScript typings files, `js_library` provides [DeclarationInfo](#declarationinfo) -so this target can be a dependency of a TypeScript rule. This includes any `.d.ts` files in `srcs` as well -as transitive ones from `deps`. -It will also provide [OutputGroupInfo] with a "types" field, so you can select the typings outputs with -`bazel build //some:js_library_target --output_groups=types` or with a `filegroup` rule using the -[output_group] attribute. - -In order to work with the linker (similar to `npm link` for first-party monorepo deps), `js_library` provides -[LinkablePackageInfo](#linkablepackageinfo) for use with our "linker" that makes this package importable. - -It also provides: -- [ExternalNpmPackageInfo](#externalnpmpackageinfo) to interop with rules that expect third-party npm packages. -- [JSModuleInfo](#jsmoduleinfo) so rules like bundlers can collect the transitive set of .js files -- [JSNamedModuleInfo](#jsnamedmoduleinfo) for rules that expect named AMD or `goog.module` format JS - -[OutputGroupInfo]: https://docs.bazel.build/versions/master/skylark/lib/OutputGroupInfo.html -[DefaultInfo]: https://docs.bazel.build/versions/master/skylark/lib/DefaultInfo.html -[output_group]: https://docs.bazel.build/versions/master/be/general.html#filegroup.output_group - - -**PARAMETERS** - - -
-npm_package_bin(tool, package, package_bin, data, env, outs, args, stderr, stdout, exit_code_out, - output_dir, link_workspace_root, chdir, kwargs) -- -Run an arbitrary npm package binary (e.g. a program under node_modules/.bin/*) under Bazel. - -It must produce outputs. If you just want to run a program with `bazel run`, use the nodejs_binary rule. - -This is like a genrule() except that it runs our launcher script that first -links the node_modules tree before running the program. - -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 - - -**PARAMETERS** - - -
-params_file(name, out, args, data, newline, kwargs) -- -Generates a UTF-8 encoded params file from a list of arguments. - -Handles variable substitutions for args. - - -**PARAMETERS** - - -