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

This is the "core" module, and is used internally by `build_bazel_rules_nodejs`.
Most users should continue to use only the latter, and ignore this "core" module.

The dependency graph is:
`build_bazel_rules_nodejs -> rules_nodejs -> bazel_skylib`

Features:
- A [Toolchain](https://docs.bazel.build/versions/main/toolchains.html) 
  that fetches a hermetic copy of node, npm, and yarn - 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.

Most features, such as `npm_install` and `nodejs_binary` are still in the `build_bazel_rules_nodejs` module.
We plan to clean these up and port into `rules_nodejs` in a future major release.


## directory_file_path

**USAGE**

<pre>
directory_file_path(<a href="#directory_file_path-name">name</a>, <a href="#directory_file_path-directory">directory</a>, <a href="#directory_file_path-path">path</a>)
</pre>

Provide DirectoryFilePathInfo to reference some file within a directory.

        Otherwise there is no way to give a Bazel label for it.

**ATTRIBUTES**


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

(*<a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory*): A unique name for this target.


<h4 id="directory_file_path-directory">directory</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>, mandatory*): a directory


<h4 id="directory_file_path-path">path</h4>

(*String, mandatory*): a path within that directory



## node_repositories

**USAGE**

<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-platform">platform</a>,
                  <a href="#node_repositories-repo_mapping">repo_mapping</a>, <a href="#node_repositories-use_nvmrc">use_nvmrc</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 NodeJS that was available when the
version of rules_nodejs you're using was released.
Note that you can skip calling `node_repositories` in your WORKSPACE file - if you later try to `yarn_install` or `npm_install`,
we'll automatically select this simple usage for you.

### Forced version(s)

You can select the version of NodeJS 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 NodeJS repositories and URLs for node_repositories to use.

#### Custom NodeJS versions

To specify custom NodeJS versions, use the `node_repositories` attribute

```python
node_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
node_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) and `examples/vendored_node_and_yarn`.



**ATTRIBUTES**


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

(*<a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory*): A unique name for this repository.


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

(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>*): auth to use for all url requests
Example: {"type": "basic", "login": "<UserName>", "password": "<Password>" }

Defaults to `{}`

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

(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> List of strings</a>*): Custom list of node repositories to use

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.

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

Defaults to `{}`

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

(*List of strings*): custom list of URLs to use to download NodeJS

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="node_repositories-node_version">node_version</h4>

(*String*): the specific version of NodeJS to install

Defaults to `"16.12.0"`

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

(*String*): Internal use only. Which platform to install as a toolchain. If unset, we assume the repository is named nodejs_[platform]

Defaults to `""`

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

(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>, mandatory*): A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`).


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

(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): the local path of the .nvmrc file containing the version of node

If set then also set node_version to the version found in the .nvmrc file.

Defaults to `None`


## node_toolchain

**USAGE**

<pre>
node_toolchain(<a href="#node_toolchain-name">name</a>, <a href="#node_toolchain-run_npm">run_npm</a>, <a href="#node_toolchain-target_tool">target_tool</a>, <a href="#node_toolchain-target_tool_path">target_tool_path</a>)
</pre>

Defines a node toolchain.

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 node_toolchain definition:

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

