> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/node

Easily install Node.js and its package managers (npm, yarn, yarn-berry, pnpm, bun). Best of all, install your packages with caching enabled by default. Supports Linux x86_64, MacOS, and Arm64 V8.


## Commands

### install

Install custom versions of Node.js, and optionally NPM/pnpm/Yarn, in any
execution environment (Docker/Linux, macOS, machine) that does not have
it preinstalled.

Recommendation: It is highly recommended to utilize an environment such as Docker with Node preinstalled.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `bun-version` | string |  | Pick a version of Bun to install (if no version is specified, the latest stable version will be installed): https://github.com/oven-sh/bun/releases
 |
| `install-bun` | boolean | false | Install Bun? |
| `install-pnpm` | boolean | false | Install pnpm? |
| `install-yarn` | boolean | false | Install Yarn? |
| `node-version` | string |  | Specify the full version tag to install. To install the latest version, set the version to `latest`. If unspecified, the version listed in .nvmrc or .node-version will be installed. If no .nvmrc file and .node-version file exists the active LTS version of Node.js will be installed by default. For a full list of releases, see the following: https://nodejs.org/en/download/releases
 |
| `nvm-cache-key` | string | nvm-v1-cache | Cache key to use when downloading nodejs. This is only used when use-nvm-cache is set to true. Defaults to nvm-v1-cache, update this value if you need to restart the cache. The node-version is added by default at the end of the cache key. If you are using multiple executors, add the executor as part of the key.
 |
| `pnpm-version` | string |  | Pick a version of pnpm to install (if no version is specified, the latest stable version will be installed): https://github.com/pnpm/pnpm/releases
 |
| `use-nvm-cache` | boolean | true | Indicates if cache would be used when installing nodejs, this would reduce the amount of errors when downloading the binaries. Defaults to true.
 |
| `yarn-version` | string |  | Pick a version of Yarn to install (if no version is specified, the latest stable version will be installed): https://github.com/yarnpkg/yarn/releases
 |

### install-bun

Install a custom version of the Bun package manager


| Parameter | Type | Default | Description |
|---|---|---|---|
| `version` | string |  | Pick a version of Bun to install (if no version is specified, the latest stable version will be installed): https://github.com/oven-sh/bun/releases
 |

### install-packages

Install your Node packages with automated caching and best practices applied. Requires lock file.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `app-dir` | string | . | Path to the directory containing your package.json file. Not needed if package.json lives in the root. |
| `cache-only-lockfile` | boolean | true | If true, package.json will be ignored in the cache key. Useful for projects where package.json changes do not always invalidate dependencies.
Note: package.json will still be the final fallback key incase a project is not configured with a lock file.
 |
| `cache-path` | string |  | By default, this orb will cache '~/.npm' for npm, '~/.bun/install/cache' for bun, and 'node_modules' for yarn/pnpm. Override which path to cache with this parameter.
The cache will be ignored when using npm ci, as the command doesn't benefit from cache.
 |
| `cache-version` | string | v1 | Change the default cache version if you need to clear the cache for any reason. |
| `check-cache` | enum | never | Yarn berry only for Zero install support -
Use 'always' to always --check-cache argument to yarn install.
Use 'detect' to enable caching of yarn.lock and to only add when required.
 |
| `include-branch-in-cache-key` | boolean | false | If true, this cache bucket will only apply to jobs within the same branch.
 |
| `override-ci-command` | string |  | By default, packages will be installed with "npm ci", "yarn install --frozen-lockfile", "yarn install --immutable", "pnpm install --frozen-lockfile", or "bun install --frozen-lockfile".
Optionally supply a custom package installation command, with any additional flags needed.
When the command npm ci is used, no cache will be used, as the command doesn't benefit from it.
 |
| `pkg-manager` | enum | npm | Select the default node package manager to use. NPM v5+ Required.
To use yarn-berry your package.json must have packageManager set to a yarn berry version, otherwise it will use old yarn.
 |
