Skip to main content
Version: 2.30 (prerelease)

nodejs

The Node.js Javascript runtime (including Corepack).

Backend: pants.backend.experimental.javascript

Config section: [nodejs]

Basic options​

package_manager​

--nodejs-package-manager=<str>
PANTS_NODEJS_PACKAGE_MANAGER
pants.toml
[nodejs]
package_manager = <str>
default: npm

Default Node.js package manager to use.

You can either rely on this default together with the [nodejs].package_managers option, or specify the package.json#packageManager tool and version in the package.json of your project.

Specifying conflicting package manager versions within a multi-package workspace is an error.

package_managers​

--nodejs-package-managers="{'key1': val1, 'key2': val2, ...}"
PANTS_NODEJS_PACKAGE_MANAGERS
pants.toml
[nodejs.package_managers]
key1 = val1
key2 = val2
...
default: 
{
  "npm": "11.6.2",
  "pnpm": "10.19.0",
  "yarn": "1.22.22"
}

A mapping of package manager versions to semver releases.

Many organizations only need a single version of a package manager, which is a good default and often the simplest thing to do.

The version download is managed by Corepack. This mapping corresponds to the https://github.com/nodejs/corepack#known-good-releases setting, using the --activate flag.

Advanced options​

corepack_env_vars​

--nodejs-corepack-env-vars="[<shell_str>, <shell_str>, ...]"
PANTS_NODEJS_COREPACK_ENV_VARS
pants.toml
[nodejs]
corepack_env_vars = [
  <shell_str>,
  <shell_str>,
  ...,
]
default: []

Environment variables to set for corepack invocations.

Entries are either strings in the form ENV_VAR=value to set an explicit value; or just ENV_VAR to copy the value from Pants's own environment.

Review https://github.com/nodejs/corepack#environment-variables for available variables.

Can be overriden by fieldnodejs_corepack_env_vars on local_environment, docker_environment, or remote_environmenttargets.

executable_search_paths​

--nodejs-executable-search-paths="[<binary-paths>, <binary-paths>, ...]"
PANTS_NODEJS_EXECUTABLE_SEARCH_PATHS
pants.toml
[nodejs]
executable_search_paths = [
  <binary-paths>,
  <binary-paths>,
  ...,
]
default: 
[
  "<PATH>"
]

The PATH value that will be used to find any tools required to run nodejs processes. The special string "<PATH>" will expand to the contents of the PATH env var.

Can be overriden by fieldnodejs_executable_search_paths on local_environment, docker_environment, or remote_environmenttargets.

extra_env_vars​

--nodejs-extra-env-vars="['<str>', '<str>', ...]"
PANTS_NODEJS_EXTRA_ENV_VARS
pants.toml
[nodejs]
extra_env_vars = [
  '<str>',
  '<str>',
  ...,
]
default: []

Environment variables to set during package manager operations.

Entries are strings in the form ENV_VAR=value to use explicitly; or just ENV_VAR to copy the value of a variable in Pants's own environment. fnmatch globs like ENV_VAR_PREFIXED_* can be used to copy multiple environment variables.

known_versions​

--nodejs-known-versions="['<str>', '<str>', ...]"
PANTS_NODEJS_KNOWN_VERSIONS
pants.toml
[nodejs]
known_versions = [
  '<str>',
  '<str>',
  ...,
]
default: 
[
  "v24.10.0|macos_arm64|fbc3d6e1e1d962450d058e918214373872cc4c46e08673f31c35932afac4a8c5|51169103",
  "v24.10.0|macos_x86_64|627b884f66db0dd35f4b46fb9e994774ce560a7fb60798ba1ab81e867a73687d|52347633",
  "v24.10.0|linux_arm64|07f0558316ebb8977dd6fb29b4de8d369a639d3d8cef544293852a6f5eea6af8|31020300",
  "v24.10.0|linux_x86_64|2642f4428869aca32443660fd71b3918e2be1277a899bdcaeb64c93b54b5af17|32102040"
]

Known versions to verify downloads against.

Each element is a pipe-separated string of version|platform|sha256|length or version|platform|sha256|length|url_override, where:

  • version is the version string
  • platform is one of [linux_arm64,linux_x86_64,macos_arm64,macos_x86_64]
  • sha256 is the 64-character hex representation of the expected sha256 digest of the download file, as emitted by shasum -a 256
  • length is the expected length of the download file in bytes, as emitted by wc -c
  • (Optional) url_override is a specific url to use instead of the normally generated url for this version

E.g., 3.1.2|macos_x86_64|6d0f18cd84b918c7b3edd0203e75569e0c7caecb1367bbbe409b44e28514f5be|42813. and 3.1.2|macos_arm64 |aca5c1da0192e2fd46b7b55ab290a92c5f07309e7b0ebf4e45ba95731ae98291|50926|https://example.mac.org/bin/v3.1.2/mac-aarch64-v3.1.2.tgz.

