### Node.js Installation Usage Example

Source: https://github.com/actions/setup-node/blob/main/_autodocs/types.md

Demonstrates how to configure and use NodeInputs to set up a specific Node.js version and architecture.

```typescript
import {getNodejsDistribution} from './distributions/installer-factory';

const nodeInputs: NodeInputs = {
  versionSpec: '20.15.1',
  arch: 'x64',
  auth: 'token ghp_xxxx',
  checkLatest: false,
  stable: true,
  mirror: '',
  mirrorToken: ''
};

const distribution = getNodejsDistribution(nodeInputs);
await distribution.setupNodeJs();
```

--------------------------------

### Basic Node.js Setup

Source: https://github.com/actions/setup-node/blob/main/_autodocs/configuration.md

Installs Node.js version 20. Use this for standard Node.js version requirements.

```yaml
-	uses:	actions/setup-node@v6
	with:
	node-version:	'20'
```

--------------------------------

### Recommended Permissions for Setup Node.js Action

Source: https://github.com/actions/setup-node/blob/main/README.md

Set these permissions for the Setup Node.js action to ensure it can access code and install dependencies.

```yaml
permissions:
  contents: read # access to check out code and install dependencies
```

--------------------------------

### Node.js Setup with Architecture

Source: https://github.com/actions/setup-node/blob/main/_autodocs/configuration.md

Installs Node.js version '20' for the 'arm64' architecture. Specify architecture when targeting specific hardware.

```yaml
-	uses:	actions/setup-node@v6
	with:
	node-version:	'20'
	architecture:	'arm64'
```

--------------------------------

### Node.js Setup with Latest Version

Source: https://github.com/actions/setup-node/blob/main/_autodocs/configuration.md

Installs the latest available Node.js version. Use with caution as it may introduce breaking changes.

```yaml
-	uses:	actions/setup-node@v6
	with:
	node-version:	'latest'
```

--------------------------------

### Node.js Setup with Version File

Source: https://github.com/actions/setup-node/blob/main/_autodocs/configuration.md

Installs Node.js based on the version specified in a file (e.g., .nvmrc, package.json). Ensure the file exists in the repository.

```yaml
-	uses:	actions/setup-node@v6
	with:
	node-version-file:	'.nvmrc'
```

--------------------------------

### Run Setup Node Action

Source: https://github.com/actions/setup-node/blob/main/_autodocs/api-reference/main.md

This is the main entry point for the setup-node action. It orchestrates the entire process of installing Node.js, configuring caching, authentication, and registering problem matchers. It is typically called directly from the action's entry point script.

```typescript
export async function run(): Promise<void>
```

```typescript
import {run} from './main';

// Called directly from setup-node.ts
await run();
```

--------------------------------

### Node.js Setup with Specific Version

Source: https://github.com/actions/setup-node/blob/main/_autodocs/configuration.md

Installs a precise Node.js version, such as '20.15.1'. Useful for ensuring exact environment reproducibility.

```yaml
-	uses:	actions/setup-node@v6
	with:
	node-version:	'20.15.1'
```

--------------------------------

### Usage Example

Source: https://github.com/actions/setup-node/blob/main/_autodocs/types.md

Demonstrates how to use the supportedPackageManagers to retrieve package manager information and get the cache folder path.

```APIDOC
## Usage

```typescript
import {supportedPackageManagers} from './cache-utils';

const npmInfo = supportedPackageManagers.npm;
const cacheFolder = await npmInfo.getCacheFolderPath();
// Returns: "/home/user/.npm"

// For yarn in monorepo
const yarnInfo = supportedPackageManagers.yarn;
const projectCache = await yarnInfo.getCacheFolderPath('/workspace/packages/app');
// Returns: "/home/user/.yarn/cache"
```
```

--------------------------------

### Node.js Setup with Caching

Source: https://github.com/actions/setup-node/blob/main/_autodocs/configuration.md

Installs Node.js version '20' and enables 'npm' package caching. Caching speeds up subsequent builds by reusing downloaded dependencies.

```yaml
-	uses:	actions/setup-node@v6
	with:
	node-version:	'20'
	cache:	'npm'
```

--------------------------------

### Node.js Setup with Nightly Build

Source: https://github.com/actions/setup-node/blob/main/_autodocs/configuration.md

Installs a 'nightly' build of Node.js version '22'. Use for testing the very latest, potentially unstable, features.

```yaml
-	uses:	actions/setup-node@v6
	with:
	node-version:	'22-nightly'
```

--------------------------------

### Node.js Setup with Registry Authentication

Source: https://github.com/actions/setup-node/blob/main/_autodocs/configuration.md

Installs Node.js version '20' and configures authentication for a private npm registry. Requires 'registry-url' and 'scope' for scoped packages.