| `with-cache` | boolean | true | Cache your node packages automatically for faster install times.
Cache will be ignored when using npm ci.
 |

### install-pnpm

Install a custom version of the pnpm package manager


| Parameter | Type | Default | Description |
|---|---|---|---|
| `version` | string |  | Pick a version of pnpm to install (if no version is specified, the latest stable version will be installed): https://github.com/pnpm/pnpm/releases
 |

### install-yarn

Install a custom version of the Yarn package manager. This only works for yarn classic versions, if you want to use yarn-berry, use the install-packages directly and select yarn-berry as pkg-manager.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `version` | string |  | Pick a version of Yarn to install (if no version is specified, the latest stable version will be installed): https://github.com/yarnpkg/yarn/releases
 |

## Jobs

### run

Simple drop-in job to run commands for your Node.js application automatically.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `app-dir` | string | ~/project | Path to the directory containing your package.json file. Not needed if package.json lives in the root. |
| `artifacts-path` | string |  | Path to a file or directory to upload to artifacts after running the script.
 |
| `bun-run` | string |  | The name of the script within your package.json which you would like to run. |
| `cache-only-lockfile` | boolean | true | If true, package.json will be ignored in the cache key. Useful for projects where package.json changes do not always invalidate dependencies.
Note: package.json will still be the final fallback key incase a project is not configured with a lock file.
 |
| `cache-path` | string |  | By default, this orb will utilize 'npm ci' and cache the '~/.npm' directory. Override which path to cache with this parameter.
The cache will be ignored when using npm ci, as the command doesn't benefit from cache.
 |
| `cache-version` | string | v1 | Change the default cache version if you need to clear the cache for any reason. |
| `check-cache` | enum | never | Yarn berry only for Zero install support -
Use 'always' to always --check-cache argument to yarn install.
Use 'detect' to enable caching of yarn.lock and to only add when required.
 |
| `executor` | executor | default | The name of executor to use. |
| `include-branch-in-cache-key` | boolean | false | If true, this cache bucket will only apply to jobs within the same branch.
 |
| `npm-run` | string |  | The name of the script within your package.json which you would like to run. |
| `override-ci-command` | string |  | By default, packages will be installed with "npm ci" or "yarn install --frozen-lockfile".
Optionally supply a custom package installation command, with any additional flags needed.
 |
| `parallelism` | integer | 1 | The number of parallel jobs to run. See https://circleci.com/docs/parallelism-faster-jobs/ |
| `pkg-manager` | enum | npm | Select the default node package manager to use. |
| `pnpm-run` | string |  | The name of the script within your package.json which you would like to run. |
| `post_install_steps` | steps |  | Provide any optional steps you would like to run after installing the node dependencies. |
| `setup` | steps |  | Provide any optional steps you would like to run prior to installing the node dependencies. This is a good place to install global modules. |
| `with-cache` | boolean | true | Cache your node packages automatically for faster install times.
Cache will be ignored when using npm ci.
 |
| `yarn-run` | string |  | The name of the script within your package.json which you would like to run. |

### test

Simple drop-in job to test your Node.js application automatically.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `app-dir` | string | ~/project | Path to the directory containing your package.json file. Not needed if package.json lives in the root. |
| `cache-only-lockfile` | boolean | true | If true, package.json will be ignored in the cache key. Useful for projects where package.json changes do not always invalidate dependencies.
Note: package.json will still be the final fallback key incase a project is not configured with a lock file.
 |
| `cache-path` | string |  | By default, this orb will utilize 'npm ci' and cache the '~/.npm' directory. Override which path to cache with this parameter.
The cache will be ignored when using npm ci, as the command doesn't benefit from cache.
 |
| `cache-version` | string | v1 | Change the default cache version if you need to clear the cache for any reason. |
| `check-cache` | enum | never | Yarn berry only for Zero install support -
Use 'always' to always --check-cache argument to yarn install.
Use 'detect' to enable caching of yarn.lock and to only add when required.
 |
