Google Git
Sign in
pigweed/third_party/github/bazel-contrib/rules_nodejs/bd052d3cc1b9ea18b37fc0af510600a2bdc11082/./docs/node/node_repositories.html
blob: a15af6c0a2363c71cca53f78dd9b281ee5e6d0c6 [file] [log] [blame]
<!--
Documentation generated by Skydoc
-->
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width initial-scale=1" />
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>Install NodeJS & Yarn</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,600,700" type="text/css">
<link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
<link rel="stylesheet" href="https://code.getmdl.io/1.1.1/material.green-light_blue.min.css">
<script defer src="https://code.getmdl.io/1.1.1/material.min.js"></script>
<link rel="stylesheet" href="/rules_nodejs/main.css">
</head>
<body>
<div class="mdl-layout mdl-js-layout mdl-layout--fixed-drawer
mdl-layout--fixed-header">
<header class="mdl-layout__header">
<div class="mdl-layout__header-row">
<span class="mdl-layout-title">Install NodeJS & Yarn</span>
</div>
</header>
<div class="mdl-layout__drawer">
<span class="mdl-layout-title">Bazel</span>
<nav class="drawer-nav">
<ul class="drawer-nav">
<li><a href="/rules_nodejs/index.html">Overview</a></li>
<li>
<a href="/rules_nodejs/common/check_bazel_version.html">Check Bazel version</a>
<ul>
<li><a href="/rules_nodejs/common/check_bazel_version.html#overview">Overview</a></li>
</ul>
</li>
<li>
<a href="/rules_nodejs/history-server/history_server.html">Run history-server</a>
<ul>
</ul>
</li>
<li>
<a href="/rules_nodejs/http-server/http_server.html">Run http-server</a>
<ul>
</ul>
</li>
<li>
<a href="/rules_nodejs/jasmine_node_test/jasmine_node_test.html">NodeJS testing</a>
<ul>
<li><a href="/rules_nodejs/jasmine_node_test/jasmine_node_test.html#overview">Overview</a></li>
</ul>
</li>
<li>
<a href="/rules_nodejs/node/node.html">Executing programs</a>
<ul>
<li><a href="/rules_nodejs/node/node.html#overview">Overview</a></li>
<li>
<a href="/rules_nodejs/node/node.html#nodejs_binary">
nodejs_binary
</a>
</li>
<li>
<a href="/rules_nodejs/node/node.html#nodejs_test">
nodejs_test
</a>
</li>
</ul>
</li>
<li>
<a href="/rules_nodejs/node/node_repositories.html">Install NodeJS & Yarn</a>
<ul>
<li><a href="/rules_nodejs/node/node_repositories.html#overview">Overview</a></li>
</ul>
</li>
<li>
<a href="/rules_nodejs/npm_install/npm_install.html">Install npm packages</a>
<ul>
<li><a href="/rules_nodejs/npm_install/npm_install.html#overview">Overview</a></li>
</ul>
</li>
<li>
<a href="/rules_nodejs/npm_package/npm_package.html">npm packaging</a>
<ul>
<li><a href="/rules_nodejs/npm_package/npm_package.html#overview">Overview</a></li>
<li>
<a href="/rules_nodejs/npm_package/npm_package.html#npm_package">
npm_package
</a>
</li>
</ul>
</li>
<li>
<a href="/rules_nodejs/rollup/rollup_bundle.html">Rollup bundling</a>
<ul>
<li><a href="/rules_nodejs/rollup/rollup_bundle.html#overview">Overview</a></li>
<li>
<a href="/rules_nodejs/rollup/rollup_bundle.html#rollup_bundle">
rollup_bundle
</a>
</li>
</ul>
</li>
</ul>
</nav>
</div>
<main class="mdl-layout__content">
<div class="page-content">
<h1>Install NodeJS & Yarn</h1>
<nav class="toc">
<h2><a href="#overview">Overview</a></h2>
<h2>Macros</h2>
<ul>
<li><a href="#node_repositories">node_repositories</a></li>
</ul>
</nav>
<hr>
<h2 id="overview">Overview</h2>
<p>This is a set of repository rules for setting up hermetic copies of NodeJS and Yarn.
See <a href="https://docs.bazel.build/versions/master/skylark/repository_rules.html">https://docs.bazel.build/versions/master/skylark/repository_rules.html</a></p>
<hr>
<h2 id="node_repositories">node_repositories</h2>
<pre>node_repositories(<a href="#node_repositories.package_json">package_json</a>, <a href="#node_repositories.node_version">node_version</a>, <a href="#node_repositories.yarn_version">yarn_version</a>, <a href="#node_repositories.vendored_node">vendored_node</a>, <a href="#node_repositories.vendored_yarn">vendored_yarn</a>, <a href="#node_repositories.node_repositories">node_repositories</a>, <a href="#node_repositories.yarn_repositories">yarn_repositories</a>, <a href="#node_repositories.node_urls">node_urls</a>, <a href="#node_repositories.yarn_urls">yarn_urls</a>, <a href="#node_repositories.preserve_symlinks">preserve_symlinks</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.</p>
<p>The versions of these tools can be specified in one of three ways:</p>
<ul>
<li>Normal Usage:
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.</li>
<li>Forced version(s):
You can select the version of NodeJS and/or Yarn to download &amp; use by specifying it when you call node_repositories,
but you must use a value that matches a known version.</li>
<li>Using a custom version:
You can pass in a custom list of NodeJS and/or Yarn repositories and URLs for node_resositories to use.</li>
<li>Using a local version:
To avoid downloads, you can check in vendored copies of NodeJS and/or Yarn and set vendored_node and or vendored_yarn
to point to those before calling node_repositories.</li>
</ul>
<p>This rule exposes the <code>@nodejs</code> workspace containing some rules the user can call later:</p>
<ul>
<li>Run node: <code>bazel run @nodejs//:node path/to/program.js</code></li>
<li>Install dependencies using npm: <code>bazel run @nodejs//:npm install</code></li>
<li>Install dependencies using yarn: <code>bazel run @nodejs//:yarn</code></li>
</ul>
<p>This rule also exposes the <code>@yarn</code> workspace for backwards compatibility:</p>
<ul>
<li>Alternately install dependencies using yarn: <code>bazel run @yarn//:yarn</code></li>
</ul>
<p>Note that the dependency installation scripts will run in each subpackage indicated by the <code>package_json</code> attribute.</p>
<p>This approach uses npm/yarn as the package manager. You could instead have Bazel act as the package manager, running the install behind the scenes.
See the <code>npm_install</code> and <code>yarn_install</code> rules, and the discussion in the README.</p>
<pre><code>load("@build_bazel_rules_nodejs//:defs.bzl", "node_repositories")
node_repositories(package_json = ["//:package.json", "//subpkg:package.json"])
</code></pre>
<p>Running <code>bazel run @nodejs//:yarn</code> in this repo would create <code>/node_modules</code> and <code>/subpkg/node_modules</code>.</p>
<h3 id="node_repositories_args">Attributes</h3>
<table class="params-table">
<colgroup>
<col class="col-param" />
<col class="col-description" />
</colgroup>
<tbody>
<tr id="node_repositories.package_json">
<td><code>package_json</code></td>
<td>
<p><code>List of strings; Optional</code></p>
<p>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>bazel run @nodejs//:yarn</code> or <code>bazel run @nodejs//:npm install</code>.
If you use bazel-managed dependencies, you can omit this attribute.</p>
</td>
</tr>
<tr id="node_repositories.node_version">
<td><code>node_version</code></td>
<td>
<p><code>Unknown; Optional</code></p>
<p>optional; the specific version of NodeJS to install.</p>
</td>
</tr>
<tr id="node_repositories.yarn_version">
<td><code>yarn_version</code></td>
<td>
<p><code>Unknown; Optional</code></p>
<p>optional; the specific version of Yarn to install.</p>
</td>
</tr>
<tr id="node_repositories.vendored_node">
<td><code>vendored_node</code></td>
<td>
<p><code>Unknown; Optional</code></p>
<p>optional; the local path to a pre-installed NodeJS runtime.</p>
</td>
</tr>
<tr id="node_repositories.vendored_yarn">
<td><code>vendored_yarn</code></td>
<td>
<p><code>Unknown; Optional</code></p>
<p>optional; the local path to a pre-installed yarn tool.</p>
</td>
</tr>
<tr id="node_repositories.node_repositories">
<td><code>node_repositories</code></td>
<td>
<p><code>Unknown; Optional</code></p>
<p>optional; custom list of node repositories to use.</p>
</td>
</tr>
<tr id="node_repositories.yarn_repositories">
<td><code>yarn_repositories</code></td>
<td>
<p><code>Unknown; Optional</code></p>
<p>optional; custom list of yarn repositories to use.</p>
</td>
</tr>
<tr id="node_repositories.node_urls">
<td><code>node_urls</code></td>
<td>
<p><code>Unknown; Optional</code></p>
<p>optional; custom list of URLs to use to download NodeJS.</p>
</td>
</tr>
<tr id="node_repositories.yarn_urls">
<td><code>yarn_urls</code></td>
<td>
<p><code>Unknown; Optional</code></p>
<p>optional; custom list of URLs to use to download Yarn.</p>
</td>
</tr>
<tr id="node_repositories.preserve_symlinks">
<td><code>preserve_symlinks</code></td>
<td>
<p><code>Boolean; Optional; Default is True</code></p>
<p>Turn on --node_options=--preserve-symlinks for nodejs_binary and nodejs_test rules.
The default for this is currently True but the options is deprecated and will be removed in the future.
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 hermiticity which is required for remote execution.</p>
</td>
</tr>
</tbody>
</table>
</div>
<footer class="mdl-mini-footer">
<div class="mdl-mini-footer__left-section">
<div class="mdl-logo">Bazel</div>
<ul class="mdl-mini-footer__link-list">
<li><a href="https://bazel.build">Home</a></li>
<li><a href="https://github.com/bazelbuild">GitHub</a></li>
</ul>
</div>
</footer>
</main>
</div>
</body>
</html>