```yaml
-	uses:	actions/setup-node@v6
	with:
	node-version:	'20'
	registry-url:	'https://npm.pkg.github.com'
	scope:	'@myorg'
```

--------------------------------

### Use private npm packages

Source: https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md

This example shows how to use private npm packages by configuring the actions/setup-node action to authenticate with a private registry. It includes steps to install dependencies while ignoring scripts for security and then rebuilding to run necessary post-install scripts.

```yaml
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
  with:
    node-version: '24.x'
    registry-url: 'https://registry.npmjs.org'
    package-manager-cache: false # Disable automatic npm dependency caching to reduce cache poisoning risk
# Skip post-install scripts here, as a malicious
# script could steal NODE_AUTH_TOKEN.
- run: npm ci --ignore-scripts
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
# `npm rebuild` will run all those post-install scripts for us.
- run: npm rebuild && npm run prepare --if-present
```

--------------------------------

### Node.js Setup with Private Mirror

Source: https://github.com/actions/setup-node/blob/main/_autodocs/configuration.md

Installs Node.js version '20' using a private mirror URL for downloading binaries. Requires 'mirror' and optionally 'mirror-token' for authentication.

```yaml
-	uses:	actions/setup-node@v6
	with:
	node-version:	'20'
	mirror:	'https://internal-node-mirror.company.com'
	mirror-token:	'${{ secrets.MIRROR_TOKEN }}'
```

--------------------------------

### Node.js Setup with V8 Canary Build

Source: https://github.com/actions/setup-node/blob/main/_autodocs/configuration.md

Installs the 'v8-canary' build of Node.js. This is for testing cutting-edge V8 JavaScript engine features.

```yaml
-	uses:	actions/setup-node@v6
	with:
	node-version:	'v8-canary'
```

--------------------------------

### Basic Node.js Version Installation

Source: https://github.com/actions/setup-node/blob/main/_autodocs/INDEX.md

Installs a specific Node.js version using the setup-node action. Ensure the 'node-version' input is correctly specified.

```yaml
- uses: actions/setup-node@v6
  with:
    node-version: '20'
```

--------------------------------

### run()

Source: https://github.com/actions/setup-node/blob/main/_autodocs/api-reference/main.md

The main entry point for the setup-node action. It orchestrates the installation of Node.js, caching of dependencies, configuration of authentication, and registration of problem matchers.

```APIDOC
## run()

### Description

Main entry point for the setup-node action. Orchestrates Node.js installation, caching, authentication configuration, and problem matcher registration.

### Method

N/A (This is a function within an action, not a direct HTTP endpoint)

### Endpoint

N/A

### Parameters

None

### Request Example

```typescript
import { run } from './main';

// Called directly from setup-node.ts
await run();
```

### Response

#### Success Response

`Promise<void>` - Indicates successful completion of the action.

#### Response Example

N/A (void return type)

### Configuration Sources

All configuration is read from GitHub Actions inputs:
- `node-version`: Semantic version spec (e.g., "20.x", "20.15.1")
- `node-version-file`: Path to version file (.nvmrc, package.json, .tool-versions)
- `architecture`: Target architecture ("x86", "x64", "arm64")
- `check-latest`: Boolean to check for latest matching version
- `token`: Authorization token for node-versions repository
- `registry-url`: NPM registry for authentication
- `cache`: Package manager for caching ("npm", "yarn", "pnpm")
- `package-manager-cache`: Boolean to enable/disable auto-detection of npm caching
- `cache-dependency-path`: Custom path(s) to lock files
- `mirror`: Alternative Node.js mirror URL
- `mirror-token`: Authorization for mirror
- `stable`: Whether to use stable releases (defaults to "true")

### Side Effects

- Modifies `PATH` environment variable via `core.addPath()`
- Saves state variables for post-action cache save
- Sets GitHub Actions outputs (`node-version`, `cache-hit`)
- Exports environment variables (`NPM_CONFIG_USERCONFIG`, `NODE_AUTH_TOKEN`)
- Registers problem matchers in GitHub Actions UI
- Logs informational and debug messages
```

--------------------------------

### CustomDistribution Example

Source: https://github.com/actions/setup-node/blob/main/_autodocs/api-reference/distributions.md

Example implementation of a custom Node.js distribution extending the BaseDistribution class. It provides a specific distribution URL and a placeholder for custom setup logic.

```typescript
class CustomDistribution extends BaseDistribution {
  protected getDistributionUrl(mirror: string): string {
    const url = mirror || 'https://custom-node-mirror.example.com';
    return `${url}/dist`;
  }

  public async setupNodeJs(): Promise<void> {
    // Custom implementation
  }
}
```

--------------------------------

### Node.js Setup with Release Candidate Build

Source: https://github.com/actions/setup-node/blob/main/_autodocs/configuration.md

Installs a release candidate (RC) build of Node.js version '22'. Use for testing upcoming stable releases.

