| |
| |
| <!-- |
| 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 npm packages</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 npm packages</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 npm packages</h1> |
| |
| <nav class="toc"> |
| <h2><a href="#overview">Overview</a></h2> |
| <h2>Repository Rules</h2> |
| <ul> |
| <li><a href="#npm_install">npm_install</a></li> |
| <li><a href="#yarn_install">yarn_install</a></li> |
| </ul> |
| </nav> |
| <hr> |
| <h2 id="overview">Overview</h2> |
| <p>Rules to install NodeJS dependencies during WORKSPACE evaluation. |
| This happens before the first build or test runs, allowing you to use Bazel |
| as the package manager.</p> |
| <p>See discussion in the README.</p> |
| |
| <hr> |
| |
| <h2 id="npm_install">npm_install</h2> |
| |
| <pre>npm_install(<a href="#npm_install.name">name</a>, <a href="#npm_install.data">data</a>, <a href="#npm_install.always_hide_bazel_files">always_hide_bazel_files</a>, <a href="#npm_install.exclude_packages">exclude_packages</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.package_json">package_json</a>, <a href="#npm_install.package_lock_json">package_lock_json</a>, <a href="#npm_install.prod_only">prod_only</a>, <a href="#npm_install.quiet">quiet</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> |
| |
| |
| <h3 id="npm_install_args">Attributes</h3> |
| |
| <table class="params-table"> |
| <colgroup> |
| <col class="col-param" /> |
| <col class="col-description" /> |
| </colgroup> |
| <tbody> |
| <tr id="npm_install.name"> |
| <td><code>name</code></td> |
| <td> |
| <p><code><a href="https://bazel.build/docs/build-ref.html#name">Name</a>; Required</code></p> |
| <p>A unique name for this rule.</p> |
| </td> |
| </tr> |
| <tr id="npm_install.data"> |
| <td><code>data</code></td> |
| <td> |
| <p><code>List of <a href="https://bazel.build/docs/build-ref.html#labels">labels</a>; Optional; Default is []</code></p> |
| <p>Data files required by this rule.</p> |
| <pre><code> If symlink_node_modules is True, this attribute is ignored since |
| the dependency manager will run in the package.json location. |
| </code></pre> |
| </td> |
| </tr> |
| <tr id="npm_install.always_hide_bazel_files"> |
| <td><code>always_hide_bazel_files</code></td> |
| <td> |
| <p><code>Boolean; Optional; Default is False</code></p> |
| <p>If True then Bazel build files such as <code>BUILD</code> and BUILD.bazel<code>will always be hidden by prefixing them with</code>_`.</p> |
| <pre><code> Defaults to False, in which case Bazel files are _not_ hidden when `symlink_node_modules` |
| is True. In this case, the rule will report an error when there are Bazel files detected |
| in npm packages. |
| |
| Reporting the error is desirable as relying on this repository rule to hide |
| these files does not work in the case where a user deletes their node_modules folder |
| and manually re-creates it with yarn or npm outside of Bazel which would restore them. |
| On a subsequent Bazel build, this repository rule does not re-run and the presence |
| of the Bazel files leads to a build failure that looks like the following: |
| |
| ``` |
| ERROR: /private/var/tmp/_bazel_greg/37b273501bbecefcf5ce4f3afcd7c47a/external/npm/BUILD.bazel:9:1: |
| Label '@npm//:node_modules/rxjs/src/AsyncSubject.ts' crosses boundary of subpackage '@npm//node_modules/rxjs/src' |
| (perhaps you meant to put the colon here: '@npm//node_modules/rxjs/src:AsyncSubject.ts'?) |
| ``` |
| |
| See https://github.com/bazelbuild/rules_nodejs/issues/802 for more details. |
| |
| The recommended solution is to use the @bazel/hide-bazel-files utility to hide these files. |
| See https://github.com/bazelbuild/rules_nodejs/blob/master/packages/hide-bazel-files/README.md |
| for installation instructions. |
| |
| The alternate solution is to set `always_hide_bazel_files` to True which tell |
| this rule to hide Bazel files even when `symlink_node_modules` is True. This means |
| you won't need to use `@bazel/hide-bazel-files` utility but if you manually recreate |
| your `node_modules` folder via yarn or npm outside of Bazel you may run into the above |
| error. |
| </code></pre> |
| </td> |
| </tr> |
| <tr id="npm_install.exclude_packages"> |
| <td><code>exclude_packages</code></td> |
| <td> |
| <p><code>List of strings; Optional; Default is []</code></p> |
| <p>DEPRECATED. This attribute is no longer used.</p> |
| </td> |
| </tr> |
| <tr id="npm_install.included_files"> |
| <td><code>included_files</code></td> |
| <td> |
| <p><code>List of strings; Optional; Default is []</code></p> |
| <p>List of file extensions to be included in the npm package targets.</p> |
| <pre><code> For example, [".js", ".d.ts", ".proto", ".json", ""]. |
| |
| 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. |
| |
| 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 `README` should |
| be included in the package targets. |
| |
| This attribute applies to both the coarse `@wksp//:node_modules` target |
| as well as the fine grained targets such as `@wksp//foo`. |
| </code></pre> |
| </td> |
| </tr> |
| <tr id="npm_install.manual_build_file_contents"> |
| <td><code>manual_build_file_contents</code></td> |
| <td> |
| <p><code>String; Optional; Default is ''</code></p> |
| <p>Experimental attribute that can be used to override |
| the generated BUILD.bazel file and set its contents manually. |
| Can be used to work-around a bazel performance issue if the |
| default <code>@wksp//:node_modules</code> target has too many files in it. |
| See <a href="https://github.com/bazelbuild/bazel/issues/5153">https://github.com/bazelbuild/bazel/issues/5153</a>. 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> |
| </td> |
| </tr> |
| <tr id="npm_install.package_json"> |
| <td><code>package_json</code></td> |
| <td> |
| <p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Required</code></p> |
| |
| </td> |
| </tr> |
| <tr id="npm_install.package_lock_json"> |
| <td><code>package_lock_json</code></td> |
| <td> |
| <p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Required</code></p> |
| |
| </td> |
| </tr> |
| <tr id="npm_install.prod_only"> |
| <td><code>prod_only</code></td> |
| <td> |
| <p><code>Boolean; Optional; Default is False</code></p> |
| <p>Don't install devDependencies</p> |
| </td> |
| </tr> |
| <tr id="npm_install.quiet"> |
| <td><code>quiet</code></td> |
| <td> |
| <p><code>Boolean; Optional; Default is True</code></p> |
| <p>If stdout and stderr should be printed to the terminal.</p> |
| </td> |
| </tr> |
| <tr id="npm_install.symlink_node_modules"> |
| <td><code>symlink_node_modules</code></td> |
| <td> |
| <p><code>Boolean; Optional; Default is True</code></p> |
| <p>Turn symlinking of node_modules on</p> |
| <pre><code> This requires the use of Bazel 0.26.0 and the experimental |
| managed_directories feature. |
| |
| 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. |
| |
| 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. |
| </code></pre> |
| </td> |
| </tr> |
| <tr id="npm_install.timeout"> |
| <td><code>timeout</code></td> |
| <td> |
| <p><code>Integer; Optional; Default is 3600</code></p> |
| <p>Maximum duration of the command "npm install" in seconds |
| (default is 3600 seconds).</p> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <hr> |
| |
| <h2 id="yarn_install">yarn_install</h2> |
| |
| <pre>yarn_install(<a href="#yarn_install.name">name</a>, <a href="#yarn_install.data">data</a>, <a href="#yarn_install.always_hide_bazel_files">always_hide_bazel_files</a>, <a href="#yarn_install.exclude_packages">exclude_packages</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.network_timeout">network_timeout</a>, <a href="#yarn_install.package_json">package_json</a>, <a href="#yarn_install.prod_only">prod_only</a>, <a href="#yarn_install.quiet">quiet</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> |
| |
| |
| <h3 id="yarn_install_args">Attributes</h3> |
| |
| <table class="params-table"> |
| <colgroup> |
| <col class="col-param" /> |
| <col class="col-description" /> |
| </colgroup> |
| <tbody> |
| <tr id="yarn_install.name"> |
| <td><code>name</code></td> |
| <td> |
| <p><code><a href="https://bazel.build/docs/build-ref.html#name">Name</a>; Required</code></p> |
| <p>A unique name for this rule.</p> |
| </td> |
| </tr> |
| <tr id="yarn_install.data"> |
| <td><code>data</code></td> |
| <td> |
| <p><code>List of <a href="https://bazel.build/docs/build-ref.html#labels">labels</a>; Optional; Default is []</code></p> |
| <p>Data files required by this rule.</p> |
| <pre><code> If symlink_node_modules is True, this attribute is ignored since |
| the dependency manager will run in the package.json location. |
| </code></pre> |
| </td> |
| </tr> |
| <tr id="yarn_install.always_hide_bazel_files"> |
| <td><code>always_hide_bazel_files</code></td> |
| <td> |
| <p><code>Boolean; Optional; Default is False</code></p> |
| <p>If True then Bazel build files such as <code>BUILD</code> and BUILD.bazel<code>will always be hidden by prefixing them with</code>_`.</p> |
| <pre><code> Defaults to False, in which case Bazel files are _not_ hidden when `symlink_node_modules` |
| is True. In this case, the rule will report an error when there are Bazel files detected |
| in npm packages. |
| |
| Reporting the error is desirable as relying on this repository rule to hide |
| these files does not work in the case where a user deletes their node_modules folder |
| and manually re-creates it with yarn or npm outside of Bazel which would restore them. |
| On a subsequent Bazel build, this repository rule does not re-run and the presence |
| of the Bazel files leads to a build failure that looks like the following: |
| |
| ``` |
| ERROR: /private/var/tmp/_bazel_greg/37b273501bbecefcf5ce4f3afcd7c47a/external/npm/BUILD.bazel:9:1: |
| Label '@npm//:node_modules/rxjs/src/AsyncSubject.ts' crosses boundary of subpackage '@npm//node_modules/rxjs/src' |
| (perhaps you meant to put the colon here: '@npm//node_modules/rxjs/src:AsyncSubject.ts'?) |
| ``` |
| |
| See https://github.com/bazelbuild/rules_nodejs/issues/802 for more details. |
| |
| The recommended solution is to use the @bazel/hide-bazel-files utility to hide these files. |
| See https://github.com/bazelbuild/rules_nodejs/blob/master/packages/hide-bazel-files/README.md |
| for installation instructions. |
| |
| The alternate solution is to set `always_hide_bazel_files` to True which tell |
| this rule to hide Bazel files even when `symlink_node_modules` is True. This means |
| you won't need to use `@bazel/hide-bazel-files` utility but if you manually recreate |
| your `node_modules` folder via yarn or npm outside of Bazel you may run into the above |
| error. |
| </code></pre> |
| </td> |
| </tr> |
| <tr id="yarn_install.exclude_packages"> |
| <td><code>exclude_packages</code></td> |
| <td> |
| <p><code>List of strings; Optional; Default is []</code></p> |
| <p>DEPRECATED. This attribute is no longer used.</p> |
| </td> |
| </tr> |
| <tr id="yarn_install.included_files"> |
| <td><code>included_files</code></td> |
| <td> |
| <p><code>List of strings; Optional; Default is []</code></p> |
| <p>List of file extensions to be included in the npm package targets.</p> |
| <pre><code> For example, [".js", ".d.ts", ".proto", ".json", ""]. |
| |
| 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. |
| |
| 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 `README` should |
| be included in the package targets. |
| |
| This attribute applies to both the coarse `@wksp//:node_modules` target |
| as well as the fine grained targets such as `@wksp//foo`. |
| </code></pre> |
| </td> |
| </tr> |
| <tr id="yarn_install.manual_build_file_contents"> |
| <td><code>manual_build_file_contents</code></td> |
| <td> |
| <p><code>String; Optional; Default is ''</code></p> |
| <p>Experimental attribute that can be used to override |
| the generated BUILD.bazel file and set its contents manually. |
| Can be used to work-around a bazel performance issue if the |
| default <code>@wksp//:node_modules</code> target has too many files in it. |
| See <a href="https://github.com/bazelbuild/bazel/issues/5153">https://github.com/bazelbuild/bazel/issues/5153</a>. 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> |
| </td> |
| </tr> |
| <tr id="yarn_install.network_timeout"> |
| <td><code>network_timeout</code></td> |
| <td> |
| <p><code>Integer; Optional; Default is 300</code></p> |
| <p>Maximum duration of a network request made by yarn in seconds |
| (default is 300 seconds).</p> |
| </td> |
| </tr> |
| <tr id="yarn_install.package_json"> |
| <td><code>package_json</code></td> |
| <td> |
| <p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Required</code></p> |
| |
| </td> |
| </tr> |
| <tr id="yarn_install.prod_only"> |
| <td><code>prod_only</code></td> |
| <td> |
| <p><code>Boolean; Optional; Default is False</code></p> |
| <p>Don't install devDependencies</p> |
| </td> |
| </tr> |
| <tr id="yarn_install.quiet"> |
| <td><code>quiet</code></td> |
| <td> |
| <p><code>Boolean; Optional; Default is True</code></p> |
| <p>If stdout and stderr should be printed to the terminal.</p> |
| </td> |
| </tr> |
| <tr id="yarn_install.symlink_node_modules"> |
| <td><code>symlink_node_modules</code></td> |
| <td> |
| <p><code>Boolean; Optional; Default is True</code></p> |
| <p>Turn symlinking of node_modules on</p> |
| <pre><code> This requires the use of Bazel 0.26.0 and the experimental |
| managed_directories feature. |
| |
| 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. |
| |
| 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. |
| </code></pre> |
| </td> |
| </tr> |
| <tr id="yarn_install.timeout"> |
| <td><code>timeout</code></td> |
| <td> |
| <p><code>Integer; Optional; Default is 3600</code></p> |
| <p>Maximum duration of the command "yarn install" in seconds |
| (default is 3600 seconds).</p> |
| </td> |
| </tr> |
| <tr id="yarn_install.use_global_yarn_cache"> |
| <td><code>use_global_yarn_cache</code></td> |
| <td> |
| <p><code>Boolean; Optional; Default is True</code></p> |
| <p>Use the global yarn cache on the system. |
| The cache lets you avoid downloading packages multiple times. |
| However, it can introduce non-hermeticity, and the yarn cache can |
| have bugs. |
| Disabling this attribute causes every run of yarn to have a unique |
| cache_directory.</p> |
| </td> |
| </tr> |
| <tr id="yarn_install.yarn_lock"> |
| <td><code>yarn_lock</code></td> |
| <td> |
| <p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Required</code></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> |