| `executor` | executor | default | The name of executor to use. |
| `include-branch-in-cache-key` | boolean | false | If true, this cache bucket will only apply to jobs within the same branch.
 |
| `override-ci-command` | string |  | By default, packages will be installed with "npm ci" or "yarn install --frozen-lockfile".
Optionally supply a custom package installation command, with any additional flags needed.
 |
| `parallelism` | integer | 1 | The number of parallel jobs to run. See https://circleci.com/docs/parallelism-faster-jobs/ |
| `pkg-manager` | enum | npm | Select the default node package manager to use. |
| `post_install_steps` | steps |  | Provide any optional steps you would like to run after installing the node dependencies. |
| `run-command` | string | test | The name of the script within your package.json which will run your tests. |
| `setup` | steps |  | Provide any optional steps you would like to run prior to installing the node dependencies. This is a good place to install global modules. |
| `test-coverage-path` | string |  | Set this to the location where code coverage files will be placed after running tests.
The code coverage files will be uploaded to artifacts for this workflow.
 |
| `test-results-for` | enum | other | Testing framework your project uses.
If this is set to jest or mocha, test results will be automatically produced. When using jest, the jest-junit package is required as a dev dependency. See https://github.com/jest-community/jest-junit for more information.
When using mocha, the mocha-junit-reporter and mocha-multi packages are required as dev dependency. See https://github.com/michaelleeallen/mocha-junit-reporter and https://github.com/glenjamin/mocha-multi for more information.
When using bun with pkg-manager: bun, Bun's native test runner will be used with built-in JUnit output.
 |
| `test-results-path` | string |  | If you use test-results-for, this will be configured automatically.
If you configure test results yourself (for example in your node config files) set this to the location that you write them to, and they will be uploaded.
 |
| `with-cache` | boolean | true | Cache your node packages automatically for faster install times.
Cache will be ignored when using npm ci.
 |

## Executors

### default

Select the version of Node.js to use. Uses CircleCI's highly cached convenience images built for CI.
Any available tag from this list can be used: https://hub.docker.com/r/cimg/node/tags


| Parameter | Type | Default | Description |
|---|---|---|---|
| `resource_class` | enum | large | Configure the executor resource class |
| `tag` | string | lts | Pick a specific cimg/node image version tag: https://hub.docker.com/r/cimg/node
 |

## Examples

### bun_install

By default, the "install-packages" command will attempt to utilize "bun install". The command can however be overwritten to support an alternative package install command such as "bun install --frozen-lockfile".


```yaml
version: '2.1'
orbs:
  node: circleci/node@x.y
jobs:
  test:
    executor: node/default
    steps:
      - checkout
      - node/install-bun:
          version: 1.2.22
      - node/install-packages:
          pkg-manager: bun
      - run: bun run test
workflows:
  test_my_app:
    jobs:
      - test
```

### install_nodejs

Download and install any version of Node.js. Optionally installs Yarn with a parameter. You may use the default executor of this orb for a Node execution environment as well.

Recommendation: It is highly recommended to utilize an environment such as Docker with Node preinstalled.


```yaml
version: '2.1'
orbs:
  node: circleci/node@x.y
jobs:
  install-node-example:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - node/install:
          install-yarn: true
          node-version: '16.13'
      - run: node --version
workflows:
  test_my_app:
    jobs:
      - install-node-example
```

### jest_test_results

Run tests with jest and produce and upload test reports.
This assumes that you have configured your project to invoke jest as your test script and that you have the jest-junit package in your dev dependencies.


```yaml
version: '2.1'
orbs:
  node: circleci/node@x.y
workflows:
  test:
    jobs:
      - node/test:
          test-results-for: jest
```

### mocha_test_results

Run tests with mocha and produce and upload test reports.
This assumes that you have configured your project to invoke mocha as your test script and that you have the mocha-junit-reporter and mocha-multi packages in your dev dependencies.


```yaml
version: '2.1'
orbs:
  node: circleci/node@x.y
workflows:
  test:
    jobs:
      - node/test:
          executor:
            name: node/default
          test-results-for: mocha
```