```yaml
-	uses:	actions/setup-node@v6
	with:
	node-version:	'22-rc'
```

--------------------------------

### setup-node Execution Flow - Pre-step

Source: https://github.com/actions/setup-node/blob/main/_autodocs/README.md

Illustrates the sequence of operations performed by the setup-node action during its setup phase, from input processing to problem matcher registration.

```text
GitHub Actions input → Version resolution
                    → Resolve from file or direct input
                    ↓
               Distribution selection
                    → OfficialBuilds | NightlyNodejs | CanaryBuild | RcBuild
                    ↓
               Environment setup
                    → Check system tool cache
                    → Download if not cached
                    → Extract and cache locally
                    → Add to PATH
                    ↓
               Authentication config (if registry-url provided)
                    → Generate .npmrc
                    → Export environment variables
                    ↓
               Dependency cache restore
                    → Detect package manager
                    → Compute lock file hash
                    → Restore from cache if available
                    ↓
               Register problem matchers
                    → TypeScript compiler
                    → ESLint (stylish & compact)
```

--------------------------------

### Node.js Setup with LTS Version

Source: https://github.com/actions/setup-node/blob/main/_autodocs/configuration.md

Installs the latest Long-Term Support (LTS) version of Node.js, currently 'iron'. Use for stable, long-term projects.

```yaml
-	uses:	actions/setup-node@v6
	with:
	node-version:	'lts/iron'
```

--------------------------------

### Node.js Setup Checking for Latest Patch Version

Source: https://github.com/actions/setup-node/blob/main/_autodocs/configuration.md

Installs Node.js version '20' and enables 'check-latest'. This ensures the latest patch version satisfying the '20' spec is installed.

```yaml
-	uses:	actions/setup-node@v6
	with:
	node-version:	'20'
	check-latest:	true
```

--------------------------------

### Supported Package Managers Examples

Source: https://github.com/actions/setup-node/blob/main/_autodocs/types.md

Provides concrete examples of PackageManagerInfo configurations for npm, pnpm, and yarn.

```APIDOC
## Supported Package Managers

**npm:**
```typescript
{
  name: 'npm',
  lockFilePatterns: ['package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock'],
  getCacheFolderPath: () => // executes: npm config get cache
}
```

**pnpm:**
```typescript
{
  name: 'pnpm',
  lockFilePatterns: ['pnpm-lock.yaml'],
  getCacheFolderPath: () => // executes: pnpm store path --silent
}
```

**yarn:**
```typescript
{
  name: 'yarn',
  lockFilePatterns: ['yarn.lock'],
  getCacheFolderPath: (projectDir?) => // executes:
                                        // yarn 1.x: yarn cache dir
                                        // yarn 3.x+: yarn config get cacheFolder
}
```
```

--------------------------------

### Node.js Setup with Custom Cache Path

Source: https://github.com/actions/setup-node/blob/main/_autodocs/configuration.md

Installs Node.js version '20' with 'npm' caching, specifying a custom path for lock files. Supports glob patterns for complex project structures.

```yaml
-	uses:	actions/setup-node@v6
	with:
	node-version:	'20'
	cache:	'npm'
	cache-dependency-path:	'packages/*/package-lock.json'
```

--------------------------------

### Basic Node.js Setup in GitHub Actions

Source: https://github.com/actions/setup-node/blob/main/README.md

A basic workflow setup for Node.js using actions/setup-node. It checks out code, sets up Node.js version 24, disables automatic npm caching, and then runs npm ci and tests.

```yaml
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
  with:
    node-version: 24
    package-manager-cache: false # Disable automatic npm caching if not required
- run: npm ci
- run: npm test
```

--------------------------------

### OfficialBuilds.setupNodeJs

Source: https://github.com/actions/setup-node/blob/main/_autodocs/api-reference/distributions.md

