docs/Core.md

<!-- *********************
  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
 ********************* -->
# rules_nodejs Bazel module

Features:
- A [Toolchain](https://docs.bazel.build/versions/main/toolchains.html)
  that fetches a hermetic copy of node and npm - independent of what's on the developer's machine.
- Core [Providers](https://docs.bazel.build/versions/main/skylark/rules.html#providers) to allow interop between JS rules.

## UserBuildSettingInfo

**USAGE**

<pre>
UserBuildSettingInfo(<a href="#UserBuildSettingInfo-value">value</a>)
</pre>



**FIELDS**

<h4 id="UserBuildSettingInfo-value">value</h4>

 - 


## nodejs_repositories

**USAGE**

<pre>
nodejs_repositories(<a href="#nodejs_repositories-name">name</a>, <a href="#nodejs_repositories-node_download_auth">node_download_auth</a>, <a href="#nodejs_repositories-node_repositories">node_repositories</a>, <a href="#nodejs_repositories-node_urls">node_urls</a>, <a href="#nodejs_repositories-node_version">node_version</a>,
                    <a href="#nodejs_repositories-node_version_from_nvmrc">node_version_from_nvmrc</a>, <a href="#nodejs_repositories-include_headers">include_headers</a>, <a href="#nodejs_repositories-kwargs">kwargs</a>)
</pre>

To be run in user's WORKSPACE to install rules_nodejs dependencies.

This rule sets up node, npm, and npx. The versions of these tools can be specified in one of three ways

### Simplest Usage

Specify no explicit versions. This will download and use the latest Node.js that was available when the
version of rules_nodejs you're using was released.

### Forced version(s)

You can select the version of Node.js to download & use by specifying it when you call node_repositories,
using a value that matches a known version (see the default values)

### Using a custom version

You can pass in a custom list of Node.js repositories and URLs for node_repositories to use.

#### Custom Node.js versions

To specify custom Node.js versions, use the `node_repositories` attribute

```python
nodejs_repositories(
    node_repositories = {
        "10.10.0-darwin_amd64": ("node-v10.10.0-darwin-x64.tar.gz", "node-v10.10.0-darwin-x64", "00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e"),
        "10.10.0-linux_amd64": ("node-v10.10.0-linux-x64.tar.xz", "node-v10.10.0-linux-x64", "686d2c7b7698097e67bcd68edc3d6b5d28d81f62436c7cf9e7779d134ec262a9"),
        "10.10.0-windows_amd64": ("node-v10.10.0-win-x64.zip", "node-v10.10.0-win-x64", "70c46e6451798be9d052b700ce5dadccb75cf917f6bf0d6ed54344c856830cfb"),
    },
)
```

These can be mapped to a custom download URL, using `node_urls`

```python
nodejs_repositories(
    node_version = "10.10.0",
    node_repositories = {"10.10.0-darwin_amd64": ("node-v10.10.0-darwin-x64.tar.gz", "node-v10.10.0-darwin-x64", "00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e")},
    node_urls = ["https://mycorpproxy/mirror/node/v{version}/{filename}"],
)
```

A Mac client will try to download node from `https://mycorpproxy/mirror/node/v10.10.0/node-v10.10.0-darwin-x64.tar.gz`
and expect that file to have sha256sum `00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e`

See the [the repositories documentation](repositories.html) for how to use the resulting repositories.

### Using a custom node.js.

To avoid downloads, you can check in a vendored node.js binary or can build one from source.
See [toolchains](./toolchains.md).


**PARAMETERS**


<h4 id="nodejs_repositories-name">name</h4>

Unique name for the repository rule



<h4 id="nodejs_repositories-node_download_auth">node_download_auth</h4>

Auth to use for all url requests.

Example: { "type": "basic", "login": "&lt;UserName&gt;", "password": "&lt;Password&gt;" }

Defaults to `{}`

<h4 id="nodejs_repositories-node_repositories">node_repositories</h4>

Custom list of node repositories to use

A dictionary mapping Node.js 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.

By default, if this attribute has no items, we'll use a list of all public Node.js releases.

Defaults to `{}`

<h4 id="nodejs_repositories-node_urls">node_urls</h4>

List of URLs to use to download Node.js.

Each entry is a template for downloading a node distribution.

The `{version}` parameter is substituted with the `node_version` attribute,
and `{filename}` with the matching entry from the `node_repositories` attribute.

Defaults to `["https://nodejs.org/dist/v{version}/{filename}"]`

<h4 id="nodejs_repositories-node_version">node_version</h4>

The specific version of Node.js to install

Defaults to `"18.20.8"`

<h4 id="nodejs_repositories-node_version_from_nvmrc">node_version_from_nvmrc</h4>

The .nvmrc file containing the version of Node.js to use.

If set then the version found in the .nvmrc file is used instead of the one specified by node_version.

Defaults to `None`

<h4 id="nodejs_repositories-include_headers">include_headers</h4>

Set headers field in NodeInfo provided by this toolchain.

This setting creates a dependency on a c++ toolchain.

Defaults to `False`

<h4 id="nodejs_repositories-kwargs">kwargs</h4>

Additional parameters




## nodejs_toolchain

**USAGE**

<pre>
nodejs_toolchain(<a href="#nodejs_toolchain-name">name</a>, <a href="#nodejs_toolchain-node">node</a>, <a href="#nodejs_toolchain-node_path">node_path</a>, <a href="#nodejs_toolchain-npm">npm</a>, <a href="#nodejs_toolchain-npm_path">npm_path</a>, <a href="#nodejs_toolchain-npm_srcs">npm_srcs</a>, <a href="#nodejs_toolchain-headers">headers</a>, <a href="#nodejs_toolchain-kwargs">kwargs</a>)
</pre>

Defines a node toolchain for a platform.

You can use this to refer to a vendored nodejs binary in your repository,
or even to compile nodejs from sources using rules_foreign_cc or other rules.

First, in a BUILD.bazel file, create a nodejs_toolchain definition:

```starlark
load("@rules_nodejs//nodejs:toolchain.bzl", "nodejs_toolchain")

nodejs_toolchain(
    name = "toolchain",
    node = "//some/path/bin/node",
)
```

Next, declare which execution platforms or target platforms the toolchain should be selected for
based on constraints.

```starlark
toolchain(
    name = "my_nodejs",
    exec_compatible_with = [
        "@platforms//os:linux",
        "@platforms//cpu:x86_64",
    ],
    toolchain = ":toolchain",
    toolchain_type = "@rules_nodejs//nodejs:toolchain_type",
)
```

See https://bazel.build/extending/toolchains#toolchain-resolution for more information on toolchain
resolution.

Finally in your `WORKSPACE`, register it with `register_toolchains("//:my_nodejs")`

For usage see https://docs.bazel.build/versions/main/toolchains.html#defining-toolchains.
You can use the `--toolchain_resolution_debug` flag to `bazel` to help diagnose which toolchain is selected.


**PARAMETERS**


<h4 id="nodejs_toolchain-name">name</h4>

Unique name for this target



<h4 id="nodejs_toolchain-node">node</h4>

Node.js executable

Defaults to `None`

<h4 id="nodejs_toolchain-node_path">node_path</h4>

Path to Node.js executable file

This is typically an absolute path to a non-hermetic Node.js executable.

Only one of `node` and `node_path` may be set.

Defaults to `""`

<h4 id="nodejs_toolchain-npm">npm</h4>

Npm JavaScript entry point

Defaults to `None`

<h4 id="nodejs_toolchain-npm_path">npm_path</h4>

Path to npm JavaScript entry point.

This is typically an absolute path to a non-hermetic npm installation.

Only one of `npm` and `npm_path` may be set.

Defaults to `""`

<h4 id="nodejs_toolchain-npm_srcs">npm_srcs</h4>

Additional source files required to run npm.

Not necessary if specifying `npm_path` to a non-hermetic npm installation.

Defaults to `[]`

<h4 id="nodejs_toolchain-headers">headers</h4>

cc_library that contains the Node/v8 header files

Defaults to `None`

<h4 id="nodejs_toolchain-kwargs">kwargs</h4>

Additional parameters