node_toolchain(
    name = "node_toolchain",
    target_tool = "//some/path/bin/node",
)
```

Next, declare which execution platforms or target platforms the toolchain should be selected for:
```starlark
toolchain(
    name = "my_nodejs",
    exec_compatible_with = [
        "@platforms//os:linux",
        "@platforms//cpu:x86_64",
    ],
    toolchain = ":node_toolchain",
    toolchain_type = "@rules_nodejs//nodejs:toolchain_type",
)
```

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.


**ATTRIBUTES**


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

(*<a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory*): A unique name for this target.


<h4 id="node_toolchain-run_npm">run_npm</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): A template file that allows us to execute npm

Defaults to `None`

<h4 id="node_toolchain-target_tool">target_tool</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): A hermetically downloaded nodejs executable target for the target platform.

Defaults to `None`

<h4 id="node_toolchain-target_tool_path">target_tool_path</h4>

(*String*): Path to an existing nodejs executable for the target platform.

Defaults to `""`


## yarn_repositories

**USAGE**

<pre>
yarn_repositories(<a href="#yarn_repositories-name">name</a>, <a href="#yarn_repositories-node_repository">node_repository</a>, <a href="#yarn_repositories-repo_mapping">repo_mapping</a>, <a href="#yarn_repositories-yarn_download_auth">yarn_download_auth</a>, <a href="#yarn_repositories-yarn_releases">yarn_releases</a>, <a href="#yarn_repositories-yarn_urls">yarn_urls</a>,
                  <a href="#yarn_repositories-yarn_version">yarn_version</a>)
</pre>

Repository rule to fetch the yarnpkg.com package manager.

Note, the recommended name is "yarn". If you choose a different name, you'll have to override the
`yarn` attribute in your `yarn_install` rule to point to your `yarn.js` file.

## Custom Yarn versions

To specify custom Yarn versions, use the `yarn_releases` attribute

```python
yarn_repositories(
    yarn_releases = {
        "1.12.1": ("yarn-v1.12.1.tar.gz", "yarn-v1.12.1", "09bea8f4ec41e9079fa03093d3b2db7ac5c5331852236d63815f8df42b3ba88d"),
    },
)
```

Like `node_urls`, the `yarn_urls` attribute can be used to provide a list of custom URLs to use to download yarn

```python
yarn_repositories(
    yarn_releases = {
        "1.12.1": ("yarn-v1.12.1.tar.gz", "yarn-v1.12.1", "09bea8f4ec41e9079fa03093d3b2db7ac5c5331852236d63815f8df42b3ba88d"),
    },
    yarn_version = "1.12.1",
    yarn_urls = [
        "https://github.com/yarnpkg/yarn/releases/download/v{version}/{filename}",
    ],
)
```

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 `09bea8f4ec41e9079fa03093d3b2db7ac5c5331852236d63815f8df42b3ba88d`.

If you don't use Yarn at all, you can skip downloading it by setting `yarn_urls = []`.

## Vendored yarn

You can vendor the `yarn.js` file into your repo. In this case, don't call `yarn_repositories` at all.
Just pass the label of your vendored file to the `yarn` attribute of `yarn_install`.


**ATTRIBUTES**


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

(*<a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory*): A unique name for this repository.


<h4 id="yarn_repositories-node_repository">node_repository</h4>

(*String*): The basename for a nodejs toolchain to use for running yarn.
            Usually this is the value of the `name` attribute given to a nodejs_register_toolchains call in WORKSPACE

Defaults to `"nodejs"`

<h4 id="yarn_repositories-repo_mapping">repo_mapping</h4>

(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>, mandatory*): A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`).


<h4 id="yarn_repositories-yarn_download_auth">yarn_download_auth</h4>

(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>*): auth to use for all url requests
    Example: {"type": "basic", "login": "<UserName>", "password": "<Password>" }

Defaults to `{}`

<h4 id="yarn_repositories-yarn_releases">yarn_releases</h4>

(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> List of strings</a>*): Custom list of yarn releases to use.

    Dictionary mapping Yarn versions to their corresponding (filename, strip_prefix, sha256) tuples.

    By default, if this attribute has no items, we'll use a list of all public releases which
    is periodically mirrored to rules_nodejs.

Defaults to `{}`

<h4 id="yarn_repositories-yarn_urls">yarn_urls</h4>

(*List of strings*): custom list of URLs to use to download Yarn

    Each entry is a template using `yarn_version` and `yarn_releases` in the substitutions.

    If this list is empty, we won't download yarn at all.

Defaults to `["https://github.com/yarnpkg/yarn/releases/download/v{version}/{filename}"]`

<h4 id="yarn_repositories-yarn_version">yarn_version</h4>

(*String*): the specific version of Yarn to install

Defaults to `"1.22.11"`


## DeclarationInfo

**USAGE**

<pre>
DeclarationInfo(<a href="#DeclarationInfo-declarations">declarations</a>, <a href="#DeclarationInfo-transitive_declarations">transitive_declarations</a>, <a href="#DeclarationInfo-type_blocklisted_declarations">type_blocklisted_declarations</a>)
</pre>

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.

Do not create DeclarationInfo instances directly, instead use the declaration_info factory function.