### node_bun_run

Drop-in solution to automatically run custom bun commands for your Node.js applications.
This job will automatically download your code into any version node environment, install your dependencies with caching enabled, and execute your custom bun script.


```yaml
version: '2.1'
orbs:
  node: circleci/node@x.y
workflows:
  run-bun-command:
    jobs:
      - node/run:
          bun-run: build
          executor:
            name: node/default
          pkg-manager: bun
          setup:
            - node/install-bun
```

### node_npm_run

Drop-in solution to automatically run custom npm commands for your Node.js applications.
This job will automatically download your code into any version node environment, install your dependencies with caching enabled, and execute your custom npm script.


```yaml
version: '2.1'
orbs:
  node: circleci/node@x.y
workflows:
  run-npm-command:
    jobs:
      - node/run:
          executor:
            name: node/default
          npm-run: build
```

### node_pnpm_run

Drop-in solution to automatically run custom pnpm commands for your Node.js applications.
This job will automatically download your code into any version node environment, install your dependencies with caching enabled, and execute your custom pnpm script.


```yaml
version: '2.1'
orbs:
  node: circleci/node@x.y
workflows:
  run-npm-command:
    jobs:
      - node/run:
          executor:
            name: node/default
          pnpm-run: build
```

### node_test_and_deploy

Drop-in solution to automatically test your Node.js applications. This job will automatically download your code into any version node environment, install your dependencies with caching enabled, and execute your testing script.
This example shows how easily with two orbs you can test your Node application and automatically deploy to Heroku when successful, and on the master branch.


```yaml
version: '2.1'
orbs:
  heroku: circleci/heroku@x.y
  node: circleci/node@x.y
workflows:
  test-and-deploy:
    jobs:
      - node/test:
          executor:
            name: node/default
      - heroku/deploy-via-git:
          filters:
            branches:
              only:
                - master
          requires:
            - node/test
```

### node_yarn_run

Drop-in solution to automatically run custom yarn commands for your Node.js applications.
This job will automatically download your code into any version node environment, install your dependencies with caching enabled, and execute your custom yarn script.


```yaml
version: '2.1'
orbs:
  node: circleci/node@x.y
workflows:
  run-npm-command:
    jobs:
      - node/run:
          executor:
            name: node/default
          yarn-run: build
```

### npm_install

By default, the "install-packages" command will attempt to utilize "npm ci". The command can however be overwritten to support an alternative package install command such as "npm install".


```yaml
version: '2.1'
orbs:
  node: circleci/node@x.y
jobs:
  test:
    executor: node/default
    steps:
      - checkout
      - run: sudo npm install -g npm@latest
      - node/install-packages:
          cache-path: ~/project/node_modules
          override-ci-command: npm install
      - run: npm run test
workflows:
  test_my_app:
    jobs:
      - test
```

### pnpm_install

By default, the "install-packages" command will attempt to utilize "pnpm i --frozen-lockfile". The command can however be overwritten to support an alternative package install command such as "pnpm install".


```yaml
version: '2.1'
orbs:
  node: circleci/node@x.y
jobs:
  test:
    executor: node/default
    steps:
      - checkout
      - run: sudo npm install -g npm@latest
      - node/install-packages:
          override-ci-command: pnpm i
          pkg-manager: pnpm
      - run: pnpm run test
workflows:
  test_my_app:
    jobs:
      - test
```

### run_matrix_testing

Easily test your application against multiple versions of Node.js in just a few lines. This example uses "Matrix" jobs to call the same node/test job multiple times at once, each with the Node version we have specified.

Read more here: https://circleci.com/blog/you-are-what-you-git-how-your-vcs-branching-model-affects-your-delivery-cadence/


```yaml
version: '2.1'
orbs:
  node: circleci/node@x.y
workflows:
  matrix-tests:
    jobs:
      - node/test:
          matrix:
            parameters:
              executor:
                - node13
                - node12
                - node10
```