Installs an official Node.js release. It supports various versioning syntaxes like LTS aliases (e.g., lts/iron, lts/*), latest syntax (e.g., current, latest), and manifest-based resolution. The method handles fetching version manifests, searching the tool cache, downloading from manifests with retry logic, and falling back to direct downloads from nodejs.org. It also adds the installed Node.js to the system's PATH.

```APIDOC
## OfficialBuilds.setupNodeJs()

### Description
Installs an official Node.js release with support for LTS aliases, latest syntax, and manifest-based resolution. It handles version resolution, downloading from manifests or directly, and updating the system's PATH.

### Method
```
public async setupNodeJs(): Promise<void>
```

### Behavior
1. Resolves LTS aliases (e.g., `lts/iron`, `lts/*`, `lts/-n`) by fetching manifests.
2. Handles latest syntax (e.g., `current`, `latest`, `node`) by selecting the newest version.
3. Optionally checks for the latest version if `checkLatest` is enabled.
4. Searches the hosted tool cache for the Node.js version.
5. Attempts to download from the manifest, using an auth token if provided, with HTTP retry logic.
6. Falls back to direct download from `nodejs.org` on failure.
7. Adds the installed Node.js to the system's PATH.

### Error Handling
- Catches HTTP 403/429 (rate limit) errors.
- Logs informative errors for various failure modes.
- Implements graceful fallback between manifest and direct download methods.

```

--------------------------------

### Node.js Installation with Registry Authentication

Source: https://github.com/actions/setup-node/blob/main/_autodocs/INDEX.md

Installs Node.js and configures authentication for a private npm registry. Provide the 'registry-url' and 'scope' for authentication.

```yaml
- uses: actions/setup-node@v6
  with:
    node-version: '20'
    registry-url: 'https://npm.pkg.github.com'
    scope: '@myorg'
```

--------------------------------

### Configure Node.js Setup with Options

Source: https://github.com/actions/setup-node/blob/main/README.md

Use this snippet to configure the setup-node action with various inputs. Specify the Node.js version, file for version, architecture, caching, and registry details.

```yaml
- uses: actions/setup-node@v6
  with:
    # Version Spec of the version to use in SemVer notation.
    # It also admits such aliases as lts/*, latest, nightly and canary builds
    # Examples: 12.x, 10.15.1, >=10.15.0, lts/Hydrogen, 16-nightly, latest, node
    node-version: ''

    # File containing the version Spec of the version to use.  Examples: package.json, .nvmrc, .node-version, .tool-versions.
    # If node-version and node-version-file are both provided the action will use version from node-version.
    node-version-file: ''

    # Set this option if you want the action to check for the latest available version
    # that satisfies the version spec.
    # It will only get affect for lts Nodejs versions (12.x, >=10.15.0, lts/Hydrogen).
    # Default: false
    check-latest: false

    # Target architecture for Node to use. Examples: x86, x64. Will use system architecture by default.
    # Default: ''. The action use system architecture by default
    architecture: ''

    # Used to pull node distributions from https://github.com/actions/node-versions.
    # Since there's a default, this is typically not supplied by the user.
    # When running this action on github.com, the default value is sufficient.
    # When running on GHES, you can pass a personal access token for github.com if you are experiencing rate limiting.
    #
    # We recommend using a service account with the least permissions necessary. Also
    # when generating a new PAT, select the least scopes necessary.
    #
    # [Learn more about creating and using encrypted secrets](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)
    #
    # Default: ${{ github.server_url == 'https://github.com' && github.token || '' }}
    token: ''

    # Used to specify a package manager for caching in the default directory. Supported values: npm, yarn, pnpm.
    # Package manager should be pre-installed
    # Default: ''
    cache: ''

    # Controls automatic caching for npm. By default, caching for npm is enabled if either the devEngines.packageManager field or the top-level packageManager field in package.json specifies npm and no explicit cache input is provided.
    # To disable automatic caching for npm, set package-manager-cache to false.
    # default: true
    package-manager-cache: true

    # Used to specify the path to a dependency file: package-lock.json, yarn.lock, etc.
    # It will generate hash from the target file for primary key. It works only If cache is specified.
    # Supports wildcards or a list of file names for caching multiple dependencies.
    # Default: ''
    cache-dependency-path: ''

    # Optional registry to set up for auth. Will set the registry in a project level .npmrc and .yarnrc file,
    # and set up auth to read in from env.NODE_AUTH_TOKEN.
    # Default: ''
    registry-url: ''

    # Optional scope for authenticating against scoped registries.
    # Will fall back to the repository owner when using the GitHub Packages registry (https://npm.pkg.github.com/).
    # Default: ''
    scope: ''

    # Optional mirror to download binaries from.
    # Artifacts need to match the official Node.js
    # Example:
    # V8 Canary Build: <mirror_url>/download/v8-canary
    # RC Build: <mirror_url>/download/rc
    # Official: Build <mirror_url>/dist
    # Nightly build: <mirror_url>/download/nightly
    # Default: ''
    mirror: ''

    # Optional mirror token.
    # The token will be used as a bearer token in the Authorization header
    # Default: ''
    mirror-token: ''
```

--------------------------------

### Usage Example: Get npm Cache Folder

Source: https://github.com/actions/setup-node/blob/main/_autodocs/types.md

Demonstrates how to import package manager information and use it to retrieve the default npm cache folder path.

```typescript
import {supportedPackageManagers} from './cache-utils';

const npmInfo = supportedPackageManagers.npm;
const cacheFolder = await npmInfo.getCacheFolderPath();
// Returns: "/home/user/.npm"
```

--------------------------------

### Install Exact V8 Canary Version

Source: https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md

Installs a precise V8 Canary build using its full version string.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    name: Node sample
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 'v24.0.0-v8-canary2025030537242e55ac'
          package-manager-cache: false # Disable automatic npm caching if not required
      - run: npm ci
      - run: npm test
```

--------------------------------

### Install an Exact Nightly Version

Source: https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md

Specify the exact nightly build version to install. Disable automatic npm caching if not required.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    name: Node sample
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24.0.0-nightly202505066102159fa1'
          package-manager-cache: false # Disable automatic npm caching if not required
      - run: npm ci
      - run: npm test
```

--------------------------------

### Example: Resolve Node.js Version Input

Source: https://github.com/actions/setup-node/blob/main/_autodocs/api-reference/main.md

Examples demonstrating how `resolveVersionInput` returns the specified version when `node-version` is provided, or the content of a `.nvmrc` file when `node-version-file` is used.

```typescript
// When node-version: "20.15.1" is provided
const version = resolveVersionInput(); // returns "20.15.1"

// When node-version-file: ".nvmrc" is provided
const version = resolveVersionInput(); // returns contents of .nvmrc file
```

--------------------------------

### Node.js Installation with Dependency Caching

Source: https://github.com/actions/setup-node/blob/main/_autodocs/INDEX.md

Installs a Node.js version and enables dependency caching for a specified package manager (e.g., npm). This can speed up build times by reusing cached dependencies.

```yaml
- uses: actions/setup-node@v6
  with:
    node-version: '20'
    cache: 'npm'
```

--------------------------------

### installer-factory.ts Exports

Source: https://github.com/actions/setup-node/blob/main/_autodocs/README.md

Factory for creating Node.js distribution installers.

```APIDOC
## getNodejsDistribution(installerOptions: NodeInputs): BaseDistribution

### Description
Creates and returns a Node.js distribution installer based on the provided options.

### Parameters
- **installerOptions** (NodeInputs) - Required - The installation configuration options.

### Returns
- `BaseDistribution` - An instance of a Node.js distribution installer.
```

--------------------------------

### Specify Latest or Current Node.js Release

Source: https://github.com/actions/setup-node/blob/main/_autodocs/configuration.md

Use 'latest', 'current', 'node', or '*' to install the most recent stable release of Node.js.

```yaml
- uses: actions/setup-node@v6
  with:
    node-version: 'latest'   # Latest release
```

```yaml
- uses: actions/setup-node@v6
  with:
    node-version: 'current'  # Current release (same as latest)
```

```yaml
- uses: actions/setup-node@v6
  with:
    node-version: 'node'     # Node release (same as latest)
```

```yaml
- uses: actions/setup-node@v6
  with:
    node-version: '*'        # Latest (same as above)
```

--------------------------------

### util.ts Exports

Source: https://github.com/actions/setup-node/blob/main/_autodocs/README.md

Utility functions for Node.js setup.

```APIDOC
## getNodeVersionFromFile(versionFilePath: string): string | null

### Description
Retrieves the Node.js version from a specified file.

### Parameters
- **versionFilePath** (string) - Required - The path to the file containing the Node.js version.

### Signature
`getNodeVersionFromFile(versionFilePath: string): string | null`

## printEnvDetailsAndSetOutput(): Promise<void>

### Description
Prints environment details and sets the action's output.

### Signature
`printEnvDetailsAndSetOutput(): Promise<void>`

## unique(): (value: unknown) => boolean

### Description
A filter function that returns only unique values.

### Signature
`unique(): (value: unknown) => boolean`
```

--------------------------------

### Usage Example for INodeVersionInfo

Source: https://github.com/actions/setup-node/blob/main/_autodocs/types.md

Demonstrates how to create an instance of `INodeVersionInfo` and use it with the `downloadNodejs` function. Ensure the `info` object accurately reflects the desired Node.js version and its properties.

```typescript
const info: INodeVersionInfo = {
  downloadUrl: 'https://nodejs.org/dist/v20.15.1/node-v20.15.1-linux-x64.tar.gz',
  resolvedVersion: '20.15.1',
  arch: 'x64',
  fileName: 'node-v20.15.1-linux-x64'
};

const toolPath = await distribution.downloadNodejs(info);
```

--------------------------------

### Install an RC Version

Source: https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md

Specify the exact release candidate version to install. Unlike nightly versions, range specifiers are not supported for RC versions. Disable automatic npm caching if not required.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    name: Node sample
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24.0.0-rc.4'
          package-manager-cache: false # Disable automatic npm caching if not required
      - run: npm ci
      - run: npm test
```

--------------------------------

### Monorepo Node.js Installation with Multiple Dependency Cache Paths

Source: https://github.com/actions/setup-node/blob/main/_autodocs/INDEX.md

Installs Node.js and configures dependency caching for a monorepo structure. Specify multiple lock file paths using 'cache-dependency-path' for different packages.

```yaml
- uses: actions/setup-node@v6
  with:
    node-version: '20'
    cache: 'npm'
    cache-dependency-path: |
      package-lock.json
      packages/*/package-lock.json
```

--------------------------------

### Handling Both Version Inputs Warning

Source: https://github.com/actions/setup-node/blob/main/_autodocs/errors.md

Illustrates a scenario where both 'node-version' and 'node-version-file' are specified, resulting in a warning. The example shows that only 'node-version' will be used.

```yaml
- uses: actions/setup-node@v6
  with:
    node-version: '20'
    node-version-file: '.nvmrc'  # Ignored
  # Warning shown, uses node-version value
```

--------------------------------

### Specify Node.js Prerelease Builds

Source: https://github.com/actions/setup-node/blob/main/_autodocs/configuration.md

Use specific identifiers to install prerelease versions like nightly, release candidates, or canaries.

```yaml
- uses: actions/setup-node@v6
  with:
    node-version: '22-nightly'  # Nightly build
```

```yaml
- uses: actions/setup-node@v6
  with:
    node-version: '22-rc'       # Release candidate
```

```yaml
- uses: actions/setup-node@v6
  with:
    node-version: 'v8-canary'   # V8 canary build
```

--------------------------------

### Specify Exact Node.js Version

Source: https://github.com/actions/setup-node/blob/main/_autodocs/configuration.md

Use an exact version string to ensure a specific Node.js version is installed.

```yaml
- uses: actions/setup-node@v6
  with:
    node-version: '20.15.1'  # Exact version
```

--------------------------------

### downloadNodejs Method

Source: https://github.com/actions/setup-node/blob/main/_autodocs/api-reference/distributions.md

Downloads and extracts the Node.js binary from a given URL. Returns the path to the cached Node.js installation. Throws an error on download or extraction failures.

```typescript
protected async downloadNodejs(info: INodeVersionInfo): Promise<string>
```

--------------------------------

### Handle HTTP Client Errors with actions/setup-node

Source: https://github.com/actions/setup-node/blob/main/_autodocs/errors.md

This example shows how to use the actions/setup-node action. If a GitHub rate limit is hit, it automatically falls back to a direct download. Provide a PAT for a higher rate limit.

```yaml
- uses: actions/setup-node@v6
  with:
    node-version: '20'
    # GitHub rate limit hit
  # Logged: "Received HTTP status code 429. This usually indicates the rate limit has been exceeded"
  # Automatically falls back to nodejs.org

- uses: actions/setup-node@v6
  with:
    node-version: '20'
    token: ${{ secrets.GH_TOKEN }}  # Provide PAT for higher rate limit
```

--------------------------------

### Usage Example: Get yarn Cache Folder in Monorepo

Source: https://github.com/actions/setup-node/blob/main/_autodocs/types.md

Shows how to get the yarn cache folder path for a specific project directory within a monorepo structure.

```typescript
// For yarn in monorepo
const yarnInfo = supportedPackageManagers.yarn;
const projectCache = await yarnInfo.getCacheFolderPath('/workspace/packages/app');
// Returns: "/home/user/.yarn/cache"
```

--------------------------------

### Handle Extraction Failures with actions/setup-node

Source: https://github.com/actions/setup-node/blob/main/_autodocs/errors.md

This example demonstrates the use of actions/setup-node. Errors during the extraction phase will be shown in the logs. Ensure sufficient disk space and correct permissions for the temporary directory.

```yaml
- uses: actions/setup-node@v6
  with:
    node-version: '20'
  # Error in extraction phase shown in logs
  # Check available disk space and permissions
```

--------------------------------

### setupNodeJs Method

Source: https://github.com/actions/setup-node/blob/main/_autodocs/api-reference/distributions.md

Orchestrates the Node.js installation process, including checking the latest version, searching the tool cache, downloading if necessary, and adding the Node.js binary to the system's PATH.

```typescript
public async setupNodeJs(): Promise<void>
```

--------------------------------

### setup-node Execution Flow - Post-step

Source: https://github.com/actions/setup-node/blob/main/_autodocs/README.md

Details the cache-save phase of the setup-node action, focusing on retrieving state and saving the cache if a cache miss occurred.

```text
Retrieve state from pre-step
                    → Package manager
                    → Cache paths
                    → Cache keys
                    ↓
Check if cache hit occurred
                    ↓
If miss: Save cache
    → Call @actions/cache.saveCache()
    → Save with primary key
```

--------------------------------

### Setup Node using a Version File

Source: https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md

Specify the Node.js version by referencing a version file like `.nvmrc` using the `node-version-file` input. The action searches for this file relative to the repository root.

```yaml
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
  with:
    node-version-file: '.nvmrc'
    package-manager-cache: false # Disable automatic npm caching if not required
- run: npm ci
- run: npm test
```

--------------------------------

### Node.js Setup Disabling Automatic Caching

Source: https://github.com/actions/setup-node/blob/main/_autodocs/configuration.md

Installs Node.js version '20' but disables automatic package manager caching. Use when manual cache management is preferred or automatic detection is problematic.

```yaml
-	uses:	actions/setup-node@v6
	with:
	node-version:	'20'
	package-manager-cache:	false
```

--------------------------------

### Matrix Build with Multiple OS, Node Versions, and Architectures

Source: https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md

Configure a GitHub Actions workflow to build and test Node.js projects across various operating systems, Node.js versions, and architectures using a matrix strategy. This example demonstrates how to include specific overrides for different environments.

```yaml
jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os:
          - ubuntu-latest
          - macos-latest
          - windows-latest
        node_version:
          - 20
          - 22
          - 24
        architecture:
          - x64
        # an extra windows-x86 run:
        include:
          - os: windows-latest
            node_version: 24
            architecture: x86
    name: Node ${{ matrix.node_version }} - ${{ matrix.architecture }} on ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v6
      - name: Setup node
        uses: actions/setup-node@v6
        with:
          node-version: ${{ matrix.node_version }}
          architecture: ${{ matrix.architecture }}
          package-manager-cache: false # Disable automatic npm caching if not required
      - run: npm ci
      - run: npm test
```

--------------------------------

### Catching Registry Configuration Errors

Source: https://github.com/actions/setup-node/blob/main/_autodocs/errors.md

Demonstrates how to configure setup-node with an invalid registry URL to trigger an authentication error. It also shows a correct configuration and a subsequent npm ci command that would fail if the authentication token is missing.

```yaml
- uses: actions/setup-node@v6
  with:
    node-version: '20'
    registry-url: 'not-a-url'
  # May fail silently or in npm commands
  # npm ci will fail with auth error if token missing

env:
  NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

- uses: actions/setup-node@v6
  with:
    node-version: '20'
    registry-url: 'https://npm.pkg.github.com'

- run: npm ci  # Fails if NODE_AUTH_TOKEN not set
```

--------------------------------

### NodeInputs Interface

Source: https://github.com/actions/setup-node/blob/main/_autodocs/types.md

The `NodeInputs` interface defines the configuration object for controlling Node.js installation. It specifies version, architecture, authentication, and other installation preferences.

```APIDOC
## NodeInputs Interface

### Description
Configuration object passed to distribution classes to control Node.js installation behavior.

### Fields

| Field | Type | Required | Description |
|---|---|---|---|
| versionSpec | string | Yes | Semantic version specification (e.g., "20.x", "lts/iron", "nightly", "v8-canary") |
| arch | string | Yes | Target architecture ("x86", "x64", "arm64", "arm") |
| auth | string | No | Authorization header value for node-versions repository (format: "token {token}") |
| checkLatest | boolean | Yes | Whether to check for latest version matching the spec |
| stable | boolean | Yes | Whether to prefer stable releases (used for LTS manifest lookups) |
| mirror | string | Yes | Alternative Node.js mirror URL or empty string for default |
| mirrorToken | string | Yes | Authorization bearer token for mirror access or empty string |

### Usage

```typescript
import {getNodejsDistribution} from './distributions/installer-factory';

const nodeInputs: NodeInputs = {
  versionSpec: '20.15.1',
  arch: 'x64',
  auth: 'token ghp_xxxx',
  checkLatest: false,
  stable: true,
  mirror: '',
  mirrorToken: ''
};

const distribution = getNodejsDistribution(nodeInputs);
await distribution.setupNodeJs();
```
```

--------------------------------

### Setup Node.js with NPM Dependency Caching (YAML)

Source: https://github.com/actions/setup-node/blob/main/docs/adrs/0000-caching-dependencies.md

This YAML snippet demonstrates how to configure the actions/setup-node action to enable caching for NPM dependencies. It checks out the code, sets up the Node.js environment, and specifies 'npm' for caching.

```yaml
steps:
- uses: actions/checkout@v2
- uses: actions/setup-node@v2
  with:
    node-version: '14'
    cache: npm
```

--------------------------------

### Install V8 Canary Build for Major Node Version

Source: https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md

Installs the latest V8 Canary release for a major Node.js version (e.g., 24).

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    name: Node sample
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24-v8-canary' # it will install the latest v8 canary release for node 24
          package-manager-cache: false # Disable automatic npm caching if not required
      - run: npm ci
      - run: npm test
```

--------------------------------

### Setup Node with GHES and Token

Source: https://github.com/actions/setup-node/blob/main/README.md

Use the actions/setup-node action on GitHub Enterprise Server (GHES) with a personal access token to increase API rate limits when downloading Node.js distributions. This is useful when the runner cannot access github.com directly or to avoid unauthenticated request limits.

```yaml
uses: actions/setup-node@v6
with:
  token: ${{ secrets.GH_DOTCOM_TOKEN }}
  node-version: 24
  package-manager-cache: false # Disable automatic npm caching if not required
```

--------------------------------

### Install V8 Canary Build for Specific Node Version

Source: https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md

Installs the latest V8 Canary release for a specific Node.js version (e.g., 24.0.0).

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    name: Node sample
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24.0.0-v8-canary' # it will install the latest v8 canary release for node 24.0.0
          package-manager-cache: false # Disable automatic npm caching if not required
      - run: npm ci
      - run: npm test
```

--------------------------------

### Check Node.js Setup Cache Hit Status

Source: https://github.com/actions/setup-node/blob/main/_autodocs/INDEX.md

This snippet demonstrates how to use the actions/setup-node action to set up Node.js and then check if the cache was successfully hit. It uses the 'npm' package manager and caches the dependencies.

```yaml
- uses: actions/setup-node@v6
  id: setup
  with:
    node-version: '20'
    cache: 'npm'

- run: echo "Cache hit: ${{ steps.setup.outputs.cache-hit }}"
```

--------------------------------

### Retrieve Installed Node.js Version Output

Source: https://github.com/actions/setup-node/blob/main/_autodocs/configuration.md

Access the installed Node.js version using the 'node-version' output. This is useful for verifying the correct Node.js environment is set up.

```yaml
steps:
  - uses: actions/setup-node@v6
    id: setup
    with:
      node-version: '20'
  
  - run: echo "Installed Node ${{ steps.setup.outputs.node-version }}"
```

--------------------------------

### Install Nightly Build for a Major Version

Source: https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md

Specify a major version with '-nightly' to install the latest nightly release for that major version. Disable automatic npm caching if not required.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    name: Node sample
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24-nightly' # it will install the latest nightly release for node 24
          package-manager-cache: false # Disable automatic npm caching if not required
      - run: npm ci
      - run: npm test
```

--------------------------------

### Install Nightly Build for a Specific Version

Source: https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md

Specify a full version number with '-nightly' to install the latest nightly release for that specific version. Disable automatic npm caching if not required.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    name: Node sample
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24.0.0-nightly' # it will install the latest nightly release for node 24.0.0
          package-manager-cache: false # Disable automatic npm caching if not required
      - run: npm ci
      - run: npm test
```

--------------------------------

### Setup Node.js with Yarn Dependency Caching (YAML)

Source: https://github.com/actions/setup-node/blob/main/docs/adrs/0000-caching-dependencies.md

This YAML snippet shows how to configure the actions/setup-node action to enable caching for Yarn dependencies. It includes checking out code, setting up Node.js, and setting the 'cache' input to 'yarn'.

```yaml
steps:
- uses: actions/checkout@v2
- uses: actions/setup-node@v2
  with:
    node-version: '14'
    cache: yarn
```

--------------------------------

### Disable Caching with npm Install

Source: https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md

Use this configuration when you are not using a lockfile and need to explicitly disable the caching mechanism provided by actions/setup-node. This ensures that package installations do not rely on a cache that would be invalidated without a lockfile.

```yaml
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
  with:
    node-version: '24'
    package-manager-cache: false # Explicitly disable caching if you don't have a lockfile
- run: npm install
- run: npm test
```

--------------------------------

### Enable Debug Logging for setup-node

Source: https://github.com/actions/setup-node/blob/main/_autodocs/errors.md

Set the ACTIONS_STEP_DEBUG environment variable to true to enable detailed debug output for the setup-node action. This is useful for diagnosing issues with Node.js version resolution, caching, and downloads.

```yaml
env:
  ACTIONS_STEP_DEBUG: true

steps:
  - uses: actions/setup-node@v6
    with:
      node-version: '20'
```

--------------------------------

### Publish to npmjs and GPR with npm

Source: https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md

Set up Node.js and publish packages to both npmjs.org and GitHub Packages (GPR) within the same workflow. This example shows how to configure the action for different registry URLs and authentication tokens.

```yaml
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
  with:
    node-version: '24.x'
    registry-url: 'https://registry.npmjs.org'
    package-manager-cache: false # Disable automatic npm dependency caching to reduce cache poisoning risk
- run: npm ci
- run: npm publish
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
- uses: actions/setup-node@v6
  with:
    registry-url: 'https://npm.pkg.github.com'
    package-manager-cache: false # Disable automatic npm dependency caching to reduce cache poisoning risk
- run: npm publish
  env:
    NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Setup Node with Check Latest Enabled

Source: https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md

Use `check-latest: true` to ensure the action always attempts to download the most up-to-date Node.js version. This can have performance implications compared to using cached versions.

```yaml
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
  with:
    node-version: '24'
    check-latest: true
    package-manager-cache: false # Disable automatic npm caching if not required
- run: npm ci
- run: npm test
```