Note: historically this was a subset of the string-typed "typescript" provider.


**FIELDS**

<h4 id="DeclarationInfo-declarations">declarations</h4>

 A depset of typings files produced by this rule 
<h4 id="DeclarationInfo-transitive_declarations">transitive_declarations</h4>

 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. 
<h4 id="DeclarationInfo-type_blocklisted_declarations">type_blocklisted_declarations</h4>

 A depset of .d.ts files that we should not use to infer JSCompiler types (via tsickle) 


## DirectoryFilePathInfo

**USAGE**

<pre>
DirectoryFilePathInfo(<a href="#DirectoryFilePathInfo-directory">directory</a>, <a href="#DirectoryFilePathInfo-path">path</a>)
</pre>

Joins a label pointing to a TreeArtifact with a path nested within that directory.

**FIELDS**

<h4 id="DirectoryFilePathInfo-directory">directory</h4>

 a TreeArtifact (ctx.actions.declare_directory) 
<h4 id="DirectoryFilePathInfo-path">path</h4>

 path relative to the directory 


## JSModuleInfo

**USAGE**

<pre>
JSModuleInfo(<a href="#JSModuleInfo-direct_sources">direct_sources</a>, <a href="#JSModuleInfo-sources">sources</a>)
</pre>

JavaScript files and sourcemaps.

**FIELDS**

<h4 id="JSModuleInfo-direct_sources">direct_sources</h4>

 Depset of direct JavaScript files and sourcemaps 
<h4 id="JSModuleInfo-sources">sources</h4>

 Depset of direct and transitive JavaScript files and sourcemaps 


## LinkablePackageInfo

**USAGE**

<pre>
LinkablePackageInfo(<a href="#LinkablePackageInfo-files">files</a>, <a href="#LinkablePackageInfo-package_name">package_name</a>, <a href="#LinkablePackageInfo-package_path">package_path</a>, <a href="#LinkablePackageInfo-path">path</a>)
</pre>

The LinkablePackageInfo provider provides information to the linker for linking pkg_npm built packages

**FIELDS**

<h4 id="LinkablePackageInfo-files">files</h4>

 Depset of files in this package (must all be contained within path) 
<h4 id="LinkablePackageInfo-package_name">package_name</h4>

 The package name.

This field is optional. If not set, the target can be made linkable to a package_name with the npm_link rule. 
<h4 id="LinkablePackageInfo-package_path">package_path</h4>

 The directory in the workspace to link to.

If set, link the 1st party dependencies to the node_modules under the package path specified.
If unset, the default is to link to the node_modules root of the workspace. 
<h4 id="LinkablePackageInfo-path">path</h4>

 The path to link to.

Path must be relative to execroot/wksp. It can either an output dir path such as,

`bazel-out/<platform>-<build>/bin/path/to/package` or
`bazel-out/<platform>-<build>/bin/external/external_wksp>/path/to/package`

or a source file path such as,

`path/to/package` or
`external/<external_wksp>/path/to/package` 


## UserBuildSettingInfo

**USAGE**

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



**FIELDS**

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

 (Undocumented) 


## declaration_info

**USAGE**

<pre>
declaration_info(<a href="#declaration_info-declarations">declarations</a>, <a href="#declaration_info-deps">deps</a>)
</pre>

Constructs a DeclarationInfo including all transitive files needed to type-check from DeclarationInfo providers in a list of deps.

**PARAMETERS**


<h4 id="declaration_info-declarations">declarations</h4>

list of typings files



<h4 id="declaration_info-deps">deps</h4>

list of labels of dependencies where we should collect their DeclarationInfo to pass transitively

Defaults to `[]`


## js_module_info

**USAGE**

<pre>
js_module_info(<a href="#js_module_info-sources">sources</a>, <a href="#js_module_info-deps">deps</a>)
</pre>

Constructs a JSModuleInfo including all transitive sources from JSModuleInfo providers in a list of deps.

**PARAMETERS**


<h4 id="js_module_info-sources">sources</h4>

direct JS files



<h4 id="js_module_info-deps">deps</h4>

other targets that provide JSModuleInfo, typically from the deps attribute

Defaults to `[]`