### run_tests_with_bun

Manual approach for running Bun's native test runner. This example shows how to manually configure Bun tests with JUnit output.
For automatic test result collection, consider using the node/test job with test-results-for: bun (see test_with_bun_native.yml example).
The "bun install" command will automatically be applied and Bun's cache directory will be cached.


```yaml
version: '2.1'
orbs:
  node: circleci/node@x.y
jobs:
  test:
    executor:
      name: node/default
      tag: 22.19.0
    steps:
      - checkout
      - node/install-bun:
          version: 1.2.22
      - node/install-packages:
          pkg-manager: bun
      - run:
          command: bun test
          name: Run Bun tests
      - run:
          command: bun test --reporter junit --bail
          name: Run Bun tests with JUnit output
          when: always
      - store_test_results:
          path: ./junit.xml
workflows:
  test_my_app:
    jobs:
      - test
```

### run_tests_with_npm

How to quickly and easily run your Node.js tests on CircleCI with caching automatically included. This example assumes you are using NPM as your package manager.
The "npm ci" command will automatically be applied and the "~/.npm" directory cached.


```yaml
version: '2.1'
orbs:
  node: circleci/node@x.y
jobs:
  test:
    executor:
      name: node/default
      tag: '13.14'
    steps:
      - checkout
      - node/install-packages
      - run:
          command: npm run test
workflows:
  test_my_app:
    jobs:
      - test
```

### run_tests_with_pnpm

Utilize the pnpm package manager with the CircleCI Node orb. Caching of your Node packages is enabled by default.


```yaml
version: '2.1'
orbs:
  node: circleci/node@x.y
jobs:
  test:
    executor:
      name: node/default
      tag: '16'
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: pnpm
      - run:
          command: pnpm run test
          name: Run pnpm tests
workflows:
  test_my_app:
    jobs:
      - test
```

### run_tests_with_yarn

Utilize the YARN package manager with the CircleCI Node orb. Caching of your Node packages is enabled by default.


```yaml
version: '2.1'
orbs:
  node: circleci/node@x.y
jobs:
  test:
    executor:
      name: node/default
      tag: '16'
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: yarn
      - run:
          command: yarn run test
          name: Run YARN tests
workflows:
  test_my_app:
    jobs:
      - test
```

### test_results

Run tests with jest and produce and upload test reports.
This assumes that you have configured your project so that your test script will produce the junit.xml file.


```yaml
version: '2.1'
orbs:
  node: circleci/node@x.y
workflows:
  test:
    jobs:
      - node/test:
          executor:
            name: node/default
          test-results-path: junit.xml
```

### test_with_bun_native

Use the test job with Bun's native test runner for automatic test result collection.
When using "test-results-for: bun" with "pkg-manager: bun", the orb will automatically:
- Run Bun's built-in test runner with JUnit output
- Collect and store test results for CircleCI's test summary
Note: This is different from "test-results-for: jest" which runs Jest with Bun acting as a script runner.


```yaml
version: '2.1'
orbs:
  node: circleci/node@x.y
workflows:
  test_my_app:
    jobs:
      - node/test:
          name: test-with-bun-native
          pkg-manager: bun
          setup:
            - node/install-bun:
                version: 1.2.22
          test-results-for: bun
      - node/test:
          name: test-with-jest-via-bun
          pkg-manager: bun
          run-command: test:jest
          setup:
            - node/install-bun:
                version: 1.2.22
          test-results-for: jest
```

### yarn_berry_zero_install

Utilize the YARN v2 package manager + Zero installs with the CircleCI Node orb.


```yaml
version: '2.1'
orbs:
  node: circleci/node@x.y
jobs:
  test:
    executor:
      name: node/default
      tag: '16'
    steps:
      - checkout
      - node/install-packages:
          check-cache: always
          pkg-manager: yarn-berry
          with-cache: false
      - run:
          command: yarn run test
          name: Run YARN tests
workflows:
  test_my_app:
    jobs:
      - test
```