nodejs

nodejs makes the selected official Node.js distribution available to dependent tasks. Use it when calling node directly through a general command runner. It is not a function and takes no arguments.

When project-root package.json declares pnpm, loading nodejs also downloads and installs a matching official standalone pnpm release from GitHub. pnpm 11 and newer are supported. The nodejs dependency puts pnpm on PATH and configures an xx-owned command-scoped binary directory as pnpm's globalBinDir, including global binaries installed by an earlier dependent task. Global packages, store data, metadata cache, and state use persistent xx cache directories for reuse. npm_install and npm_run select managed pnpm from the package.json in their dir, including nested packages, despite retaining their existing Starlark names. Without a declaration, they use npm bundled with Node.js.

Supported declarations are an exact top-level version:

{
  "packageManager": "[email protected]"
}

or a devEngines semver range:

{
  "devEngines": {
    "packageManager": {
      "name": "pnpm",
      "version": ">=11.0.0 <12.0.0",
      "onFail": "download"
    }
  }
}

^11.5.0 ranges are also supported. xx ignores onFail, resolves the newest published stable version from npm registry metadata, reads its official asset digest from the GitHub release page, and caches the verified GitHub archive. This avoids GitHub API rate limits. package.json is read when nodejs loads, so pnpm declarations cannot be generated later by task dependencies. Other package-manager declarations do not enable managed tooling and preserve existing npm behavior.

Corepack-style integrity suffixes such as [email protected]+sha512.abcdef are accepted. xx still verifies the downloaded archive against digest published by GitHub.

Load an exact stable x.y.z release or release candidate in the form x.y.z-rc.N, without a leading v. The exact host artifact must exist in Node.js's official release indexes and bundle npm and npx version 7 or newer.

On first use, xx downloads and verifies the official Node.js distribution, including bundled npm and npx. Later runs reuse it. Supported hosts are Windows x86-64 and ARM64, Linux x86-64 and ARM64, and macOS ARM64.

Examples

Print the managed Node.js version

load("@[email protected]", "nodejs")
load("@os@1", "os_run")

os_run(("node", "--version"), deps=[nodejs])

Run a project script directly

load("@[email protected]", "nodejs")
load("@os@1", "env_set", "os_run")

os_run(
    ("node", "scripts/generate.mjs"),
    deps=[nodejs, env_set("NODE_ENV", "production")],
)

Use npm_run for scripts declared in the selected package directory's package.json.