Values are space-stripped, so pipes can be indented for readability if necessary.

optional_tools​

--nodejs-optional-tools="['<str>', '<str>', ...]"
PANTS_NODEJS_OPTIONAL_TOOLS
pants.toml
[nodejs]
optional_tools = [
  '<str>',
  '<str>',
  ...,
]
default: []

List any additional executable which are not mandatory for node processes to work, but which should be included if available. The paths to these tools will be included in the PATH used in the execution sandbox, so that they may be used by nodejs processes execution.

resolves​

--nodejs-resolves="{'key1': val1, 'key2': val2, ...}"
PANTS_NODEJS_RESOLVES
pants.toml
[nodejs.resolves]
key1 = val1
key2 = val2
...
default: {}

A mapping of names to lockfile paths used in your project.

Specifying a resolve name is optional. If unspecified, the default resolve name is calculated by taking the path from the source root to the directory containing the lockfile and replacing '/' with '.' in that path.

Example: An npm lockfile located at src/js/package/package-lock.json will result in a resolve named js.package, assuming src/ is a source root.

Run pants generate-lockfiles to generate the lockfile(s).

search_path​

--nodejs-search-path="[<binary-paths>, <binary-paths>, ...]"
PANTS_NODEJS_SEARCH_PATH
pants.toml
[nodejs]
search_path = [
  <binary-paths>,
  <binary-paths>,
  ...,
]
default: 
[
  "<PATH>"
]

A list of paths to search for Node.js distributions.

This option is only used if a templated url download specified via [nodejs].known_versions does not contain a version matching the configured [nodejs].version range.

You can specify absolute paths to binaries and/or to directories containing binaries. The order of entries does not matter.

The following special strings are supported:

For all runtime environment types:

  • <PATH>, the contents of the PATH env var

When the environment is a local_environment target:

  • AsdfPathString.STANDARD, all Node.js versions currently configured by ASDF (asdf shell, ${HOME}/.tool-versions), with a fallback to all installed versions
  • AsdfPathString.LOCAL, the ASDF binaries with the version in BUILD_ROOT/.tool-versions
  • <NVM>, all NodeJS versions under $NVM_DIR/versions/node
  • <NVM_LOCAL>, the nvm installation with the version in BUILD_ROOT/.nvmrc Note that the version in the .nvmrc file has to be on the form "vX.Y.Z".
Can be overriden by fieldnodejs_search_path on local_environment, docker_environment, or remote_environmenttargets.

tools​

--nodejs-tools="['<str>', '<str>', ...]"
PANTS_NODEJS_TOOLS
pants.toml
[nodejs]
tools = [
  '<str>',
  '<str>',
  ...,
]
default: []

List any additional executable tools required for node processes to work. The paths to these tools will be included in the PATH used in the execution sandbox, so that they may be used by nodejs processes execution.

url_platform_mapping​

--nodejs-url-platform-mapping="{'key1': val1, 'key2': val2, ...}"
PANTS_NODEJS_URL_PLATFORM_MAPPING
pants.toml
[nodejs.url_platform_mapping]
key1 = val1
key2 = val2
...
default: 
{
  "linux_arm64": "linux-arm64",
  "linux_x86_64": "linux-x64",
  "macos_arm64": "darwin-arm64",
  "macos_x86_64": "darwin-x64"
}

A dictionary mapping platforms to strings to be used when generating the URL to download the tool.

In --url-template, anytime the {platform} string is used, Pants will determine the current platform, and substitute {platform} with the respective value from your dictionary.

For example, if you define {"macos_x86_64": "apple-darwin", "linux_x86_64": "unknown-linux"}, and run Pants on Linux with an intel architecture, then {platform} will be substituted in the --url-template option with unknown-linux.

url_template​

--nodejs-url-template=<str>
PANTS_NODEJS_URL_TEMPLATE
pants.toml
[nodejs]
url_template = <str>
default: https://nodejs.org/dist/{version}/node-{version}-{platform}.tar

URL to download the tool, either as a single binary file or a compressed file (e.g. zip file). You can change this to point to your own hosted file, e.g. to work with proxies or for access via the filesystem through a file:$abspath URL (e.g. file:/this/is/absolute, possibly by templating the buildroot in a config file).

Use {version} to have the value from --version substituted, and {platform} to have a value from --url-platform-mapping substituted in, depending on the current platform. For example, https://github.com/.../protoc-&#123;version&#125;-&#123;platform&#125;.zip.

version​

--nodejs-version=<str>
PANTS_NODEJS_VERSION
pants.toml
[nodejs]
version = <str>
default: v24.10.0

Use this version of nodejs.

Deprecated options​

None

None