Google Git
Sign in
pigweed/third_party/github/bazel-contrib/rules_nodejs/db983193cdf9f2ef506ca081f1ead75cb1093754/./docs/Built-ins.html
blob: 2709cb96aa7d35316e21bb1b80bb54f8fb9ceee9 [file] [log] [blame]
<!DOCTYPE html>
<html itemscope itemtype="https://schema.org/WebPage" lang="en">
<head>
<meta charset="utf-8">
<meta content="IE=edge" http-equiv="X-UA-Compatible">
<meta content="width=device-width, initial-scale=1" name="viewport">
<link href="/rules_nodejs/Built-ins.html" rel="canonical">
<link href="" rel="shortcut icon" type="image/png">
<title>rules_nodejs - Built-ins</title>
<!-- Webfont -->
<link href="//fonts.googleapis.com/css?family=Source+Code+Pro:400,500,700|Open+Sans:400,600,700,800" rel="stylesheet">
<!-- Bootstrap -->
<link crossorigin="anonymous" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"
integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" rel="stylesheet">
<!-- Font Awesome -->
<link href="https://stackpath.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet">
<!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
<!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->
<!-- Custom stylesheet -->
<link href="/rules_nodejs/css/main.css" rel="stylesheet">
<!-- metadata -->
<meta content="rules_nodejs" name="og:title"/>
<meta content="JavaScript and NodeJS rules for Bazel" name="og:description"/>
</head>
<body>
<nav class="navbar navbar-inverse navbar-fixed-top" id="common-nav">
<div class="container">
<!-- Brand and toggle get grouped for better mobile display -->
<div class="navbar-header">
<button class="navbar-toggle collapsed" data-target="#bs-example-navbar-collapse-1" data-toggle="collapse"
type="button">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="/rules_nodejs/">
<img class="navbar-logo" src="/rules_nodejs/images/bazel-navbar.svg">
</a>
</div>
<!-- Collect the nav links, forms, and other content for toggling -->
<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
<form class="navbar-form navbar-right" action="/rules_nodejs/search.html" id="cse-search-box">
<div class="form-group">
<input type="hidden" name="cx" value="2735dc72dd157bd19">
<input type="search" name="q" id="q" class="form-control input-sm" placeholder="Search">
</div>
</form>
<ul class="nav navbar-nav navbar-right">
<li><a href="https://github.com/bazelbuild/rules_nodejs">GitHub</a></li>
</ul>
</div><!-- /.navbar-collapse -->
</div><!-- /.container-fluid -->
</nav>
<div class="container vpad">
<div class="row">
<div class="col-md-2">
<a aria-controls="sidebar-nav"
aria-expanded="false" class="btn btn-default btn-lg btn-block sidebar-toggle" data-toggle="collapse"
href="#sidebar-nav">
<i class="glyphicon glyphicon-menu-hamburger"></i> Navigation
</a>
<nav class="sidebar collapse" id="sidebar-nav">
<select onchange="location.href=this.value">
<option selected disabled hidden>Version: 3.x</option>
<option value="/rules_nodejs/Built-ins.html">3.x</option>
<option value="https://docs.aspect.dev/rules_nodejs/Built-ins.html">2.3</option>
</select>
<h3>rules_nodejs</h3>
<ul class="sidebar-nav">
<li><a href="/rules_nodejs/">Introduction</a></li>
<li><a href="install.html">Installation</a></li>
<li><a href="repositories.html">Repositories</a></li>
<li><a href="dependencies.html">Dependencies</a></li>
<li><a href="debugging.html">Debugging</a></li>
<li><a href="stamping.html">Stamping</a></li>
<li><a href="changing-rules.html">Making changes to rules_nodejs</a></li>
<li><a href="examples.html">Examples</a></li>
</ul>
<h3>Rules</h3>
<ul class="sidebar-nav">
<li><a href="/rules_nodejs/Built-ins.html">Built-ins</a></li>
<li><a href="/rules_nodejs/Concatjs.html">Concatjs</a></li>
<li><a href="/rules_nodejs/Cypress.html">Cypress</a></li>
<li><a href="/rules_nodejs/Jasmine.html">Jasmine</a></li>
<li><a href="/rules_nodejs/Labs.html">Labs</a></li>
<li><a href="/rules_nodejs/Protractor.html">Protractor</a></li>
<li><a href="/rules_nodejs/Rollup.html">Rollup</a></li>
<li><a href="/rules_nodejs/Terser.html">Terser</a></li>
<li><a href="/rules_nodejs/TypeScript.html">TypeScript</a></li>
<li><a href="/rules_nodejs/esbuild.html">esbuild</a></li>
</ul>
<h3>Community</h3>
<ul class="sidebar-nav">
<li><a href="https://github.com/bazelbuild/rules_nodejs/blob/master/CONTRIBUTING.md">Contribute to
rules_nodejs</a></li>
<li><a href="https://slack.bazel.build">Join #javascript on Slack</a></li>
<li><a href="https://github.com/bazelbuild/rules_nodejs/issues">Issue Tracker</a></li>
<li><a href="https://github.com/bazelbuild/rules_nodejs">Github</a></li>
</ul>
</nav>
</div>
<div class="col-md-8">
<div class="content">
<!-- *********************
DO NOT EDIT THIS FILE
It is a generated build output from Stardoc.
Instead you must edit the .bzl file where the rules are declared,
or possibly a markdown file next to the .bzl file
********************* -->
<h1 id="built-in-rules">Built-in rules</h1>
<p>These rules are available without any npm installation, via the <code class="language-plaintext highlighter-rouge">WORKSPACE</code> install of the <code class="language-plaintext highlighter-rouge">build_bazel_rules_nodejs</code> workspace. This is necessary to bootstrap Bazel to run the package manager to download other rules from NPM.</p>
<h2 id="node_repositories">node_repositories</h2>
<p><strong>USAGE</strong></p>
<pre>
node_repositories(<a href="#node_repositories-name">name</a>, <a href="#node_repositories-node_download_auth">node_download_auth</a>, <a href="#node_repositories-node_repositories">node_repositories</a>, <a href="#node_repositories-node_urls">node_urls</a>, <a href="#node_repositories-node_version">node_version</a>,
<a href="#node_repositories-package_json">package_json</a>, <a href="#node_repositories-preserve_symlinks">preserve_symlinks</a>, <a href="#node_repositories-repo_mapping">repo_mapping</a>, <a href="#node_repositories-vendored_node">vendored_node</a>, <a href="#node_repositories-vendored_yarn">vendored_yarn</a>,
<a href="#node_repositories-yarn_download_auth">yarn_download_auth</a>, <a href="#node_repositories-yarn_repositories">yarn_repositories</a>, <a href="#node_repositories-yarn_urls">yarn_urls</a>, <a href="#node_repositories-yarn_version">yarn_version</a>)
</pre>
<p>To be run in user’s WORKSPACE to install rules_nodejs dependencies.</p>
<p>This rule sets up node, npm, and yarn. The versions of these tools can be specified in one of three ways</p>
<h3 id="simplest-usage">Simplest Usage</h3>
<p>Specify no explicit versions. This will download and use the latest NodeJS &amp; Yarn that were available when the
version of rules_nodejs you’re using was released.
Note that you can skip calling <code class="language-plaintext highlighter-rouge">node_repositories</code> in your WORKSPACE file - if you later try to <code class="language-plaintext highlighter-rouge">yarn_install</code> or <code class="language-plaintext highlighter-rouge">npm_install</code>,
we’ll automatically select this simple usage for you.</p>
<h3 id="forced-versions">Forced version(s)</h3>
<p>You can select the version of NodeJS and/or Yarn to download &amp; use by specifying it when you call node_repositories,
using a value that matches a known version (see the default values)</p>
<h3 id="using-a-custom-version">Using a custom version</h3>
<p>You can pass in a custom list of NodeJS and/or Yarn repositories and URLs for node_resositories to use.</p>
<h4 id="custom-nodejs-versions">Custom NodeJS versions</h4>
<p>To specify custom NodeJS versions, use the <code class="language-plaintext highlighter-rouge">node_repositories</code> attribute</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">node_repositories</span><span class="p">(</span>
<span class="n">node_repositories</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">"10.10.0-darwin_amd64"</span><span class="p">:</span> <span class="p">(</span><span class="s">"node-v10.10.0-darwin-x64.tar.gz"</span><span class="p">,</span> <span class="s">"node-v10.10.0-darwin-x64"</span><span class="p">,</span> <span class="s">"00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e"</span><span class="p">),</span>
<span class="s">"10.10.0-linux_amd64"</span><span class="p">:</span> <span class="p">(</span><span class="s">"node-v10.10.0-linux-x64.tar.xz"</span><span class="p">,</span> <span class="s">"node-v10.10.0-linux-x64"</span><span class="p">,</span> <span class="s">"686d2c7b7698097e67bcd68edc3d6b5d28d81f62436c7cf9e7779d134ec262a9"</span><span class="p">),</span>
<span class="s">"10.10.0-windows_amd64"</span><span class="p">:</span> <span class="p">(</span><span class="s">"node-v10.10.0-win-x64.zip"</span><span class="p">,</span> <span class="s">"node-v10.10.0-win-x64"</span><span class="p">,</span> <span class="s">"70c46e6451798be9d052b700ce5dadccb75cf917f6bf0d6ed54344c856830cfb"</span><span class="p">),</span>
<span class="p">},</span>
<span class="p">)</span>
</code></pre></div></div>
<p>These can be mapped to a custom download URL, using <code class="language-plaintext highlighter-rouge">node_urls</code></p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">node_repositories</span><span class="p">(</span>
<span class="n">node_version</span> <span class="o">=</span> <span class="s">"10.10.0"</span><span class="p">,</span>
<span class="n">node_repositories</span> <span class="o">=</span> <span class="p">{</span><span class="s">"10.10.0-darwin_amd64"</span><span class="p">:</span> <span class="p">(</span><span class="s">"node-v10.10.0-darwin-x64.tar.gz"</span><span class="p">,</span> <span class="s">"node-v10.10.0-darwin-x64"</span><span class="p">,</span> <span class="s">"00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e"</span><span class="p">)},</span>
<span class="n">node_urls</span> <span class="o">=</span> <span class="p">[</span><span class="s">"https://mycorpproxy/mirror/node/v{version}/{filename}"</span><span class="p">],</span>
<span class="p">)</span>
</code></pre></div></div>
<p>A Mac client will try to download node from <code class="language-plaintext highlighter-rouge">https://mycorpproxy/mirror/node/v10.10.0/node-v10.10.0-darwin-x64.tar.gz</code>
and expect that file to have sha256sum <code class="language-plaintext highlighter-rouge">00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e</code></p>
<h4 id="custom-yarn-versions">Custom Yarn versions</h4>
<p>To specify custom Yarn versions, use the <code class="language-plaintext highlighter-rouge">yarn_repositories</code> attribute</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">node_repositories</span><span class="p">(</span>
<span class="n">yarn_repositories</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">"1.12.1"</span><span class="p">:</span> <span class="p">(</span><span class="s">"yarn-v1.12.1.tar.gz"</span><span class="p">,</span> <span class="s">"yarn-v1.12.1"</span><span class="p">,</span> <span class="s">"09bea8f4ec41e9079fa03093d3b2db7ac5c5331852236d63815f8df42b3ba88d"</span><span class="p">),</span>
<span class="p">},</span>
<span class="p">)</span>
</code></pre></div></div>
<p>Like <code class="language-plaintext highlighter-rouge">node_urls</code>, the <code class="language-plaintext highlighter-rouge">yarn_urls</code> attribute can be used to provide a list of custom URLs to use to download yarn</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">node_repositories</span><span class="p">(</span>
<span class="n">yarn_repositories</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">"1.12.1"</span><span class="p">:</span> <span class="p">(</span><span class="s">"yarn-v1.12.1.tar.gz"</span><span class="p">,</span> <span class="s">"yarn-v1.12.1"</span><span class="p">,</span> <span class="s">"09bea8f4ec41e9079fa03093d3b2db7ac5c5331852236d63815f8df42b3ba88d"</span><span class="p">),</span>
<span class="p">},</span>
<span class="n">yarn_version</span> <span class="o">=</span> <span class="s">"1.12.1"</span><span class="p">,</span>
<span class="n">yarn_urls</span> <span class="o">=</span> <span class="p">[</span>
<span class="s">"https://github.com/yarnpkg/yarn/releases/download/v{version}/{filename}"</span><span class="p">,</span>
<span class="p">],</span>
<span class="p">)</span>
</code></pre></div></div>
<p>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 <code class="language-plaintext highlighter-rouge">09bea8f4ec41e9079fa03093d3b2db7ac5c5331852236d63815f8df42b3ba88d</code>.</p>
<h3 id="using-a-local-version">Using a local version</h3>
<p>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.</p>
<p>See the <a href="repositories.html">the repositories documentation</a> for how to use the resulting repositories.</p>
<h3 id="manual-install">Manual install</h3>
<p>You can optionally pass a <code class="language-plaintext highlighter-rouge">package_json</code> 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 <code class="language-plaintext highlighter-rouge">npm_install</code> or <code class="language-plaintext highlighter-rouge">yarn_install</code> rules, but we don’t recommend it, and might remove it in the future.</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>load("@build_bazel_rules_nodejs//:index.bzl", "node_repositories")
node_repositories(package_json = ["//:package.json", "//subpkg:package.json"])
</code></pre></div></div>
<p>Running <code class="language-plaintext highlighter-rouge">bazel run @nodejs//:yarn_node_repositories</code> in this repo would create <code class="language-plaintext highlighter-rouge">/node_modules</code> and <code class="language-plaintext highlighter-rouge">/subpkg/node_modules</code>.</p>
<p>Note that the dependency installation scripts will run in each subpackage indicated by the <code class="language-plaintext highlighter-rouge">package_json</code> attribute.</p>
<p><strong>ATTRIBUTES</strong></p>
<h4 id="node_repositories-name">name</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory</em>): A unique name for this repository.</p>
<h4 id="node_repositories-node_download_auth">node_download_auth</h4>
<p>(<em><a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -&gt; String</a></em>): auth to use for all url requests
Example: {“type”: “basic”, “login”: “<UserName>", "password": "<Password>" }</Password></UserName></p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">{}</code></p>
<h4 id="node_repositories-node_repositories">node_repositories</h4>
<p>(<em><a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -&gt; List of strings</a></em>): Custom list of node repositories to use</p>
<p>A dictionary mapping NodeJS versions to sets of hosts and their corresponding (filename, strip_prefix, sha256) tuples.
You should list a node binary for every platform users have, likely Mac, Windows, and Linux.</p>
<p>By default, if this attribute has no items, we’ll use a list of all public NodeJS releases.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">{}</code></p>
<h4 id="node_repositories-node_urls">node_urls</h4>
<p>(<em>List of strings</em>): custom list of URLs to use to download NodeJS</p>
<p>Each entry is a template for downloading a node distribution.</p>
<p>The <code class="language-plaintext highlighter-rouge">{version}</code> parameter is substituted with the <code class="language-plaintext highlighter-rouge">node_version</code> attribute,
and <code class="language-plaintext highlighter-rouge">{filename}</code> with the matching entry from the <code class="language-plaintext highlighter-rouge">node_repositories</code> attribute.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">["https://nodejs.org/dist/v{version}/{filename}"]</code></p>
<h4 id="node_repositories-node_version">node_version</h4>
<p>(<em>String</em>): the specific version of NodeJS to install or, if vendored_node is specified, the vendored version of node</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">"12.13.0"</code></p>
<h4 id="node_repositories-package_json">package_json</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a></em>): (ADVANCED, not recommended)
a list of labels, which indicate the package.json files that will be installed
when you manually run the package manager, e.g. with
<code class="language-plaintext highlighter-rouge">bazel run @nodejs//:yarn_node_repositories</code> or <code class="language-plaintext highlighter-rouge">bazel run @nodejs//:npm_node_repositories install</code>.
If you use bazel-managed dependencies, you should omit this attribute.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="node_repositories-preserve_symlinks">preserve_symlinks</h4>
<p>(<em>Boolean</em>): Turn on –node_options=–preserve-symlinks for nodejs_binary and nodejs_test rules.</p>
<p>When this option is turned on, node will preserve the symlinked path for resolves instead of the default
behavior of resolving to the real path. This means that all required files must be in be included in your
runfiles as it prevents the default behavior of potentially resolving outside of the runfiles. For example,
all required files need to be included in your node_modules filegroup. This option is desirable as it gives
a stronger guarantee of hermeticity which is required for remote execution.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">True</code></p>
<h4 id="node_repositories-repo_mapping">repo_mapping</h4>
<p>(<em><a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -&gt; String</a>, mandatory</em>): A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.&lt;p&gt;For example, an entry <code class="language-plaintext highlighter-rouge">"@foo": "@bar"</code> declares that, for any time this repository depends on <code class="language-plaintext highlighter-rouge">@foo</code> (such as a dependency on <code class="language-plaintext highlighter-rouge">@foo//some:target</code>, it should actually resolve that dependency within globally-declared <code class="language-plaintext highlighter-rouge">@bar</code> (<code class="language-plaintext highlighter-rouge">@bar//some:target</code>).</p>
<h4 id="node_repositories-vendored_node">vendored_node</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">Label</a></em>): the local path to a pre-installed NodeJS runtime.</p>
<p>If set then also set node_version to the version that of node that is vendored.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">None</code></p>
<h4 id="node_repositories-vendored_yarn">vendored_yarn</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">Label</a></em>): the local path to a pre-installed yarn tool</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">None</code></p>
<h4 id="node_repositories-yarn_download_auth">yarn_download_auth</h4>
<p>(<em><a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -&gt; String</a></em>): auth to use for all url requests
Example: {“type”: “basic”, “login”: “<UserName>", "password": "<Password>" }</Password></UserName></p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">{}</code></p>
<h4 id="node_repositories-yarn_repositories">yarn_repositories</h4>
<p>(<em><a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -&gt; List of strings</a></em>): Custom list of yarn repositories to use.</p>
<p>Dictionary mapping Yarn versions to their corresponding (filename, strip_prefix, sha256) tuples.</p>
<p>By default, if this attribute has no items, we’ll use a list of all public NodeJS releases.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">{}</code></p>
<h4 id="node_repositories-yarn_urls">yarn_urls</h4>
<p>(<em>List of strings</em>): custom list of URLs to use to download Yarn</p>
<p>Each entry is a template, similar to the <code class="language-plaintext highlighter-rouge">node_urls</code> attribute, using <code class="language-plaintext highlighter-rouge">yarn_version</code> and <code class="language-plaintext highlighter-rouge">yarn_repositories</code> in the substitutions.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">["https://github.com/yarnpkg/yarn/releases/download/v{version}/{filename}"]</code></p>
<h4 id="node_repositories-yarn_version">yarn_version</h4>
<p>(<em>String</em>): the specific version of Yarn to install</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">"1.19.1"</code></p>
<h2 id="nodejs_binary">nodejs_binary</h2>
<p><strong>USAGE</strong></p>
<pre>
nodejs_binary(<a href="#nodejs_binary-name">name</a>, <a href="#nodejs_binary-chdir">chdir</a>, <a href="#nodejs_binary-configuration_env_vars">configuration_env_vars</a>, <a href="#nodejs_binary-data">data</a>, <a href="#nodejs_binary-default_env_vars">default_env_vars</a>, <a href="#nodejs_binary-entry_point">entry_point</a>,
<a href="#nodejs_binary-link_workspace_root">link_workspace_root</a>, <a href="#nodejs_binary-templated_args">templated_args</a>)
</pre>
<p>Runs some JavaScript code in NodeJS.</p>
<p><strong>ATTRIBUTES</strong></p>
<h4 id="nodejs_binary-name">name</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory</em>): A unique name for this target.</p>
<h4 id="nodejs_binary-chdir">chdir</h4>
<p>(<em>String</em>): 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.</p>
<p>To run in the directory containing the <code class="language-plaintext highlighter-rouge">nodejs_binary</code> / <code class="language-plaintext highlighter-rouge">nodejs_test</code>, use</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>chdir = package_name()
</code></pre></div></div>
<p>(or if you’re in a macro, use <code class="language-plaintext highlighter-rouge">native.package_name()</code>)</p>
<p>WARNING: this will affect other paths passed to the program, either as arguments or in configuration files,
which are workspace-relative.
You may need <code class="language-plaintext highlighter-rouge">../../</code> segments to re-relativize such paths to the new working directory.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">""</code></p>
<h4 id="nodejs_binary-configuration_env_vars">configuration_env_vars</h4>
<p>(<em>List of strings</em>): Pass these configuration environment variables to the resulting binary.
Chooses a subset of the configuration environment variables (taken from <code class="language-plaintext highlighter-rouge">ctx.var</code>), which also
includes anything specified via the –define flag.
Note, this can lead to different outputs produced by this rule.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="nodejs_binary-data">data</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a></em>): Runtime dependencies which may be loaded during execution.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="nodejs_binary-default_env_vars">default_env_vars</h4>
<p>(<em>List of strings</em>): Default environment variables that are added to <code class="language-plaintext highlighter-rouge">configuration_env_vars</code>.</p>
<p>This is separate from the default of <code class="language-plaintext highlighter-rouge">configuration_env_vars</code> so that a user can set <code class="language-plaintext highlighter-rouge">configuration_env_vars</code>
without losing the defaults that should be set in most cases.</p>
<p>The set of default environment variables is:</p>
<ul>
<li><code class="language-plaintext highlighter-rouge">VERBOSE_LOGS</code>: use by some rules &amp; tools to turn on debug output in their logs</li>
<li><code class="language-plaintext highlighter-rouge">NODE_DEBUG</code>: used by node.js itself to print more logs</li>
<li><code class="language-plaintext highlighter-rouge">RUNFILES_LIB_DEBUG</code>: print diagnostic message from Bazel runfiles.bash helper</li>
</ul>
<p>Defaults to <code class="language-plaintext highlighter-rouge">["VERBOSE_LOGS", "NODE_DEBUG", "RUNFILES_LIB_DEBUG"]</code></p>
<h4 id="nodejs_binary-entry_point">entry_point</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>, mandatory</em>): The script which should be executed first, usually containing a main function.</p>
<p>If the entry JavaScript file belongs to the same package (as the BUILD file),
you can simply reference it by its relative name to the package directory:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">nodejs_binary</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"my_binary"</span><span class="p">,</span>
<span class="p">...</span>
<span class="n">entry_point</span> <span class="o">=</span> <span class="s">":file.js"</span><span class="p">,</span>
<span class="p">)</span>
</code></pre></div></div>
<p>You can specify the entry point as a typescript file so long as you also include
the ts_library target in data:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">ts_library</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"main"</span><span class="p">,</span>
<span class="n">srcs</span> <span class="o">=</span> <span class="p">[</span><span class="s">"main.ts"</span><span class="p">],</span>
<span class="p">)</span>
<span class="n">nodejs_binary</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"bin"</span><span class="p">,</span>
<span class="n">data</span> <span class="o">=</span> <span class="p">[</span><span class="s">":main"</span><span class="p">]</span>
<span class="n">entry_point</span> <span class="o">=</span> <span class="s">":main.ts"</span><span class="p">,</span>
<span class="p">)</span>
</code></pre></div></div>
<p>The rule will use the corresponding <code class="language-plaintext highlighter-rouge">.js</code> output of the ts_library rule as the entry point.</p>
<p>If the entry point target is a rule, it should produce a single JavaScript entry file that will be passed to the nodejs_binary rule.
For example:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">filegroup</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"entry_file"</span><span class="p">,</span>
<span class="n">srcs</span> <span class="o">=</span> <span class="p">[</span><span class="s">"main.js"</span><span class="p">],</span>
<span class="p">)</span>
<span class="n">nodejs_binary</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"my_binary"</span><span class="p">,</span>
<span class="n">entry_point</span> <span class="o">=</span> <span class="s">":entry_file"</span><span class="p">,</span>
<span class="p">)</span>
</code></pre></div></div>
<p>The entry_point can also be a label in another workspace:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">nodejs_binary</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"history-server"</span><span class="p">,</span>
<span class="n">entry_point</span> <span class="o">=</span> <span class="s">"@npm//:node_modules/history-server/modules/cli.js"</span><span class="p">,</span>
<span class="n">data</span> <span class="o">=</span> <span class="p">[</span><span class="s">"@npm//history-server"</span><span class="p">],</span>
<span class="p">)</span>
</code></pre></div></div>
<h4 id="nodejs_binary-link_workspace_root">link_workspace_root</h4>
<p>(<em>Boolean</em>): Link the workspace root to the bin_dir to support absolute requires like ‘my_wksp/path/to/file’.
If source files need to be required then they can be copied to the bin_dir with copy_to_bin.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">False</code></p>
<h4 id="nodejs_binary-templated_args">templated_args</h4>
<p>(<em>List of strings</em>): Arguments which are passed to every execution of the program.
To pass a node startup option, prepend it with <code class="language-plaintext highlighter-rouge">--node_options=</code>, e.g.
<code class="language-plaintext highlighter-rouge">--node_options=--preserve-symlinks</code>.</p>
<p>Subject to ‘Make variable’ substitution. See https://docs.bazel.build/versions/master/be/make-variables.html.</p>
<ol>
<li>Subject to predefined source/output path variables substitutions.</li>
</ol>
<p>The predefined variables <code class="language-plaintext highlighter-rouge">execpath</code>, <code class="language-plaintext highlighter-rouge">execpaths</code>, <code class="language-plaintext highlighter-rouge">rootpath</code>, <code class="language-plaintext highlighter-rouge">rootpaths</code>, <code class="language-plaintext highlighter-rouge">location</code>, and <code class="language-plaintext highlighter-rouge">locations</code> take
label parameters (e.g. <code class="language-plaintext highlighter-rouge">$(execpath //foo:bar)</code>) and substitute the file paths denoted by that label.</p>
<p>See https://docs.bazel.build/versions/master/be/make-variables.html#predefined_label_variables for more info.</p>
<p>NB: This $(location) substition returns the manifest file path which differs from the *_binary &amp; *_test
args and genrule bazel substitions. This will be fixed in a future major release.
See docs string of <code class="language-plaintext highlighter-rouge">expand_location_into_runfiles</code> macro in <code class="language-plaintext highlighter-rouge">internal/common/expand_into_runfiles.bzl</code>
for more info.</p>
<p>The recommended approach is to now use <code class="language-plaintext highlighter-rouge">$(rootpath)</code> where you previously used $(location).</p>
<p>To get from a <code class="language-plaintext highlighter-rouge">$(rootpath)</code> to the absolute path that <code class="language-plaintext highlighter-rouge">$$(rlocation $(location))</code> returned you can either use
<code class="language-plaintext highlighter-rouge">$$(rlocation $(rootpath))</code> if you are in the <code class="language-plaintext highlighter-rouge">templated_args</code> of a <code class="language-plaintext highlighter-rouge">nodejs_binary</code> or <code class="language-plaintext highlighter-rouge">nodejs_test</code>:</p>
<p>BUILD.bazel:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">nodejs_test</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"my_test"</span><span class="p">,</span>
<span class="n">data</span> <span class="o">=</span> <span class="p">[</span><span class="s">":bootstrap.js"</span><span class="p">],</span>
<span class="n">templated_args</span> <span class="o">=</span> <span class="p">[</span><span class="s">"--node_options=--require=$$(rlocation $(rootpath :bootstrap.js))"</span><span class="p">],</span>
<span class="p">)</span>
</code></pre></div></div>
<p>or if you’re in the context of a .js script you can pass the $(rootpath) as an argument to the script
and use the javascript runfiles helper to resolve to the absolute path:</p>
<p>BUILD.bazel:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">nodejs_test</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"my_test"</span><span class="p">,</span>
<span class="n">data</span> <span class="o">=</span> <span class="p">[</span><span class="s">":some_file"</span><span class="p">],</span>
<span class="n">entry_point</span> <span class="o">=</span> <span class="s">":my_test.js"</span><span class="p">,</span>
<span class="n">templated_args</span> <span class="o">=</span> <span class="p">[</span><span class="s">"$(rootpath :some_file)"</span><span class="p">],</span>
<span class="p">)</span>
</code></pre></div></div>
<p>my_test.js</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">const</span> <span class="n">runfiles</span> <span class="o">=</span> <span class="n">require</span><span class="p">(</span><span class="n">process</span><span class="p">.</span><span class="n">env</span><span class="p">[</span><span class="s">'BAZEL_NODE_RUNFILES_HELPER'</span><span class="p">]);</span>
<span class="n">const</span> <span class="n">args</span> <span class="o">=</span> <span class="n">process</span><span class="p">.</span><span class="n">argv</span><span class="p">.</span><span class="nb">slice</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span>
<span class="n">const</span> <span class="n">some_file</span> <span class="o">=</span> <span class="n">runfiles</span><span class="p">.</span><span class="n">resolveWorkspaceRelative</span><span class="p">(</span><span class="n">args</span><span class="p">[</span><span class="mi">0</span><span class="p">]);</span>
</code></pre></div></div>
<p>NB: Bazel will error if it sees the single dollar sign $(rlocation path) in <code class="language-plaintext highlighter-rouge">templated_args</code> as it will try to
expand <code class="language-plaintext highlighter-rouge">$(rlocation)</code> since we now expand predefined &amp; custom “make” variables such as <code class="language-plaintext highlighter-rouge">$(COMPILATION_MODE)</code>,
<code class="language-plaintext highlighter-rouge">$(BINDIR)</code> &amp; <code class="language-plaintext highlighter-rouge">$(TARGET_CPU)</code> using <code class="language-plaintext highlighter-rouge">ctx.expand_make_variables</code>. See https://docs.bazel.build/versions/master/be/make-variables.html.</p>
<p>To prevent expansion of <code class="language-plaintext highlighter-rouge">$(rlocation)</code> write it as <code class="language-plaintext highlighter-rouge">$$(rlocation)</code>. Bazel understands <code class="language-plaintext highlighter-rouge">$$</code> to be
the string literal <code class="language-plaintext highlighter-rouge">$</code> and the expansion results in <code class="language-plaintext highlighter-rouge">$(rlocation)</code> being passed as an arg instead
of being expanded. <code class="language-plaintext highlighter-rouge">$(rlocation)</code> is then evaluated by the bash node launcher script and it calls
the <code class="language-plaintext highlighter-rouge">rlocation</code> function in the runfiles.bash helper. For example, the templated arg
<code class="language-plaintext highlighter-rouge">$$(rlocation $(rootpath //:some_file))</code> is expanded by Bazel to <code class="language-plaintext highlighter-rouge">$(rlocation ./some_file)</code> which
is then converted in bash to the absolute path of <code class="language-plaintext highlighter-rouge">//:some_file</code> in runfiles by the runfiles.bash helper
before being passed as an argument to the program.</p>
<p>NB: nodejs_binary and nodejs_test will preserve the legacy behavior of <code class="language-plaintext highlighter-rouge">$(rlocation)</code> so users don’t
need to update to <code class="language-plaintext highlighter-rouge">$$(rlocation)</code>. This may be changed in the future.</p>
<ol>
<li>Subject to predefined variables &amp; custom variable substitutions.</li>
</ol>
<p>Predefined “Make” variables such as $(COMPILATION_MODE) and $(TARGET_CPU) are expanded.
See https://docs.bazel.build/versions/master/be/make-variables.html#predefined_variables.</p>
<p>Custom variables are also expanded including variables set through the Bazel CLI with –define=SOME_VAR=SOME_VALUE.
See https://docs.bazel.build/versions/master/be/make-variables.html#custom_variables.</p>
<p>Predefined genrule variables are not supported in this context.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h2 id="nodejs_test">nodejs_test</h2>
<p><strong>USAGE</strong></p>
<pre>
nodejs_test(<a href="#nodejs_test-name">name</a>, <a href="#nodejs_test-chdir">chdir</a>, <a href="#nodejs_test-configuration_env_vars">configuration_env_vars</a>, <a href="#nodejs_test-data">data</a>, <a href="#nodejs_test-default_env_vars">default_env_vars</a>, <a href="#nodejs_test-entry_point">entry_point</a>,
<a href="#nodejs_test-expected_exit_code">expected_exit_code</a>, <a href="#nodejs_test-link_workspace_root">link_workspace_root</a>, <a href="#nodejs_test-templated_args">templated_args</a>)
</pre>
<p>Identical to <code class="language-plaintext highlighter-rouge">nodejs_binary</code>, except this can be used with <code class="language-plaintext highlighter-rouge">bazel test</code> as well.
When the binary returns zero exit code, the test passes; otherwise it fails.</p>
<p><code class="language-plaintext highlighter-rouge">nodejs_test</code> is a convenient way to write a novel kind of test based on running
your own test runner. For example, the <code class="language-plaintext highlighter-rouge">ts-api-guardian</code> library has a way to
assert the public API of a TypeScript program, and uses <code class="language-plaintext highlighter-rouge">nodejs_test</code> here:
https://github.com/angular/angular/blob/master/tools/ts-api-guardian/index.bzl</p>
<p>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 <code class="language-plaintext highlighter-rouge">mocha_test</code>.
Some test runners like Karma and Jasmine have custom rules with added features, e.g. <code class="language-plaintext highlighter-rouge">jasmine_node_test</code>.</p>
<p>By default, Bazel runs tests with a working directory set to your workspace root.
Use the <code class="language-plaintext highlighter-rouge">chdir</code> attribute to change the working directory before the program starts.</p>
<p>To debug a Node.js test, we recommend saving a group of flags together in a “config”.
Put this in your <code class="language-plaintext highlighter-rouge">tools/bazel.rc</code> so it’s shared with your team:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># Enable debugging tests with --config=debug
</span><span class="n">test</span><span class="p">:</span><span class="n">debug</span> <span class="o">--</span><span class="n">test_arg</span><span class="o">=--</span><span class="n">node_options</span><span class="o">=--</span><span class="n">inspect</span><span class="o">-</span><span class="n">brk</span> <span class="o">--</span><span class="n">test_output</span><span class="o">=</span><span class="n">streamed</span> <span class="o">--</span><span class="n">test_strategy</span><span class="o">=</span><span class="n">exclusive</span> <span class="o">--</span><span class="n">test_timeout</span><span class="o">=</span><span class="mi">9999</span> <span class="o">--</span><span class="n">nocache_test_results</span>
</code></pre></div></div>
<p>Now you can add <code class="language-plaintext highlighter-rouge">--config=debug</code> to any <code class="language-plaintext highlighter-rouge">bazel test</code> command line.
The runtime will pause before executing the program, allowing you to connect a
remote debugger.</p>
<p><strong>ATTRIBUTES</strong></p>
<h4 id="nodejs_test-name">name</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory</em>): A unique name for this target.</p>
<h4 id="nodejs_test-chdir">chdir</h4>
<p>(<em>String</em>): 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.</p>
<p>To run in the directory containing the <code class="language-plaintext highlighter-rouge">nodejs_binary</code> / <code class="language-plaintext highlighter-rouge">nodejs_test</code>, use</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>chdir = package_name()
</code></pre></div></div>
<p>(or if you’re in a macro, use <code class="language-plaintext highlighter-rouge">native.package_name()</code>)</p>
<p>WARNING: this will affect other paths passed to the program, either as arguments or in configuration files,
which are workspace-relative.
You may need <code class="language-plaintext highlighter-rouge">../../</code> segments to re-relativize such paths to the new working directory.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">""</code></p>
<h4 id="nodejs_test-configuration_env_vars">configuration_env_vars</h4>
<p>(<em>List of strings</em>): Pass these configuration environment variables to the resulting binary.
Chooses a subset of the configuration environment variables (taken from <code class="language-plaintext highlighter-rouge">ctx.var</code>), which also
includes anything specified via the –define flag.
Note, this can lead to different outputs produced by this rule.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="nodejs_test-data">data</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a></em>): Runtime dependencies which may be loaded during execution.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="nodejs_test-default_env_vars">default_env_vars</h4>
<p>(<em>List of strings</em>): Default environment variables that are added to <code class="language-plaintext highlighter-rouge">configuration_env_vars</code>.</p>
<p>This is separate from the default of <code class="language-plaintext highlighter-rouge">configuration_env_vars</code> so that a user can set <code class="language-plaintext highlighter-rouge">configuration_env_vars</code>
without losing the defaults that should be set in most cases.</p>
<p>The set of default environment variables is:</p>
<ul>
<li><code class="language-plaintext highlighter-rouge">VERBOSE_LOGS</code>: use by some rules &amp; tools to turn on debug output in their logs</li>
<li><code class="language-plaintext highlighter-rouge">NODE_DEBUG</code>: used by node.js itself to print more logs</li>
<li><code class="language-plaintext highlighter-rouge">RUNFILES_LIB_DEBUG</code>: print diagnostic message from Bazel runfiles.bash helper</li>
</ul>
<p>Defaults to <code class="language-plaintext highlighter-rouge">["VERBOSE_LOGS", "NODE_DEBUG", "RUNFILES_LIB_DEBUG"]</code></p>
<h4 id="nodejs_test-entry_point">entry_point</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>, mandatory</em>): The script which should be executed first, usually containing a main function.</p>
<p>If the entry JavaScript file belongs to the same package (as the BUILD file),
you can simply reference it by its relative name to the package directory:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">nodejs_binary</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"my_binary"</span><span class="p">,</span>
<span class="p">...</span>
<span class="n">entry_point</span> <span class="o">=</span> <span class="s">":file.js"</span><span class="p">,</span>
<span class="p">)</span>
</code></pre></div></div>
<p>You can specify the entry point as a typescript file so long as you also include
the ts_library target in data:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">ts_library</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"main"</span><span class="p">,</span>
<span class="n">srcs</span> <span class="o">=</span> <span class="p">[</span><span class="s">"main.ts"</span><span class="p">],</span>
<span class="p">)</span>
<span class="n">nodejs_binary</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"bin"</span><span class="p">,</span>
<span class="n">data</span> <span class="o">=</span> <span class="p">[</span><span class="s">":main"</span><span class="p">]</span>
<span class="n">entry_point</span> <span class="o">=</span> <span class="s">":main.ts"</span><span class="p">,</span>
<span class="p">)</span>
</code></pre></div></div>
<p>The rule will use the corresponding <code class="language-plaintext highlighter-rouge">.js</code> output of the ts_library rule as the entry point.</p>
<p>If the entry point target is a rule, it should produce a single JavaScript entry file that will be passed to the nodejs_binary rule.
For example:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">filegroup</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"entry_file"</span><span class="p">,</span>
<span class="n">srcs</span> <span class="o">=</span> <span class="p">[</span><span class="s">"main.js"</span><span class="p">],</span>
<span class="p">)</span>
<span class="n">nodejs_binary</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"my_binary"</span><span class="p">,</span>
<span class="n">entry_point</span> <span class="o">=</span> <span class="s">":entry_file"</span><span class="p">,</span>
<span class="p">)</span>
</code></pre></div></div>
<p>The entry_point can also be a label in another workspace:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">nodejs_binary</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"history-server"</span><span class="p">,</span>
<span class="n">entry_point</span> <span class="o">=</span> <span class="s">"@npm//:node_modules/history-server/modules/cli.js"</span><span class="p">,</span>
<span class="n">data</span> <span class="o">=</span> <span class="p">[</span><span class="s">"@npm//history-server"</span><span class="p">],</span>
<span class="p">)</span>
</code></pre></div></div>
<h4 id="nodejs_test-expected_exit_code">expected_exit_code</h4>
<p>(<em>Integer</em>): The expected exit code for the test. Defaults to 0.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">0</code></p>
<h4 id="nodejs_test-link_workspace_root">link_workspace_root</h4>
<p>(<em>Boolean</em>): Link the workspace root to the bin_dir to support absolute requires like ‘my_wksp/path/to/file’.
If source files need to be required then they can be copied to the bin_dir with copy_to_bin.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">False</code></p>
<h4 id="nodejs_test-templated_args">templated_args</h4>
<p>(<em>List of strings</em>): Arguments which are passed to every execution of the program.
To pass a node startup option, prepend it with <code class="language-plaintext highlighter-rouge">--node_options=</code>, e.g.
<code class="language-plaintext highlighter-rouge">--node_options=--preserve-symlinks</code>.</p>
<p>Subject to ‘Make variable’ substitution. See https://docs.bazel.build/versions/master/be/make-variables.html.</p>
<ol>
<li>Subject to predefined source/output path variables substitutions.</li>
</ol>
<p>The predefined variables <code class="language-plaintext highlighter-rouge">execpath</code>, <code class="language-plaintext highlighter-rouge">execpaths</code>, <code class="language-plaintext highlighter-rouge">rootpath</code>, <code class="language-plaintext highlighter-rouge">rootpaths</code>, <code class="language-plaintext highlighter-rouge">location</code>, and <code class="language-plaintext highlighter-rouge">locations</code> take
label parameters (e.g. <code class="language-plaintext highlighter-rouge">$(execpath //foo:bar)</code>) and substitute the file paths denoted by that label.</p>
<p>See https://docs.bazel.build/versions/master/be/make-variables.html#predefined_label_variables for more info.</p>
<p>NB: This $(location) substition returns the manifest file path which differs from the *_binary &amp; *_test
args and genrule bazel substitions. This will be fixed in a future major release.
See docs string of <code class="language-plaintext highlighter-rouge">expand_location_into_runfiles</code> macro in <code class="language-plaintext highlighter-rouge">internal/common/expand_into_runfiles.bzl</code>
for more info.</p>
<p>The recommended approach is to now use <code class="language-plaintext highlighter-rouge">$(rootpath)</code> where you previously used $(location).</p>
<p>To get from a <code class="language-plaintext highlighter-rouge">$(rootpath)</code> to the absolute path that <code class="language-plaintext highlighter-rouge">$$(rlocation $(location))</code> returned you can either use
<code class="language-plaintext highlighter-rouge">$$(rlocation $(rootpath))</code> if you are in the <code class="language-plaintext highlighter-rouge">templated_args</code> of a <code class="language-plaintext highlighter-rouge">nodejs_binary</code> or <code class="language-plaintext highlighter-rouge">nodejs_test</code>:</p>
<p>BUILD.bazel:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">nodejs_test</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"my_test"</span><span class="p">,</span>
<span class="n">data</span> <span class="o">=</span> <span class="p">[</span><span class="s">":bootstrap.js"</span><span class="p">],</span>
<span class="n">templated_args</span> <span class="o">=</span> <span class="p">[</span><span class="s">"--node_options=--require=$$(rlocation $(rootpath :bootstrap.js))"</span><span class="p">],</span>
<span class="p">)</span>
</code></pre></div></div>
<p>or if you’re in the context of a .js script you can pass the $(rootpath) as an argument to the script
and use the javascript runfiles helper to resolve to the absolute path:</p>
<p>BUILD.bazel:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">nodejs_test</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"my_test"</span><span class="p">,</span>
<span class="n">data</span> <span class="o">=</span> <span class="p">[</span><span class="s">":some_file"</span><span class="p">],</span>
<span class="n">entry_point</span> <span class="o">=</span> <span class="s">":my_test.js"</span><span class="p">,</span>
<span class="n">templated_args</span> <span class="o">=</span> <span class="p">[</span><span class="s">"$(rootpath :some_file)"</span><span class="p">],</span>
<span class="p">)</span>
</code></pre></div></div>
<p>my_test.js</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">const</span> <span class="n">runfiles</span> <span class="o">=</span> <span class="n">require</span><span class="p">(</span><span class="n">process</span><span class="p">.</span><span class="n">env</span><span class="p">[</span><span class="s">'BAZEL_NODE_RUNFILES_HELPER'</span><span class="p">]);</span>
<span class="n">const</span> <span class="n">args</span> <span class="o">=</span> <span class="n">process</span><span class="p">.</span><span class="n">argv</span><span class="p">.</span><span class="nb">slice</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span>
<span class="n">const</span> <span class="n">some_file</span> <span class="o">=</span> <span class="n">runfiles</span><span class="p">.</span><span class="n">resolveWorkspaceRelative</span><span class="p">(</span><span class="n">args</span><span class="p">[</span><span class="mi">0</span><span class="p">]);</span>
</code></pre></div></div>
<p>NB: Bazel will error if it sees the single dollar sign $(rlocation path) in <code class="language-plaintext highlighter-rouge">templated_args</code> as it will try to
expand <code class="language-plaintext highlighter-rouge">$(rlocation)</code> since we now expand predefined &amp; custom “make” variables such as <code class="language-plaintext highlighter-rouge">$(COMPILATION_MODE)</code>,
<code class="language-plaintext highlighter-rouge">$(BINDIR)</code> &amp; <code class="language-plaintext highlighter-rouge">$(TARGET_CPU)</code> using <code class="language-plaintext highlighter-rouge">ctx.expand_make_variables</code>. See https://docs.bazel.build/versions/master/be/make-variables.html.</p>
<p>To prevent expansion of <code class="language-plaintext highlighter-rouge">$(rlocation)</code> write it as <code class="language-plaintext highlighter-rouge">$$(rlocation)</code>. Bazel understands <code class="language-plaintext highlighter-rouge">$$</code> to be
the string literal <code class="language-plaintext highlighter-rouge">$</code> and the expansion results in <code class="language-plaintext highlighter-rouge">$(rlocation)</code> being passed as an arg instead
of being expanded. <code class="language-plaintext highlighter-rouge">$(rlocation)</code> is then evaluated by the bash node launcher script and it calls
the <code class="language-plaintext highlighter-rouge">rlocation</code> function in the runfiles.bash helper. For example, the templated arg
<code class="language-plaintext highlighter-rouge">$$(rlocation $(rootpath //:some_file))</code> is expanded by Bazel to <code class="language-plaintext highlighter-rouge">$(rlocation ./some_file)</code> which
is then converted in bash to the absolute path of <code class="language-plaintext highlighter-rouge">//:some_file</code> in runfiles by the runfiles.bash helper
before being passed as an argument to the program.</p>
<p>NB: nodejs_binary and nodejs_test will preserve the legacy behavior of <code class="language-plaintext highlighter-rouge">$(rlocation)</code> so users don’t
need to update to <code class="language-plaintext highlighter-rouge">$$(rlocation)</code>. This may be changed in the future.</p>
<ol>
<li>Subject to predefined variables &amp; custom variable substitutions.</li>
</ol>
<p>Predefined “Make” variables such as $(COMPILATION_MODE) and $(TARGET_CPU) are expanded.
See https://docs.bazel.build/versions/master/be/make-variables.html#predefined_variables.</p>
<p>Custom variables are also expanded including variables set through the Bazel CLI with –define=SOME_VAR=SOME_VALUE.
See https://docs.bazel.build/versions/master/be/make-variables.html#custom_variables.</p>
<p>Predefined genrule variables are not supported in this context.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h2 id="npm_install">npm_install</h2>
<p><strong>USAGE</strong></p>
<pre>
npm_install(<a href="#npm_install-name">name</a>, <a href="#npm_install-args">args</a>, <a href="#npm_install-data">data</a>, <a href="#npm_install-environment">environment</a>, <a href="#npm_install-included_files">included_files</a>, <a href="#npm_install-manual_build_file_contents">manual_build_file_contents</a>, <a href="#npm_install-npm_command">npm_command</a>,
<a href="#npm_install-package_json">package_json</a>, <a href="#npm_install-package_lock_json">package_lock_json</a>, <a href="#npm_install-package_path">package_path</a>, <a href="#npm_install-quiet">quiet</a>, <a href="#npm_install-repo_mapping">repo_mapping</a>, <a href="#npm_install-strict_visibility">strict_visibility</a>,
<a href="#npm_install-symlink_node_modules">symlink_node_modules</a>, <a href="#npm_install-timeout">timeout</a>)
</pre>
<p>Runs npm install during workspace setup.</p>
<p>This rule will set the environment variable <code class="language-plaintext highlighter-rouge">BAZEL_NPM_INSTALL</code> 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 <code class="language-plaintext highlighter-rouge">npm_install</code> repository rule.</p>
<p><strong>LOCAL MODULES WITH THE NEED TO BE USED BOTH INSIDE AND OUTSIDE BAZEL</strong></p>
<p>When using a monorepo it’s common to have modules that we want to use locally and
publish to an external package repository. This can be achieved using a <code class="language-plaintext highlighter-rouge">js_library</code> rule
with a <code class="language-plaintext highlighter-rouge">package_name</code> attribute defined inside the local package <code class="language-plaintext highlighter-rouge">BUILD</code> file. However,
if the project relies on the local package dependency with <code class="language-plaintext highlighter-rouge">file:</code>, this could introduce a
race condition with the <code class="language-plaintext highlighter-rouge">npm_install</code> rule.</p>
<p>In order to overcome it, a link will be created to the package <code class="language-plaintext highlighter-rouge">BUILD</code> file from the
npm external Bazel repository, which require us to complete a last step which is writing
the expected targets on that same <code class="language-plaintext highlighter-rouge">BUILD</code> file to be later used by the <code class="language-plaintext highlighter-rouge">npm_install</code>
rule, which are: <code class="language-plaintext highlighter-rouge">&lt;package_name__files&gt;</code>, <code class="language-plaintext highlighter-rouge">&lt;package_name__nested_node_modules&gt;</code>,
<code class="language-plaintext highlighter-rouge">&lt;package_name__contents&gt;</code>, <code class="language-plaintext highlighter-rouge">&lt;package_name__typings&gt;</code> and the last
one just <code class="language-plaintext highlighter-rouge">&lt;package_name&gt;</code>.</p>
<p>If you doubt what those targets should look like, check the
generated <code class="language-plaintext highlighter-rouge">BUILD</code> file for a given node module.</p>
<p><strong>ATTRIBUTES</strong></p>
<h4 id="npm_install-name">name</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory</em>): A unique name for this repository.</p>
<h4 id="npm_install-args">args</h4>
<p>(<em>List of strings</em>): Arguments passed to npm install.</p>
<p>See npm CLI docs https://docs.npmjs.com/cli/install.html for complete list of supported arguments.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="npm_install-data">data</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a></em>): Data files required by this rule.</p>
<p>If symlink_node_modules is True, this attribute is optional since the package manager
will run in your workspace folder. It is recommended, however, that all files that the
package manager depends on, such as <code class="language-plaintext highlighter-rouge">.rc</code> files or files used in <code class="language-plaintext highlighter-rouge">postinstall</code>, are added
symlink_node_modules is True so that the repository rule is rerun when any of these files
change.</p>
<p>If symlink_node_modules is False, the package manager is run in the bazel external
repository so all files that the package manager depends on must be listed.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="npm_install-environment">environment</h4>
<p>(<em><a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -&gt; String</a></em>): Environment variables to set before calling the package manager.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">{}</code></p>
<h4 id="npm_install-included_files">included_files</h4>
<p>(<em>List of strings</em>): List of file extensions to be included in the npm package targets.</p>
<p>For example, [“.js”, “.d.ts”, “.proto”, “.json”, “”].</p>
<p>This option is useful to limit the number of files that are inputs
to actions that depend on npm package targets. See
https://github.com/bazelbuild/bazel/issues/5153.</p>
<p>If set to an empty list then all files are included in the package targets.
If set to a list of extensions, only files with matching extensions are
included in the package targets. An empty string in the list is a special
string that denotes that files with no extensions such as <code class="language-plaintext highlighter-rouge">README</code> should
be included in the package targets.</p>
<p>This attribute applies to both the coarse <code class="language-plaintext highlighter-rouge">@wksp//:node_modules</code> target
as well as the fine grained targets such as <code class="language-plaintext highlighter-rouge">@wksp//foo</code>.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="npm_install-manual_build_file_contents">manual_build_file_contents</h4>
<p>(<em>String</em>): Experimental attribute that can be used to override the generated BUILD.bazel file and set its contents manually.</p>
<p>Can be used to work-around a bazel performance issue if the
default <code class="language-plaintext highlighter-rouge">@wksp//:node_modules</code> target has too many files in it.
See https://github.com/bazelbuild/bazel/issues/5153. If
you are running into performance issues due to a large
node_modules target it is recommended to switch to using
fine grained npm dependencies.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">""</code></p>
<h4 id="npm_install-npm_command">npm_command</h4>
<p>(<em>String</em>): The npm command to run, to install dependencies.</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code> See npm docs &lt;https://docs.npmjs.com/cli/v6/commands&gt;
In particular, for "ci" it says:
&gt; If dependencies in the package lock do not match those in package.json, npm ci will exit with an error, instead of updating the package lock.
</code></pre></div></div>
<p>Defaults to <code class="language-plaintext highlighter-rouge">"ci"</code></p>
<h4 id="npm_install-package_json">package_json</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>, mandatory</em>)</p>
<h4 id="npm_install-package_lock_json">package_lock_json</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>, mandatory</em>)</p>
<h4 id="npm_install-package_path">package_path</h4>
<p>(<em>String</em>): If set, link the 3rd party node_modules dependencies under the package path specified.</p>
<p>In most cases, this should be the directory of the package.json file so that the linker links the node_modules
in the same location they are found in the source tree. In a future release, this will default to the package.json
directory. This is planned for 4.0: https://github.com/bazelbuild/rules_nodejs/issues/2451</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">""</code></p>
<h4 id="npm_install-quiet">quiet</h4>
<p>(<em>Boolean</em>): If stdout and stderr should be printed to the terminal.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">True</code></p>
<h4 id="npm_install-repo_mapping">repo_mapping</h4>
<p>(<em><a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -&gt; String</a>, mandatory</em>): A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.&lt;p&gt;For example, an entry <code class="language-plaintext highlighter-rouge">"@foo": "@bar"</code> declares that, for any time this repository depends on <code class="language-plaintext highlighter-rouge">@foo</code> (such as a dependency on <code class="language-plaintext highlighter-rouge">@foo//some:target</code>, it should actually resolve that dependency within globally-declared <code class="language-plaintext highlighter-rouge">@bar</code> (<code class="language-plaintext highlighter-rouge">@bar//some:target</code>).</p>
<h4 id="npm_install-strict_visibility">strict_visibility</h4>
<p>(<em>Boolean</em>): Turn on stricter visibility for generated BUILD.bazel files</p>
<p>When enabled, only dependencies within the given <code class="language-plaintext highlighter-rouge">package.json</code> file are given public visibility.
All transitive dependencies are given limited visibility, enforcing that all direct dependencies are
listed in the <code class="language-plaintext highlighter-rouge">package.json</code> file.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">True</code></p>
<h4 id="npm_install-symlink_node_modules">symlink_node_modules</h4>
<p>(<em>Boolean</em>): Turn symlinking of node_modules on</p>
<p>This requires the use of Bazel 0.26.0 and the experimental
managed_directories feature.</p>
<p>When true, the package manager will run in the package.json folder
and the resulting node_modules folder will be symlinked into the
external repository create by this rule.</p>
<p>When false, the package manager will run in the external repository
created by this rule and any files other than the package.json file and
the lock file that are required for it to run should be listed in the
data attribute.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">True</code></p>
<h4 id="npm_install-timeout">timeout</h4>
<p>(<em>Integer</em>): Maximum duration of the package manager execution in seconds.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">3600</code></p>
<h2 id="pkg_npm">pkg_npm</h2>
<p><strong>USAGE</strong></p>
<pre>
pkg_npm(<a href="#pkg_npm-name">name</a>, <a href="#pkg_npm-deps">deps</a>, <a href="#pkg_npm-nested_packages">nested_packages</a>, <a href="#pkg_npm-node_context_data">node_context_data</a>, <a href="#pkg_npm-package_name">package_name</a>, <a href="#pkg_npm-srcs">srcs</a>, <a href="#pkg_npm-substitutions">substitutions</a>, <a href="#pkg_npm-tgz">tgz</a>,
<a href="#pkg_npm-vendor_external">vendor_external</a>)
</pre>
<p>The pkg_npm rule creates a directory containing a publishable npm artifact.</p>
<p>Example:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">load</span><span class="p">(</span><span class="s">"@build_bazel_rules_nodejs//:index.bzl"</span><span class="p">,</span> <span class="s">"pkg_npm"</span><span class="p">)</span>
<span class="n">pkg_npm</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"my_package"</span><span class="p">,</span>
<span class="n">srcs</span> <span class="o">=</span> <span class="p">[</span><span class="s">"package.json"</span><span class="p">],</span>
<span class="n">deps</span> <span class="o">=</span> <span class="p">[</span><span class="s">":my_typescript_lib"</span><span class="p">],</span>
<span class="n">substitutions</span> <span class="o">=</span> <span class="p">{</span><span class="s">"//internal/"</span><span class="p">:</span> <span class="s">"//"</span><span class="p">},</span>
<span class="p">)</span>
</code></pre></div></div>
<p>You can use a pair of <code class="language-plaintext highlighter-rouge">// BEGIN-INTERNAL ... // END-INTERNAL</code> comments to mark regions of files that should be elided during publishing.
For example:</p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">function</span> <span class="nx">doThing</span><span class="p">()</span> <span class="p">{</span>
<span class="c1">// BEGIN-INTERNAL</span>
<span class="c1">// This is a secret internal-only comment</span>
<span class="nx">doInternalOnlyThing</span><span class="p">();</span>
<span class="c1">// END-INTERNAL</span>
<span class="p">}</span>
</code></pre></div></div>
<p>With the Bazel stamping feature, pkg_npm will replace any placeholder version in your package with the actual version control tag.
See the <a href="https://github.com/bazelbuild/rules_nodejs/blob/master/docs/index.md#stamping">stamping documentation</a></p>
<p>Usage:</p>
<p><code class="language-plaintext highlighter-rouge">pkg_npm</code> yields four labels. Build the package directory using the default label:</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span>bazel build :my_package
Target //:my_package up-to-date:
bazel-out/fastbuild/bin/my_package
<span class="nv">$ </span><span class="nb">ls</span> <span class="nt">-R</span> bazel-out/fastbuild/bin/my_package
</code></pre></div></div>
<p>Dry-run of publishing to npm, calling <code class="language-plaintext highlighter-rouge">npm pack</code> (it builds the package first if needed):</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span>bazel run :my_package.pack
INFO: Running <span class="nb">command </span>line: bazel-out/fastbuild/bin/my_package.pack
my-package-name-1.2.3.tgz
<span class="nv">$ </span><span class="nb">tar</span> <span class="nt">-tzf</span> my-package-name-1.2.3.tgz
</code></pre></div></div>
<p>Actually publish the package with <code class="language-plaintext highlighter-rouge">npm publish</code> (also builds first):</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># Check login credentials</span>
<span class="nv">$ </span>bazel run @nodejs//:npm_node_repositories <span class="nb">who</span>
<span class="c"># Publishes the package</span>
<span class="nv">$ </span>bazel run :my_package.publish
</code></pre></div></div>
<p>You can pass arguments to npm by escaping them from Bazel using a double-hyphen, for example:</p>
<p><code class="language-plaintext highlighter-rouge">bazel run my_package.publish -- --tag=next</code></p>
<p>It is also possible to use the resulting tar file file from the <code class="language-plaintext highlighter-rouge">.pack</code> as an action input via the <code class="language-plaintext highlighter-rouge">.tar</code> label.
To make use of this label, the <code class="language-plaintext highlighter-rouge">tgz</code> attribute must be set, and the generating <code class="language-plaintext highlighter-rouge">pkg_npm</code> rule must have a valid <code class="language-plaintext highlighter-rouge">package.json</code> file
as part of its sources:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">pkg_npm</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"my_package"</span><span class="p">,</span>
<span class="n">srcs</span> <span class="o">=</span> <span class="p">[</span><span class="s">"package.json"</span><span class="p">],</span>
<span class="n">deps</span> <span class="o">=</span> <span class="p">[</span><span class="s">":my_typescript_lib"</span><span class="p">],</span>
<span class="n">tgz</span> <span class="o">=</span> <span class="s">"my_package.tgz"</span><span class="p">,</span>
<span class="p">)</span>
<span class="n">my_rule</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"foo"</span><span class="p">,</span>
<span class="n">srcs</span> <span class="o">=</span> <span class="p">[</span>
<span class="s">"//:my_package.tar"</span><span class="p">,</span>
<span class="p">],</span>
<span class="p">)</span>
</code></pre></div></div>
<p><strong>ATTRIBUTES</strong></p>
<h4 id="pkg_npm-name">name</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory</em>): A unique name for this target.</p>
<h4 id="pkg_npm-deps">deps</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a></em>): Other targets which produce files that should be included in the package, such as <code class="language-plaintext highlighter-rouge">rollup_bundle</code></p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="pkg_npm-nested_packages">nested_packages</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a></em>): Other pkg_npm rules whose content is copied into this package.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="pkg_npm-node_context_data">node_context_data</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">Label</a></em>): Provides info about the build context, such as stamping.</p>
<p>By default it reads from the bazel command line, such as the <code class="language-plaintext highlighter-rouge">--stamp</code> argument.
Use this to override values for this target, such as enabling or disabling stamping.
You can use the <code class="language-plaintext highlighter-rouge">node_context_data</code> rule in <code class="language-plaintext highlighter-rouge">@build_bazel_rules_nodejs//internal/node:context.bzl</code>
to create a NodeContextInfo. The dependencies of this attribute must provide: NodeContextInfo</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">@build_bazel_rules_nodejs//internal:node_context_data</code></p>
<h4 id="pkg_npm-package_name">package_name</h4>
<p>(<em>String</em>): Optional package_name that this npm package may be imported as.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">""</code></p>
<h4 id="pkg_npm-srcs">srcs</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a></em>): Files inside this directory which are simply copied into the package.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="pkg_npm-substitutions">substitutions</h4>
<p>(<em><a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -&gt; String</a></em>): Key-value pairs which are replaced in all the files while building the package.</p>
<p>You can use values from the workspace status command using curly braces, for example
<code class="language-plaintext highlighter-rouge">{"0.0.0-PLACEHOLDER": "{STABLE_GIT_VERSION}"}</code>.</p>
<p>See the section on stamping in the <a href="stamping">README</a></p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">{}</code></p>
<h4 id="pkg_npm-tgz">tgz</h4>
<p>(<em>String</em>): If set, will create a <code class="language-plaintext highlighter-rouge">.tgz</code> file that can be used as an input to another rule, the tar will be given the name assigned to this attribute.</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code> NOTE: If this attribute is set, a valid `package.json` file must be included in the sources of this target
</code></pre></div></div>
<p>Defaults to <code class="language-plaintext highlighter-rouge">""</code></p>
<h4 id="pkg_npm-vendor_external">vendor_external</h4>
<p>(<em>List of strings</em>): External workspaces whose contents should be vendored into this workspace.
Avoids <code class="language-plaintext highlighter-rouge">external/foo</code> path segments in the resulting package.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h2 id="pkg_web">pkg_web</h2>
<p><strong>USAGE</strong></p>
<pre>
pkg_web(<a href="#pkg_web-name">name</a>, <a href="#pkg_web-additional_root_paths">additional_root_paths</a>, <a href="#pkg_web-node_context_data">node_context_data</a>, <a href="#pkg_web-srcs">srcs</a>, <a href="#pkg_web-substitutions">substitutions</a>)
</pre>
<p>Assembles a web application from source files.</p>
<p><strong>ATTRIBUTES</strong></p>
<h4 id="pkg_web-name">name</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory</em>): A unique name for this target.</p>
<h4 id="pkg_web-additional_root_paths">additional_root_paths</h4>
<p>(<em>List of strings</em>): Path prefixes to strip off all srcs, in addition to the current package. Longest wins.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="pkg_web-node_context_data">node_context_data</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">Label</a></em>): Provides info about the build context, such as stamping.</p>
<p>By default it reads from the bazel command line, such as the <code class="language-plaintext highlighter-rouge">--stamp</code> argument.
Use this to override values for this target, such as enabling or disabling stamping.
You can use the <code class="language-plaintext highlighter-rouge">node_context_data</code> rule in <code class="language-plaintext highlighter-rouge">@build_bazel_rules_nodejs//internal/node:context.bzl</code>
to create a NodeContextInfo. The dependencies of this attribute must provide: NodeContextInfo</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">@build_bazel_rules_nodejs//internal:node_context_data</code></p>
<h4 id="pkg_web-srcs">srcs</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a></em>): Files which should be copied into the package</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="pkg_web-substitutions">substitutions</h4>
<p>(<em><a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -&gt; String</a></em>): Key-value pairs which are replaced in all the files while building the package.</p>
<p>You can use values from the workspace status command using curly braces, for example
<code class="language-plaintext highlighter-rouge">{"0.0.0-PLACEHOLDER": "{STABLE_GIT_VERSION}"}</code>.
See the section on stamping in the README.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">{}</code></p>
<h2 id="yarn_install">yarn_install</h2>
<p><strong>USAGE</strong></p>
<pre>
yarn_install(<a href="#yarn_install-name">name</a>, <a href="#yarn_install-args">args</a>, <a href="#yarn_install-data">data</a>, <a href="#yarn_install-environment">environment</a>, <a href="#yarn_install-frozen_lockfile">frozen_lockfile</a>, <a href="#yarn_install-included_files">included_files</a>,
<a href="#yarn_install-manual_build_file_contents">manual_build_file_contents</a>, <a href="#yarn_install-package_json">package_json</a>, <a href="#yarn_install-package_path">package_path</a>, <a href="#yarn_install-quiet">quiet</a>, <a href="#yarn_install-repo_mapping">repo_mapping</a>,
<a href="#yarn_install-strict_visibility">strict_visibility</a>, <a href="#yarn_install-symlink_node_modules">symlink_node_modules</a>, <a href="#yarn_install-timeout">timeout</a>, <a href="#yarn_install-use_global_yarn_cache">use_global_yarn_cache</a>, <a href="#yarn_install-yarn_lock">yarn_lock</a>)
</pre>
<p>Runs yarn install during workspace setup.</p>
<p>This rule will set the environment variable <code class="language-plaintext highlighter-rouge">BAZEL_YARN_INSTALL</code> 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 <code class="language-plaintext highlighter-rouge">yarn_install</code> repository rule.</p>
<p><strong>LOCAL MODULES WITH THE NEED TO BE USED BOTH INSIDE AND OUTSIDE BAZEL</strong></p>
<p>When using a monorepo it’s common to have modules that we want to use locally and
publish to an external package repository. This can be achieved using a <code class="language-plaintext highlighter-rouge">js_library</code> rule
with a <code class="language-plaintext highlighter-rouge">package_name</code> attribute defined inside the local package <code class="language-plaintext highlighter-rouge">BUILD</code> file. However,
if the project relies on the local package dependency with <code class="language-plaintext highlighter-rouge">link:</code>, this could introduce a
race condition with the <code class="language-plaintext highlighter-rouge">yarn_install</code> rule.</p>
<p>In order to overcome it, a link will be created to the package <code class="language-plaintext highlighter-rouge">BUILD</code> file from the
npm external Bazel repository, which require us to complete a last step which is writing
the expected targets on that same <code class="language-plaintext highlighter-rouge">BUILD</code> file to be later used by the <code class="language-plaintext highlighter-rouge">yarn_install</code>
rule, which are: <code class="language-plaintext highlighter-rouge">&lt;package_name__files&gt;</code>, <code class="language-plaintext highlighter-rouge">&lt;package_name__nested_node_modules&gt;</code>,
<code class="language-plaintext highlighter-rouge">&lt;package_name__contents&gt;</code>, <code class="language-plaintext highlighter-rouge">&lt;package_name__typings&gt;</code> and the last
one just <code class="language-plaintext highlighter-rouge">&lt;package_name&gt;</code>.</p>
<p>If you doubt what those targets should look like, check the
generated <code class="language-plaintext highlighter-rouge">BUILD</code> file for a given node module.</p>
<p><strong>ATTRIBUTES</strong></p>
<h4 id="yarn_install-name">name</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory</em>): A unique name for this repository.</p>
<h4 id="yarn_install-args">args</h4>
<p>(<em>List of strings</em>): Arguments passed to yarn install.</p>
<p>See yarn CLI docs https://yarnpkg.com/en/docs/cli/install for complete list of supported arguments.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="yarn_install-data">data</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a></em>): Data files required by this rule.</p>
<p>If symlink_node_modules is True, this attribute is optional since the package manager
will run in your workspace folder. It is recommended, however, that all files that the
package manager depends on, such as <code class="language-plaintext highlighter-rouge">.rc</code> files or files used in <code class="language-plaintext highlighter-rouge">postinstall</code>, are added
symlink_node_modules is True so that the repository rule is rerun when any of these files
change.</p>
<p>If symlink_node_modules is False, the package manager is run in the bazel external
repository so all files that the package manager depends on must be listed.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="yarn_install-environment">environment</h4>
<p>(<em><a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -&gt; String</a></em>): Environment variables to set before calling the package manager.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">{}</code></p>
<h4 id="yarn_install-frozen_lockfile">frozen_lockfile</h4>
<p>(<em>Boolean</em>): Use the <code class="language-plaintext highlighter-rouge">--frozen-lockfile</code> flag for yarn.</p>
<p>Don’t generate a <code class="language-plaintext highlighter-rouge">yarn.lock</code> lockfile and fail if an update is needed.</p>
<p>This flag enables an exact install of the version that is specified in the <code class="language-plaintext highlighter-rouge">yarn.lock</code>
file. This helps to have reproducible builds across builds.</p>
<p>To update a dependency or install a new one run the <code class="language-plaintext highlighter-rouge">yarn install</code> command with the
vendored yarn binary. <code class="language-plaintext highlighter-rouge">bazel run @nodejs//:yarn install</code>. You can pass the options like
<code class="language-plaintext highlighter-rouge">bazel run @nodejs//:yarn install -- -D &lt;dep-name&gt;</code>.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">True</code></p>
<h4 id="yarn_install-included_files">included_files</h4>
<p>(<em>List of strings</em>): List of file extensions to be included in the npm package targets.</p>
<p>For example, [“.js”, “.d.ts”, “.proto”, “.json”, “”].</p>
<p>This option is useful to limit the number of files that are inputs
to actions that depend on npm package targets. See
https://github.com/bazelbuild/bazel/issues/5153.</p>
<p>If set to an empty list then all files are included in the package targets.
If set to a list of extensions, only files with matching extensions are
included in the package targets. An empty string in the list is a special
string that denotes that files with no extensions such as <code class="language-plaintext highlighter-rouge">README</code> should
be included in the package targets.</p>
<p>This attribute applies to both the coarse <code class="language-plaintext highlighter-rouge">@wksp//:node_modules</code> target
as well as the fine grained targets such as <code class="language-plaintext highlighter-rouge">@wksp//foo</code>.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="yarn_install-manual_build_file_contents">manual_build_file_contents</h4>
<p>(<em>String</em>): Experimental attribute that can be used to override the generated BUILD.bazel file and set its contents manually.</p>
<p>Can be used to work-around a bazel performance issue if the
default <code class="language-plaintext highlighter-rouge">@wksp//:node_modules</code> target has too many files in it.
See https://github.com/bazelbuild/bazel/issues/5153. If
you are running into performance issues due to a large
node_modules target it is recommended to switch to using
fine grained npm dependencies.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">""</code></p>
<h4 id="yarn_install-package_json">package_json</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>, mandatory</em>)</p>
<h4 id="yarn_install-package_path">package_path</h4>
<p>(<em>String</em>): If set, link the 3rd party node_modules dependencies under the package path specified.</p>
<p>In most cases, this should be the directory of the package.json file so that the linker links the node_modules
in the same location they are found in the source tree. In a future release, this will default to the package.json
directory. This is planned for 4.0: https://github.com/bazelbuild/rules_nodejs/issues/2451</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">""</code></p>
<h4 id="yarn_install-quiet">quiet</h4>
<p>(<em>Boolean</em>): If stdout and stderr should be printed to the terminal.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">True</code></p>
<h4 id="yarn_install-repo_mapping">repo_mapping</h4>
<p>(<em><a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -&gt; String</a>, mandatory</em>): A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.&lt;p&gt;For example, an entry <code class="language-plaintext highlighter-rouge">"@foo": "@bar"</code> declares that, for any time this repository depends on <code class="language-plaintext highlighter-rouge">@foo</code> (such as a dependency on <code class="language-plaintext highlighter-rouge">@foo//some:target</code>, it should actually resolve that dependency within globally-declared <code class="language-plaintext highlighter-rouge">@bar</code> (<code class="language-plaintext highlighter-rouge">@bar//some:target</code>).</p>
<h4 id="yarn_install-strict_visibility">strict_visibility</h4>
<p>(<em>Boolean</em>): Turn on stricter visibility for generated BUILD.bazel files</p>
<p>When enabled, only dependencies within the given <code class="language-plaintext highlighter-rouge">package.json</code> file are given public visibility.
All transitive dependencies are given limited visibility, enforcing that all direct dependencies are
listed in the <code class="language-plaintext highlighter-rouge">package.json</code> file.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">True</code></p>
<h4 id="yarn_install-symlink_node_modules">symlink_node_modules</h4>
<p>(<em>Boolean</em>): Turn symlinking of node_modules on</p>
<p>This requires the use of Bazel 0.26.0 and the experimental
managed_directories feature.</p>
<p>When true, the package manager will run in the package.json folder
and the resulting node_modules folder will be symlinked into the
external repository create by this rule.</p>
<p>When false, the package manager will run in the external repository
created by this rule and any files other than the package.json file and
the lock file that are required for it to run should be listed in the
data attribute.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">True</code></p>
<h4 id="yarn_install-timeout">timeout</h4>
<p>(<em>Integer</em>): Maximum duration of the package manager execution in seconds.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">3600</code></p>
<h4 id="yarn_install-use_global_yarn_cache">use_global_yarn_cache</h4>
<p>(<em>Boolean</em>): Use the global yarn cache on the system.</p>
<p>The cache lets you avoid downloading packages multiple times.
However, it can introduce non-hermeticity, and the yarn cache can
have bugs.</p>
<p>Disabling this attribute causes every run of yarn to have a unique
cache_directory.</p>
<p>If True, this rule will pass <code class="language-plaintext highlighter-rouge">--mutex network</code> to yarn to ensure that
the global cache can be shared by parallelized yarn_install rules.</p>
<p>If False, this rule will pass <code class="language-plaintext highlighter-rouge">--cache-folder /path/to/external/repository/__yarn_cache</code>
to yarn so that the local cache is contained within the external repository.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">True</code></p>
<h4 id="yarn_install-yarn_lock">yarn_lock</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>, mandatory</em>)</p>
<h2 id="check_bazel_version">check_bazel_version</h2>
<p><strong>USAGE</strong></p>
<pre>
check_bazel_version(<a href="#check_bazel_version-minimum_bazel_version">minimum_bazel_version</a>, <a href="#check_bazel_version-message">message</a>)
</pre>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Verify the users Bazel version is at least the given one.
</code></pre></div></div>
<p>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.</p>
<p>This should <em>not</em> be used in users WORKSPACE files. To locally pin your
Bazel version, just create the .bazelversion file in your workspace.</p>
<p><strong>PARAMETERS</strong></p>
<h4 id="check_bazel_version-minimum_bazel_version">minimum_bazel_version</h4>
<p>a string indicating the minimum version</p>
<h4 id="check_bazel_version-message">message</h4>
<p>optional string to print to your users, could be used to help them update</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">""</code></p>
<h2 id="copy_to_bin">copy_to_bin</h2>
<p><strong>USAGE</strong></p>
<pre>
copy_to_bin(<a href="#copy_to_bin-name">name</a>, <a href="#copy_to_bin-srcs">srcs</a>, <a href="#copy_to_bin-kwargs">kwargs</a>)
</pre>
<p>Copies a source file to bazel-bin at the same workspace-relative path.</p>
<p>e.g. <code class="language-plaintext highlighter-rouge">&lt;workspace_root&gt;/foo/bar/a.txt -&gt; &lt;bazel-bin&gt;/foo/bar/a.txt</code></p>
<p>This is useful to populate the output folder with all files needed at runtime, even
those which aren’t outputs of a Bazel rule.</p>
<p>This way you can run a binary in the output folder (execroot or runfiles_root)
without that program needing to rely on a runfiles helper library or be aware that
files are divided between the source tree and the output tree.</p>
<p><strong>PARAMETERS</strong></p>
<h4 id="copy_to_bin-name">name</h4>
<p>Name of the rule.</p>
<h4 id="copy_to_bin-srcs">srcs</h4>
<p>A List of Labels. File(s) to to copy.</p>
<h4 id="copy_to_bin-kwargs">kwargs</h4>
<p>further keyword arguments, e.g. <code class="language-plaintext highlighter-rouge">visibility</code></p>
<h2 id="generated_file_test">generated_file_test</h2>
<p><strong>USAGE</strong></p>
<pre>
generated_file_test(<a href="#generated_file_test-name">name</a>, <a href="#generated_file_test-generated">generated</a>, <a href="#generated_file_test-src">src</a>, <a href="#generated_file_test-substring_search">substring_search</a>, <a href="#generated_file_test-src_dbg">src_dbg</a>, <a href="#generated_file_test-kwargs">kwargs</a>)
</pre>
<p>Tests that a file generated by Bazel has identical content to a file in the workspace.</p>
<p>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.</p>
<p><strong>PARAMETERS</strong></p>
<h4 id="generated_file_test-name">name</h4>
<p>Name of the rule.</p>
<h4 id="generated_file_test-generated">generated</h4>
<p>a Label of the output file generated by another rule</p>
<h4 id="generated_file_test-src">src</h4>
<p>Label of the source file in the workspace</p>
<h4 id="generated_file_test-substring_search">substring_search</h4>
<p>When true, creates a test that will fail only if the golden file is not found
anywhere within the generated file. Note that the .update rule is not generated in substring mode.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">False</code></p>
<h4 id="generated_file_test-src_dbg">src_dbg</h4>
<p>if the build uses <code class="language-plaintext highlighter-rouge">--compilation_mode dbg</code> then some rules will produce different output.
In this case you can specify what the dbg version of the output should look like</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">None</code></p>
<h4 id="generated_file_test-kwargs">kwargs</h4>
<p>extra arguments passed to the underlying nodejs_test</p>
<h2 id="js_library">js_library</h2>
<p><strong>USAGE</strong></p>
<pre>
js_library(<a href="#js_library-name">name</a>, <a href="#js_library-srcs">srcs</a>, <a href="#js_library-package_name">package_name</a>, <a href="#js_library-deps">deps</a>, <a href="#js_library-kwargs">kwargs</a>)
</pre>
<p>Groups JavaScript code so that it can be depended on like an npm package.</p>
<p><code class="language-plaintext highlighter-rouge">js_library</code> 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 <code class="language-plaintext highlighter-rouge">filegroup</code>.
However it provides several Bazel “Providers” for interop with other rules.</p>
<blockquote>
<p>Compare this to <code class="language-plaintext highlighter-rouge">pkg_npm</code> 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 <code class="language-plaintext highlighter-rouge">pkg_npm</code> is intended to publish your code for external usage outside of Bazel, like
by publishing to npm or artifactory, while <code class="language-plaintext highlighter-rouge">js_library</code> is for internal dependencies within your repo.</p>
</blockquote>
<p><code class="language-plaintext highlighter-rouge">js_library</code> also copies any source files into the bazel-out folder.
This is the same behavior as the <code class="language-plaintext highlighter-rouge">copy_to_bin</code> rule.
By copying the complete package to the output tree, we ensure that the linker (our <code class="language-plaintext highlighter-rouge">npm link</code> 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.</p>
<h3 id="example">Example</h3>
<p>A typical example usage of <code class="language-plaintext highlighter-rouge">js_library</code> is to expose some sources with a package name:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">ts_project</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"compile_ts"</span><span class="p">,</span>
<span class="n">srcs</span> <span class="o">=</span> <span class="n">glob</span><span class="p">([</span><span class="s">"*.ts"</span><span class="p">]),</span>
<span class="p">)</span>
<span class="n">js_library</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"my_pkg"</span><span class="p">,</span>
<span class="c1"># Code that depends on this target can import from "@myco/mypkg"
</span> <span class="n">package_name</span> <span class="o">=</span> <span class="s">"@myco/mypkg"</span><span class="p">,</span>
<span class="c1"># Consumers might need fields like "main" or "typings"
</span> <span class="n">srcs</span> <span class="o">=</span> <span class="p">[</span><span class="s">"package.json"</span><span class="p">],</span>
<span class="c1"># The .js and .d.ts outputs from above will be part of the package
</span> <span class="n">deps</span> <span class="o">=</span> <span class="p">[</span><span class="s">":compile_ts"</span><span class="p">],</span>
<span class="p">)</span>
</code></pre></div></div>
<blockquote>
<p>To help work with “named AMD” modules as required by <code class="language-plaintext highlighter-rouge">concatjs_devserver</code> and other Google-style “concatjs” rules,
<code class="language-plaintext highlighter-rouge">js_library</code> 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.</p>
</blockquote>
<h3 id="outputs">Outputs</h3>
<p>Like all Bazel rules it produces a default output by providing <a href="https://docs.bazel.build/versions/master/skylark/lib/DefaultInfo.html">DefaultInfo</a>.
You’ll get these outputs if you include this in the <code class="language-plaintext highlighter-rouge">srcs</code> of a typical rule like <code class="language-plaintext highlighter-rouge">filegroup</code>,
and these will be the printed result when you <code class="language-plaintext highlighter-rouge">bazel build //some:js_library_target</code>.
The default outputs are all of:</p>
<ul>
<li><a href="https://docs.bazel.build/versions/master/skylark/lib/DefaultInfo.html">DefaultInfo</a> produced by targets in <code class="language-plaintext highlighter-rouge">deps</code></li>
<li>A copy of all sources (InputArtifacts from your source tree) in the bazel-out directory</li>
</ul>
<p>When there are TypeScript typings files, <code class="language-plaintext highlighter-rouge">js_library</code> provides <a href="#declarationinfo">DeclarationInfo</a>
so this target can be a dependency of a TypeScript rule. This includes any <code class="language-plaintext highlighter-rouge">.d.ts</code> files in <code class="language-plaintext highlighter-rouge">srcs</code> as well
as transitive ones from <code class="language-plaintext highlighter-rouge">deps</code>.
It will also provide <a href="https://docs.bazel.build/versions/master/skylark/lib/OutputGroupInfo.html">OutputGroupInfo</a> with a “types” field, so you can select the typings outputs with
<code class="language-plaintext highlighter-rouge">bazel build //some:js_library_target --output_groups=types</code> or with a <code class="language-plaintext highlighter-rouge">filegroup</code> rule using the
<a href="https://docs.bazel.build/versions/master/be/general.html#filegroup.output_group">output_group</a> attribute.</p>
<p>In order to work with the linker (similar to <code class="language-plaintext highlighter-rouge">npm link</code> for first-party monorepo deps), <code class="language-plaintext highlighter-rouge">js_library</code> provides
<a href="#linkablepackageinfo">LinkablePackageInfo</a> for use with our “linker” that makes this package importable.</p>
<p>It also provides:</p>
<ul>
<li><a href="#externalnpmpackageinfo">ExternalNpmPackageInfo</a> to interop with rules that expect third-party npm packages.</li>
<li><a href="#jsmoduleinfo">JSModuleInfo</a> so rules like bundlers can collect the transitive set of .js files</li>
<li><a href="#jsnamedmoduleinfo">JSNamedModuleInfo</a> for rules that expect named AMD or <code class="language-plaintext highlighter-rouge">goog.module</code> format JS</li>
</ul>
<p><strong>PARAMETERS</strong></p>
<h4 id="js_library-name">name</h4>
<p>a name for the target</p>
<h4 id="js_library-srcs">srcs</h4>
<p>the list of files that comprise the package</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="js_library-package_name">package_name</h4>
<p>the name it will be imported by. Should match the “name” field in the package.json file.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">None</code></p>
<h4 id="js_library-deps">deps</h4>
<p>other targets that provide JavaScript code</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="js_library-kwargs">kwargs</h4>
<p>used for undocumented legacy features</p>
<h2 id="npm_package_bin">npm_package_bin</h2>
<p><strong>USAGE</strong></p>
<pre>
npm_package_bin(<a href="#npm_package_bin-tool">tool</a>, <a href="#npm_package_bin-package">package</a>, <a href="#npm_package_bin-package_bin">package_bin</a>, <a href="#npm_package_bin-data">data</a>, <a href="#npm_package_bin-outs">outs</a>, <a href="#npm_package_bin-args">args</a>, <a href="#npm_package_bin-output_dir">output_dir</a>, <a href="#npm_package_bin-link_workspace_root">link_workspace_root</a>,
<a href="#npm_package_bin-chdir">chdir</a>, <a href="#npm_package_bin-kwargs">kwargs</a>)
</pre>
<p>Run an arbitrary npm package binary (e.g. a program under node_modules/.bin/*) under Bazel.</p>
<p>It must produce outputs. If you just want to run a program with <code class="language-plaintext highlighter-rouge">bazel run</code>, use the nodejs_binary rule.</p>
<p>This is like a genrule() except that it runs our launcher script that first
links the node_modules tree before running the program.</p>
<p>By default, Bazel runs actions with a working directory set to your workspace root.
Use the <code class="language-plaintext highlighter-rouge">chdir</code> attribute to change the working directory before the program runs.</p>
<p>This is a great candidate to wrap with a macro, as documented:
https://docs.bazel.build/versions/master/skylark/macros.html#full-example</p>
<p><strong>PARAMETERS</strong></p>
<h4 id="npm_package_bin-tool">tool</h4>
<p>a label for a binary to run, like <code class="language-plaintext highlighter-rouge">@npm//terser/bin:terser</code>. This is the longer form of package/package_bin.
Note that you can also refer to a binary in your local workspace.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">None</code></p>
<h4 id="npm_package_bin-package">package</h4>
<p>an npm package whose binary to run, like “terser”. Assumes your node_modules are installed in a workspace called “npm”</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">None</code></p>
<h4 id="npm_package_bin-package_bin">package_bin</h4>
<p>the “bin” entry from <code class="language-plaintext highlighter-rouge">package</code> that should be run. By default package_bin is the same string as <code class="language-plaintext highlighter-rouge">package</code></p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">None</code></p>
<h4 id="npm_package_bin-data">data</h4>
<p>similar to <a href="https://docs.bazel.build/versions/master/be/general.html#genrule.srcs">genrule.srcs</a>
may also include targets that produce or reference npm packages which are needed by the tool</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="npm_package_bin-outs">outs</h4>
<p>similar to <a href="https://docs.bazel.build/versions/master/be/general.html#genrule.outs">genrule.outs</a></p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="npm_package_bin-args">args</h4>
<p>Command-line arguments to the tool.</p>
<p>Subject to ‘Make variable’ substitution. See https://docs.bazel.build/versions/master/be/make-variables.html.</p>
<ol>
<li>Predefined source/output path substitions is applied first:</li>
</ol>
<p>See https://docs.bazel.build/versions/master/be/make-variables.html#predefined_label_variables.</p>
<p>Use $(execpath) $(execpaths) to expand labels to the execroot (where Bazel runs build actions).</p>
<p>Use $(rootpath) $(rootpaths) to expand labels to the runfiles path that a built binary can use
to find its dependencies.</p>
<p>Since npm_package_bin is used primarily for build actions, in most cases you’ll want to
use $(execpath) or $(execpaths) to expand locations.</p>
<p>Using $(location) and $(locations) expansions is not recommended as these are a synonyms
for either $(execpath) or $(rootpath) depending on the context.</p>
<ol>
<li>“Make” variables are expanded second:</li>
</ol>
<p>Predefined “Make” variables such as $(COMPILATION_MODE) and $(TARGET_CPU) are expanded.
See https://docs.bazel.build/versions/master/be/make-variables.html#predefined_variables.</p>
<p>Like genrule, you may also use some syntax sugar for locations.</p>
<ul>
<li><code class="language-plaintext highlighter-rouge">$@</code>: if you have only one output file, the location of the output</li>
<li><code class="language-plaintext highlighter-rouge">$(@D)</code>: The output directory. If output_dir=False and there is only one file name in outs, this expands to the directory
containing that file. If there are multiple files, this instead expands to the package’s root directory in the genfiles
tree, even if all generated files belong to the same subdirectory! If output_dir=True then this corresponds
to the output directory which is the $(RULEDIR)/{target_name}.</li>
<li><code class="language-plaintext highlighter-rouge">$(RULEDIR)</code>: the root output directory of the rule, corresponding with its package
(can be used with output_dir=True or False)</li>
</ul>
<p>See https://docs.bazel.build/versions/master/be/make-variables.html#predefined_genrule_variables.</p>
<p>Custom variables are also expanded including variables set through the Bazel CLI with –define=SOME_VAR=SOME_VALUE.
See https://docs.bazel.build/versions/master/be/make-variables.html#custom_variables.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="npm_package_bin-output_dir">output_dir</h4>
<p>set to True if you want the output to be a directory
Exactly one of <code class="language-plaintext highlighter-rouge">outs</code>, <code class="language-plaintext highlighter-rouge">output_dir</code> may be used.
If you output a directory, there can only be one output, which will be a directory named the same as the target.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">False</code></p>
<h4 id="npm_package_bin-link_workspace_root">link_workspace_root</h4>
<p>Link the workspace root to the bin_dir to support absolute requires like ‘my_wksp/path/to/file’.
If source files need to be required then they can be copied to the bin_dir with copy_to_bin.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">False</code></p>
<h4 id="npm_package_bin-chdir">chdir</h4>
<p>Working directory to run the binary or test in, relative to the workspace.</p>
<p>By default, Bazel always runs in the workspace root.</p>
<p>To run in the directory containing the <code class="language-plaintext highlighter-rouge">npm_package_bin</code> under the source tree, use
<code class="language-plaintext highlighter-rouge">chdir = package_name()</code>
(or if you’re in a macro, use <code class="language-plaintext highlighter-rouge">native.package_name()</code>).</p>
<p>To run in the output directory where the npm_package_bin writes outputs, use
<code class="language-plaintext highlighter-rouge">chdir = "$(RULEDIR)"</code></p>
<p>WARNING: this will affect other paths passed to the program, either as arguments or in configuration files,
which are workspace-relative.
You may need <code class="language-plaintext highlighter-rouge">../../</code> segments to re-relativize such paths to the new working directory.
In a <code class="language-plaintext highlighter-rouge">BUILD</code> file you could do something like this to point to the output path:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">_package_segments</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">package_name</span><span class="p">().</span><span class="n">split</span><span class="p">(</span><span class="s">"/"</span><span class="p">))</span>
<span class="n">npm_package_bin</span><span class="p">(</span>
<span class="p">...</span>
<span class="n">chdir</span> <span class="o">=</span> <span class="n">package_name</span><span class="p">(),</span>
<span class="c1"># ../.. segments to re-relative paths from the chdir back to workspace
</span> <span class="n">args</span> <span class="o">=</span> <span class="p">[</span><span class="s">"/"</span><span class="p">.</span><span class="n">join</span><span class="p">([</span><span class="s">".."</span><span class="p">]</span> <span class="o">*</span> <span class="n">_package_segments</span> <span class="o">+</span> <span class="p">[</span><span class="s">"$@"</span><span class="p">])],</span>
<span class="p">)</span>
</code></pre></div></div>
<p>Defaults to <code class="language-plaintext highlighter-rouge">None</code></p>
<h4 id="npm_package_bin-kwargs">kwargs</h4>
<p>additional undocumented keyword args</p>
<h2 id="params_file">params_file</h2>
<p><strong>USAGE</strong></p>
<pre>
params_file(<a href="#params_file-name">name</a>, <a href="#params_file-out">out</a>, <a href="#params_file-args">args</a>, <a href="#params_file-data">data</a>, <a href="#params_file-newline">newline</a>, <a href="#params_file-kwargs">kwargs</a>)
</pre>
<p>Generates a UTF-8 encoded params file from a list of arguments.</p>
<p>Handles variable substitutions for args.</p>
<p><strong>PARAMETERS</strong></p>
<h4 id="params_file-name">name</h4>
<p>Name of the rule.</p>
<h4 id="params_file-out">out</h4>
<p>Path of the output file, relative to this package.</p>
<h4 id="params_file-args">args</h4>
<p>Arguments to concatenate into a params file.</p>
<p>Subject to ‘Make variable’ substitution. See https://docs.bazel.build/versions/master/be/make-variables.html.</p>
<ol>
<li>Subject to predefined source/output path variables substitutions.</li>
</ol>
<p>The predefined variables <code class="language-plaintext highlighter-rouge">execpath</code>, <code class="language-plaintext highlighter-rouge">execpaths</code>, <code class="language-plaintext highlighter-rouge">rootpath</code>, <code class="language-plaintext highlighter-rouge">rootpaths</code>, <code class="language-plaintext highlighter-rouge">location</code>, and <code class="language-plaintext highlighter-rouge">locations</code> take
label parameters (e.g. <code class="language-plaintext highlighter-rouge">$(execpath //foo:bar)</code>) and substitute the file paths denoted by that label.</p>
<p>See https://docs.bazel.build/versions/master/be/make-variables.html#predefined_label_variables for more info.</p>
<p>NB: This $(location) substition returns the manifest file path which differs from the *_binary &amp; *_test
args and genrule bazel substitions. This will be fixed in a future major release.
See docs string of <code class="language-plaintext highlighter-rouge">expand_location_into_runfiles</code> macro in <code class="language-plaintext highlighter-rouge">internal/common/expand_into_runfiles.bzl</code>
for more info.</p>
<ol>
<li>Subject to predefined variables &amp; custom variable substitutions.</li>
</ol>
<p>Predefined “Make” variables such as $(COMPILATION_MODE) and $(TARGET_CPU) are expanded.
See https://docs.bazel.build/versions/master/be/make-variables.html#predefined_variables.</p>
<p>Custom variables are also expanded including variables set through the Bazel CLI with –define=SOME_VAR=SOME_VALUE.
See https://docs.bazel.build/versions/master/be/make-variables.html#custom_variables.</p>
<p>Predefined genrule variables are not supported in this context.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="params_file-data">data</h4>
<p>Data for $(location) expansions in args.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="params_file-newline">newline</h4>
<p>Line endings to use. One of [“auto”, “unix”, “windows”].</p>
<p>“auto” for platform-determined
“unix” for LF
“windows” for CRLF</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">"auto"</code></p>
<h4 id="params_file-kwargs">kwargs</h4>
<h2 id="declarationinfo">DeclarationInfo</h2>
<p><strong>USAGE</strong></p>
<pre>
DeclarationInfo(<a href="#DeclarationInfo-declarations">declarations</a>, <a href="#DeclarationInfo-transitive_declarations">transitive_declarations</a>, <a href="#DeclarationInfo-type_blacklisted_declarations">type_blacklisted_declarations</a>)
</pre>
<p>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.</p>
<p>Do not create DeclarationInfo instances directly, instead use the declaration_info factory function.</p>
<p>Note: historically this was a subset of the string-typed “typescript” provider.</p>
<p><strong>FIELDS</strong></p>
<h4 id="DeclarationInfo-declarations">declarations</h4>
<p>A depset of typings files produced by this rule</p>
<h4 id="DeclarationInfo-transitive_declarations">transitive_declarations</h4>
<p>A depset of typings files produced by this rule and all its transitive dependencies.
This prevents needing an aspect in rules that consume the typings, which improves performance.</p>
<h4 id="DeclarationInfo-type_blacklisted_declarations">type_blacklisted_declarations</h4>
<p>A depset of .d.ts files that we should not use to infer JSCompiler types (via tsickle)</p>
<h2 id="externalnpmpackageinfo">ExternalNpmPackageInfo</h2>
<p><strong>USAGE</strong></p>
<pre>
ExternalNpmPackageInfo(<a href="#ExternalNpmPackageInfo-direct_sources">direct_sources</a>, <a href="#ExternalNpmPackageInfo-path">path</a>, <a href="#ExternalNpmPackageInfo-sources">sources</a>, <a href="#ExternalNpmPackageInfo-workspace">workspace</a>)
</pre>
<p>Provides information about one or more external npm packages</p>
<p><strong>FIELDS</strong></p>
<h4 id="ExternalNpmPackageInfo-direct_sources">direct_sources</h4>
<p>Depset of direct source files in these external npm package(s)</p>
<h4 id="ExternalNpmPackageInfo-path">path</h4>
<p>The local workspace path that these external npm deps should be linked at. If empty, they will be linked at the root.</p>
<h4 id="ExternalNpmPackageInfo-sources">sources</h4>
<p>Depset of direct &amp; transitive source files in these external npm package(s) and transitive dependencies</p>
<h4 id="ExternalNpmPackageInfo-workspace">workspace</h4>
<p>The workspace name that these external npm package(s) are provided from</p>
<h2 id="jsecmascriptmoduleinfo">JSEcmaScriptModuleInfo</h2>
<p><strong>USAGE</strong></p>
<pre>
JSEcmaScriptModuleInfo(<a href="#JSEcmaScriptModuleInfo-direct_sources">direct_sources</a>, <a href="#JSEcmaScriptModuleInfo-sources">sources</a>)
</pre>
<p>JavaScript files (and sourcemaps) that are intended to be consumed by downstream tooling.</p>
<p>They should use modern syntax and ESModules.
These files should typically be named “foo.mjs”</p>
<p>Historical note: this was the typescript.es6_sources output</p>
<p><strong>FIELDS</strong></p>
<h4 id="JSEcmaScriptModuleInfo-direct_sources">direct_sources</h4>
<p>Depset of direct JavaScript files and sourcemaps</p>
<h4 id="JSEcmaScriptModuleInfo-sources">sources</h4>
<p>Depset of direct and transitive JavaScript files and sourcemaps</p>
<h2 id="jsmoduleinfo">JSModuleInfo</h2>
<p><strong>USAGE</strong></p>
<pre>
JSModuleInfo(<a href="#JSModuleInfo-direct_sources">direct_sources</a>, <a href="#JSModuleInfo-sources">sources</a>)
</pre>
<p>JavaScript files and sourcemaps.</p>
<p><strong>FIELDS</strong></p>
<h4 id="JSModuleInfo-direct_sources">direct_sources</h4>
<p>Depset of direct JavaScript files and sourcemaps</p>
<h4 id="JSModuleInfo-sources">sources</h4>
<p>Depset of direct and transitive JavaScript files and sourcemaps</p>
<h2 id="jsnamedmoduleinfo">JSNamedModuleInfo</h2>
<p><strong>USAGE</strong></p>
<pre>
JSNamedModuleInfo(<a href="#JSNamedModuleInfo-direct_sources">direct_sources</a>, <a href="#JSNamedModuleInfo-sources">sources</a>)
</pre>
<p>JavaScript files whose module name is self-contained.</p>
<p>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)</p>
<p>Historical note: this was the typescript.es5_sources output.</p>
<p><strong>FIELDS</strong></p>
<h4 id="JSNamedModuleInfo-direct_sources">direct_sources</h4>
<p>Depset of direct JavaScript files and sourcemaps</p>
<h4 id="JSNamedModuleInfo-sources">sources</h4>
<p>Depset of direct and transitive JavaScript files and sourcemaps</p>
<h2 id="linkablepackageinfo">LinkablePackageInfo</h2>
<p><strong>USAGE</strong></p>
<pre>
LinkablePackageInfo(<a href="#LinkablePackageInfo-files">files</a>, <a href="#LinkablePackageInfo-package_name">package_name</a>, <a href="#LinkablePackageInfo-path">path</a>, <a href="#LinkablePackageInfo-_tslibrary">_tslibrary</a>)
</pre>
<p>The LinkablePackageInfo provider provides information to the linker for linking pkg_npm built packages</p>
<p><strong>FIELDS</strong></p>
<h4 id="LinkablePackageInfo-files">files</h4>
<p>Depset of files in this package (must all be contained within path)</p>
<h4 id="LinkablePackageInfo-package_name">package_name</h4>
<p>The package name.</p>
<p>Should be the same as name field in the package’s package.json.</p>
<p>In the future, the linker may validate that the names match the name in a package.json file.</p>
<h4 id="LinkablePackageInfo-path">path</h4>
<p>The path to link to.</p>
<p>Path must be relative to execroot/wksp. It can either an output dir path such as,</p>
<p><code class="language-plaintext highlighter-rouge">bazel-out/&lt;platform&gt;-&lt;build&gt;/bin/path/to/package</code> or
<code class="language-plaintext highlighter-rouge">bazel-out/&lt;platform&gt;-&lt;build&gt;/bin/external/external_wksp&gt;/path/to/package</code></p>
<p>or a source file path such as,</p>
<p><code class="language-plaintext highlighter-rouge">path/to/package</code> or
<code class="language-plaintext highlighter-rouge">external/&lt;external_wksp&gt;/path/to/package</code></p>
<h4 id="LinkablePackageInfo-_tslibrary">_tslibrary</h4>
<p>For internal use only</p>
<h2 id="nodecontextinfo">NodeContextInfo</h2>
<p><strong>USAGE</strong></p>
<pre>
NodeContextInfo(<a href="#NodeContextInfo-stamp">stamp</a>)
</pre>
<p>Provides data about the build context, like config_setting’s</p>
<p><strong>FIELDS</strong></p>
<h4 id="NodeContextInfo-stamp">stamp</h4>
<p>If stamping is enabled</p>
<h2 id="noderuntimedepsinfo">NodeRuntimeDepsInfo</h2>
<p><strong>USAGE</strong></p>
<pre>
NodeRuntimeDepsInfo(<a href="#NodeRuntimeDepsInfo-deps">deps</a>, <a href="#NodeRuntimeDepsInfo-pkgs">pkgs</a>)
</pre>
<p>Stores runtime dependencies of a nodejs_binary or nodejs_test</p>
<p>These are files that need to be found by the node module resolver at runtime.</p>
<p>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.</p>
<p>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.</p>
<p><strong>FIELDS</strong></p>
<h4 id="NodeRuntimeDepsInfo-deps">deps</h4>
<p>depset of runtime dependency labels</p>
<h4 id="NodeRuntimeDepsInfo-pkgs">pkgs</h4>
<p>list of labels of packages that provide ExternalNpmPackageInfo</p>
<h2 id="npmpackageinfo">NpmPackageInfo</h2>
<p><strong>USAGE</strong></p>
<pre>
NpmPackageInfo(<a href="#NpmPackageInfo-direct_sources">direct_sources</a>, <a href="#NpmPackageInfo-path">path</a>, <a href="#NpmPackageInfo-sources">sources</a>, <a href="#NpmPackageInfo-workspace">workspace</a>)
</pre>
<p>Provides information about one or more external npm packages</p>
<p><strong>FIELDS</strong></p>
<h4 id="NpmPackageInfo-direct_sources">direct_sources</h4>
<p>Depset of direct source files in these external npm package(s)</p>
<h4 id="NpmPackageInfo-path">path</h4>
<p>The local workspace path that these external npm deps should be linked at. If empty, they will be linked at the root.</p>
<h4 id="NpmPackageInfo-sources">sources</h4>
<p>Depset of direct &amp; transitive source files in these external npm package(s) and transitive dependencies</p>
<h4 id="NpmPackageInfo-workspace">workspace</h4>
<p>The workspace name that these external npm package(s) are provided from</p>
<h2 id="declaration_info">declaration_info</h2>
<p><strong>USAGE</strong></p>
<pre>
declaration_info(<a href="#declaration_info-declarations">declarations</a>, <a href="#declaration_info-deps">deps</a>)
</pre>
<p>Constructs a DeclarationInfo including all transitive files needed to type-check from DeclarationInfo providers in a list of deps.</p>
<p><strong>PARAMETERS</strong></p>
<h4 id="declaration_info-declarations">declarations</h4>
<p>list of typings files</p>
<h4 id="declaration_info-deps">deps</h4>
<p>list of labels of dependencies where we should collect their DeclarationInfo to pass transitively</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h2 id="js_ecma_script_module_info">js_ecma_script_module_info</h2>
<p><strong>USAGE</strong></p>
<pre>
js_ecma_script_module_info(<a href="#js_ecma_script_module_info-sources">sources</a>, <a href="#js_ecma_script_module_info-deps">deps</a>)
</pre>
<p>Constructs a JSEcmaScriptModuleInfo including all transitive sources from JSEcmaScriptModuleInfo providers in a list of deps.</p>
<p>Returns a single JSEcmaScriptModuleInfo.</p>
<p><strong>PARAMETERS</strong></p>
<h4 id="js_ecma_script_module_info-sources">sources</h4>
<h4 id="js_ecma_script_module_info-deps">deps</h4>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h2 id="js_module_info">js_module_info</h2>
<p><strong>USAGE</strong></p>
<pre>
js_module_info(<a href="#js_module_info-sources">sources</a>, <a href="#js_module_info-deps">deps</a>)
</pre>
<p>Constructs a JSModuleInfo including all transitive sources from JSModuleInfo providers in a list of deps.</p>
<p>Returns a single JSModuleInfo.</p>
<p><strong>PARAMETERS</strong></p>
<h4 id="js_module_info-sources">sources</h4>
<h4 id="js_module_info-deps">deps</h4>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h2 id="js_named_module_info">js_named_module_info</h2>
<p><strong>USAGE</strong></p>
<pre>
js_named_module_info(<a href="#js_named_module_info-sources">sources</a>, <a href="#js_named_module_info-deps">deps</a>)
</pre>
<p>Constructs a JSNamedModuleInfo including all transitive sources from JSNamedModuleInfo providers in a list of deps.</p>
<p>Returns a single JSNamedModuleInfo.</p>
<p><strong>PARAMETERS</strong></p>
<h4 id="js_named_module_info-sources">sources</h4>
<h4 id="js_named_module_info-deps">deps</h4>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h2 id="run_node">run_node</h2>
<p><strong>USAGE</strong></p>
<pre>
run_node(<a href="#run_node-ctx">ctx</a>, <a href="#run_node-inputs">inputs</a>, <a href="#run_node-arguments">arguments</a>, <a href="#run_node-executable">executable</a>, <a href="#run_node-chdir">chdir</a>, <a href="#run_node-kwargs">kwargs</a>)
</pre>
<p>Helper to replace ctx.actions.run</p>
<p>This calls node programs with a node_modules directory in place</p>
<p><strong>PARAMETERS</strong></p>
<h4 id="run_node-ctx">ctx</h4>
<p>rule context from the calling rule implementation function</p>
<h4 id="run_node-inputs">inputs</h4>
<p>list or depset of inputs to the action</p>
<h4 id="run_node-arguments">arguments</h4>
<p>list or ctx.actions.Args object containing arguments to pass to the executable</p>
<h4 id="run_node-executable">executable</h4>
<p>stringy representation of the executable this action will run, eg eg. “my_executable” rather than ctx.executable.my_executable</p>
<h4 id="run_node-chdir">chdir</h4>
<p>directory we should change to be the working dir</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">None</code></p>
<h4 id="run_node-kwargs">kwargs</h4>
<p>all other args accepted by ctx.actions.run</p>
<h2 id="node_modules_aspect">node_modules_aspect</h2>
<p><strong>USAGE</strong></p>
<pre>
node_modules_aspect(<a href="#node_modules_aspect-name">name</a>)
</pre>
<p><strong>ASPECT ATTRIBUTES</strong></p>
<h4>deps</h4>
<p><strong>ATTRIBUTES</strong></p>
<h4 id="node_modules_aspect-name">name</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#name">Name</a>, {util.mandatoryString(name: “name”
doc_string: “A unique name for this target.”
type: NAME
mandatory: true
)}</em>)
A unique name for this target.</p>
</div>
</div>
<div class="col-md-2 sticky-sidebar">
<div class="right-sidebar">
<ul class="gh-links">
<li>
<i class="fa fa-github"></i>
<a href="https://github.com/bazelbuild/rules_nodejs/issues/new?title=Documentation issue: Built-ins&labels=question/docs">Create
issue</a>
</li>
</ul>
<ul class="section-nav">
<li class="toc-entry toc-h2"><a href="#node_repositories">node_repositories</a>
<ul>
<li class="toc-entry toc-h3"><a href="#simplest-usage">Simplest Usage</a></li>
<li class="toc-entry toc-h3"><a href="#forced-versions">Forced version(s)</a></li>
<li class="toc-entry toc-h3"><a href="#using-a-custom-version">Using a custom version</a></li>
<li class="toc-entry toc-h3"><a href="#using-a-local-version">Using a local version</a></li>
<li class="toc-entry toc-h3"><a href="#manual-install">Manual install</a></li>
</ul>
</li>
<li class="toc-entry toc-h2"><a href="#nodejs_binary">nodejs_binary</a></li>
<li class="toc-entry toc-h2"><a href="#nodejs_test">nodejs_test</a></li>
<li class="toc-entry toc-h2"><a href="#npm_install">npm_install</a></li>
<li class="toc-entry toc-h2"><a href="#pkg_npm">pkg_npm</a></li>
<li class="toc-entry toc-h2"><a href="#pkg_web">pkg_web</a></li>
<li class="toc-entry toc-h2"><a href="#yarn_install">yarn_install</a></li>
<li class="toc-entry toc-h2"><a href="#check_bazel_version">check_bazel_version</a></li>
<li class="toc-entry toc-h2"><a href="#copy_to_bin">copy_to_bin</a></li>
<li class="toc-entry toc-h2"><a href="#generated_file_test">generated_file_test</a></li>
<li class="toc-entry toc-h2"><a href="#js_library">js_library</a>
<ul>
<li class="toc-entry toc-h3"><a href="#example">Example</a></li>
<li class="toc-entry toc-h3"><a href="#outputs">Outputs</a></li>
</ul>
</li>
<li class="toc-entry toc-h2"><a href="#npm_package_bin">npm_package_bin</a></li>
<li class="toc-entry toc-h2"><a href="#params_file">params_file</a></li>
<li class="toc-entry toc-h2"><a href="#declarationinfo">DeclarationInfo</a></li>
<li class="toc-entry toc-h2"><a href="#externalnpmpackageinfo">ExternalNpmPackageInfo</a></li>
<li class="toc-entry toc-h2"><a href="#jsecmascriptmoduleinfo">JSEcmaScriptModuleInfo</a></li>
<li class="toc-entry toc-h2"><a href="#jsmoduleinfo">JSModuleInfo</a></li>
<li class="toc-entry toc-h2"><a href="#jsnamedmoduleinfo">JSNamedModuleInfo</a></li>
<li class="toc-entry toc-h2"><a href="#linkablepackageinfo">LinkablePackageInfo</a></li>
<li class="toc-entry toc-h2"><a href="#nodecontextinfo">NodeContextInfo</a></li>
<li class="toc-entry toc-h2"><a href="#noderuntimedepsinfo">NodeRuntimeDepsInfo</a></li>
<li class="toc-entry toc-h2"><a href="#npmpackageinfo">NpmPackageInfo</a></li>
<li class="toc-entry toc-h2"><a href="#declaration_info">declaration_info</a></li>
<li class="toc-entry toc-h2"><a href="#js_ecma_script_module_info">js_ecma_script_module_info</a></li>
<li class="toc-entry toc-h2"><a href="#js_module_info">js_module_info</a></li>
<li class="toc-entry toc-h2"><a href="#js_named_module_info">js_named_module_info</a></li>
<li class="toc-entry toc-h2"><a href="#run_node">run_node</a></li>
<li class="toc-entry toc-h2"><a href="#node_modules_aspect">node_modules_aspect</a></li>
</ul>
</div>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<div class="row">
<div class="col-lg-8">
<p class="text-muted">&copy; 2021 The rules_nodejs authors</p>
</div>
</div>
</div>
</footer>
<!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
<!-- Include all compiled plugins (below), or include individual files as needed -->
<script crossorigin="anonymous"
integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa"
src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"></script>
<!-- Anchor JS -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/anchor-js/3.2.0/anchor.min.js" type="text/javascript"></script>
<script>
// Automatically add anchors and links to all header elements that don't already have them.
anchors.options = { placement: 'left' };
anchors.add();
</script>
<script>
var shiftWindow = function () {
if (location.hash.length !== 0) {
window.scrollBy(0, -50);
}
};
window.addEventListener("hashchange", shiftWindow);
var highlightCurrentSidebarNav = function () {
var href = location.pathname;
var item = $('#sidebar-nav [href$="' + href + '"]');
if (item) {
var li = item.parent();
li.addClass("active");
if (li.parent() && li.parent().is("ul")) {
do {
var ul = li.parent();
if (ul.hasClass("collapse")) {
ul.collapse("show");
}
li = ul.parent();
} while (li && li.is("li"));
}
}
};
$(document).ready(function () {
// Scroll to anchor of location hash, adjusted for fixed navbar.
window.setTimeout(function () {
shiftWindow();
}, 1);
// Flip the caret when submenu toggles are clicked.
$(".sidebar-submenu").on("show.bs.collapse", function () {
var toggle = $('[href$="#' + $(this).attr('id') + '"]');
if (toggle) {
toggle.addClass("dropup");
}
});
$(".sidebar-submenu").on("hide.bs.collapse", function () {
var toggle = $('[href$="#' + $(this).attr('id') + '"]');
if (toggle) {
toggle.removeClass("dropup");
}
});
// Highlight the current page on the sidebar nav.
highlightCurrentSidebarNav();
});
</script>
</body>
</html>