Google Git
Sign in
pigweed/third_party/github/bazel-contrib/rules_nodejs/f481a1abf54b1dee887329ef1ea8a0bb1e5f2bb1/./docs/node/node_repositories.html
blob: f33a82e9cc382b69bbecc4553919d700e0bce3d8 [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/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.node_path">node_path</a>, <a href="#node_repositories.yarn_path">yarn_path</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 node_path and or yarn_path
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 compatabilty:</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>Unknown; Required</code></p>
<p>a list of labels, which indicate the package.json files that need to be installed.</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.node_path">
<td><code>node_path</code></td>
<td>
<p><code>String; Optional</code></p>
<p>optional; the local path to a pre-installed NodeJS runtime.</p>
</td>
</tr>
<tr id="node_repositories.yarn_path">
<td><code>yarn_path</code></td>
<td>
<p><code>String; 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 False</code></p>
<p>Turn on --node_options=--preserve-symlinks for nodejs_binary and nodejs_test rules.
The default for this is currently False but will be switched to True 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>