How to setup GitHub Actions for Node project?

    - uses: actions/setup-node@v4

setup-node

Set up your GitHub Actions workflow with a specific version of node.js

What is actions/setup-node?​

actions/setup-node@v4 streamlines working with Node.js in our GitHub Actions workflows. It offers some useful functionalities that can greatly improve our CI/CD processes.

Key Features:

• Node.js Version Management: It can download and cache the Node.js version specified in your workflow and automatically add it to the PATH.
• Dependency Caching: Supports caching for npm, yarn, or pnpm dependencies which speeds up the installation process in subsequent runs.
• Error Handling: It registers problem matchers for Node.js to handle error outputs more effectively.
• Authentication Configurations: The action can configure authentication for npm or GitHub Package Registry to manage private packages. Usage:

You can specify the Node.js version directly or reference a version file in your repository. It supports semantic versioning and even labels like LTS (Long Term Support) versions.

For dependency management, specify a cache option and provide paths to your dependency files if they’re not at the root level. It also allows setting up registry URLs and tokens for authentication, which is handy if we’re dealing with private registries or need to avoid rate limits on public ones.

How to Work with Lockfiles?​

For NPM:​

• Always commit package-lock.json.
• Use npm ci for installations in CI environments to ensure consistency based on the lockfile.

For Yarn:​

• Always commit yarn.lock.
• Use yarn install --immutable for installations to

For PNPM:​

• Always commit pnpm-lock.yaml.
• On CI environments, use pnpm install --frozen-lockfile to make sure the installation adheres strictly to the lockfile, preventing any updates to it.

How to Check the Latest Version with setup-node Action?​

The check-latest flag in the setup-node action controls whether the action should look for the latest Node.js version that satisfies the semantic versioning requirements you've set:

• When set to false, the action looks in the local cache first. If it doesn't find a match, it tries to download the required Node.js version, prioritizing Long Term Support (LTS) versions from the node-versions releases. If both attempts fail, it defaults to downloading directly from the Node.js distribution site.
• When set to true, the action always tries to download the latest version available, even if it means bypassing the local cache. This ensures you're using the most up-to-date version, but it might slow down your workflow because downloads take longer than using cached versions.

Here’s how you might configure this in your workflow file:

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '16'
    check-latest: true
- run: npm ci
- run: npm test

How to Use a Node Version File in setup-node Action?​

The node-version-file option lets you specify a path to a file that contains the Node.js version your project uses. This can be a .nvmrc, .node-version, .tool-versions, or a specific field in package.json. If both node-version and node-version-file are provided, the action prioritizes the node-version setting.

For example:

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version-file: '.nvmrc'
- run: npm ci
- run: npm test

How to Specify Architecture with setup-node Action?​

You can choose the architecture (like x86, x64, ARM) for the Node.js environment. This is useful if your project needs to run on specific hardware configurations. Make sure to specify the node-version along with the architecture.

Example setup for a specific architecture:

jobs:
  build:
    runs-on: windows-latest
    name: Node sample
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '14'
          architecture: 'x64'
      - run: npm ci
      - run: npm test

How to Install V8 Canary or Nightly Node.js Versions?​

If you need to test against cutting-edge features, you might want to install V8 Canary or nightly versions of Node.js. These versions are at the forefront of Node development, offering new features and updates before they are officially released.

Example of installing a V8 Canary version:

jobs:
  build:
    runs-on: ubuntu-latest
    name: Node sample
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20.0.0-v8-canary'
      - run: npm ci
      - run: npm test

Example of installing a nightly version:

jobs:
  build:
    runs-on: ubuntu-latest
    name: Node sample
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '16-nightly'
      - run: npm ci
      - run: npm test

Here's how to manage caching of package data when using the setup-node action in your GitHub workflows, which can help speed up build times by reusing the stored data across runs.

How to Cache npm Dependencies Using setup-node?​

When setting up your GitHub Actions workflow with npm, you can enable caching to save time on future builds. Here’s a basic example:

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '14'
    cache: 'npm'
- run: npm ci
- run: npm test

In this setup:

• The cache: 'npm' option enables caching for npm dependencies.
• npm ci is used for installation to ensure that the exact versions from package-lock.json are installed.

How to Cache Dependencies in Monorepos​

For monorepos or projects with dependencies in multiple directories, you can specify paths to different lock files using the cache-dependency-path:

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '14'
    cache: 'npm'
    cache-dependency-path: 'subdir/package-lock.json'
- run: npm ci
- run: npm test

This configuration tells the setup-node action to cache the npm dependencies based on the lock file located in the specified subdirectory.

How to Use Wildcard Patterns to Cache Dependencies?​

If you need to cache dependencies from multiple locations within your repository, you can use wildcard patterns to specify multiple lock files:

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '14'
    cache: 'npm'
    cache-dependency-path: '**/package-lock.json'
- run: npm ci
- run: npm test

This approach will cache all npm dependencies that match the given wildcard pattern, making it ideal for large projects with multiple Node.js applications.

How to Cache yarn Dependencies​

For projects using Yarn, you can cache dependencies by specifying cache: 'yarn':

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '14'
    cache: 'yarn'
- run: yarn install --frozen-lockfile
- run: yarn test

This setup caches the yarn dependencies and uses the --frozen-lockfile option to prevent updates to the yarn.lock file during installation, ensuring consistent dependency resolution.

How to Cache pnpm Dependencies?​

For projects using pnpm, caching can be configured similarly:

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '14'
    cache: 'pnpm'
- run: pnpm install
- run: pnpm test

This configuration enables caching for pnpm and uses the default behavior of pnpm install, which respects the lock file similarly to npm ci.

These examples show how to efficiently use caching in your GitHub Actions workflows to speed up builds and ensure consistency across installations.

These configurations allow you to use very specific or the very latest versions of Node.js for testing or development purposes, helping to ensure compatibility or to pioneer new technologies.