setup-node/README.md

127 lines
4.9 KiB
Markdown
Raw Normal View History

2019-08-04 09:49:54 +08:00
# setup-node
[![build-test](https://github.com/actions/setup-node/actions/workflows/build-test.yml/badge.svg)](https://github.com/actions/setup-node/actions/workflows/build-test.yml)
[![versions](https://github.com/actions/setup-node/actions/workflows/versions.yml/badge.svg)](https://github.com/actions/setup-node/actions/workflows/versions.yml)
[![proxy](https://github.com/actions/setup-node/actions/workflows/proxy.yml/badge.svg)](https://github.com/actions/setup-node/actions/workflows/proxy.yml)
2019-08-13 03:10:38 +08:00
2021-06-25 17:06:49 +08:00
This action provides the following functionality for GitHub Actions users:
2019-08-04 09:49:54 +08:00
- Optionally downloading and caching distribution of the requested Node.js version, and adding it to the PATH
2021-07-16 03:14:30 +08:00
- Optionally caching npm/yarn/pnpm dependencies
- Registering problem matchers for error output
- Configuring authentication for GPR or npm
2019-08-04 09:49:54 +08:00
## Usage
2020-05-19 21:57:20 +08:00
See [action.yml](action.yml)
2020-05-19 21:57:20 +08:00
**Basic:**
2022-04-01 16:13:52 +08:00
2020-05-19 21:57:20 +08:00
```yaml
steps:
2022-04-01 16:13:52 +08:00
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
2020-05-19 21:57:20 +08:00
with:
node-version: 14
- run: npm ci
- run: npm test
2020-05-19 21:57:20 +08:00
```
The `node-version` input is optional. If not supplied, the node version from PATH will be used. However, it is recommended to always specify Node.js version and don't rely on the system one.
2020-05-19 21:57:20 +08:00
The action will first check the local cache for a semver match. If unable to find a specific version in the cache, the action will attempt to download a version of Node.js. It will pull LTS versions from [node-versions releases](https://github.com/actions/node-versions/releases) and on miss or failure will fall back to the previous behavior of downloading directly from [node dist](https://nodejs.org/dist/).
2020-05-19 21:57:20 +08:00
For information regarding locally cached versions of Node.js on GitHub hosted runners, check out [GitHub Actions Virtual Environments](https://github.com/actions/virtual-environments).
2019-08-04 09:49:54 +08:00
### Supported version syntax
2021-06-30 20:07:45 +08:00
The `node-version` input supports the following syntax:
major versions: `12`, `14`, `16`
more specific versions: `10.15`, `14.2.0`, `16.3.0`
nvm lts syntax: `lts/erbium`, `lts/fermium`, `lts/*`
2021-06-30 20:07:45 +08:00
### Checking in lockfiles
It's **always** recommended to commit the lockfile of your package manager for security and performance reasons. For more information consult the "Working with lockfiles" section of the [Advanced usage](docs/advanced-usage.md#working-with-lockfiles) guide.
2022-04-18 22:15:27 +08:00
## Caching global packages data
2022-04-18 22:15:27 +08:00
The action has a built-in functionality for caching and restoring dependencies. It uses [actions/cache](https://github.com/actions/cache) under the hood for caching global packages data but requires less configuration settings. Supported package managers are `npm`, `yarn`, `pnpm` (v6.10+). The `cache` input is optional, and caching is turned off by default.
2021-08-05 20:00:47 +08:00
The action defaults to search for the dependency file (`package-lock.json` or `yarn.lock`) in the repository root, and uses its hash as a part of the cache key. Use `cache-dependency-path` for cases when multiple dependency files are used, or they are located in different subdirectories.
2022-04-18 22:15:27 +08:00
**Note:** The action does not cache `node_modules`
See the examples of using cache for `yarn`/`pnpm` and `cache-dependency-path` input in the [Advanced usage](docs/advanced-usage.md#caching-packages-data) guide.
2019-08-04 09:49:54 +08:00
2021-06-30 20:07:45 +08:00
**Caching npm dependencies:**
2022-04-01 16:13:52 +08:00
2019-08-04 09:49:54 +08:00
```yaml
steps:
2022-04-01 16:13:52 +08:00
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
2019-08-04 09:49:54 +08:00
with:
node-version: 14
cache: 'npm'
- run: npm ci
2019-08-04 09:49:54 +08:00
- run: npm test
```
2021-08-05 20:00:47 +08:00
**Caching npm dependencies in monorepos:**
2022-04-01 16:13:52 +08:00
2021-07-16 03:14:30 +08:00
```yaml
steps:
2022-04-01 16:13:52 +08:00
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
2021-07-16 03:14:30 +08:00
with:
node-version: 14
2021-08-05 20:00:47 +08:00
cache: 'npm'
cache-dependency-path: subdir/package-lock.json
- run: npm ci
2021-08-05 20:00:47 +08:00
- run: npm test
2021-06-30 23:44:51 +08:00
```
## Matrix Testing
2019-08-04 09:49:54 +08:00
```yaml
jobs:
build:
runs-on: ubuntu-latest
2019-08-04 09:49:54 +08:00
strategy:
matrix:
node: [ 12, 14, 16 ]
2019-08-04 09:49:54 +08:00
name: Node ${{ matrix.node }} sample
steps:
2022-04-01 16:13:52 +08:00
- uses: actions/checkout@v3
2019-08-04 09:49:54 +08:00
- name: Setup node
uses: actions/setup-node@v3
2019-08-04 09:49:54 +08:00
with:
node-version: ${{ matrix.node }}
- run: npm ci
2019-08-04 09:49:54 +08:00
- run: npm test
```
2022-04-01 16:13:52 +08:00
## Advanced usage
1. [Check latest version](docs/advanced-usage.md#check-latest-version)
2. [Using a node version file](docs/advanced-usage.md#node-version-file)
3. [Using different architectures](docs/advanced-usage.md#architecture)
4. [Caching packages data](docs/advanced-usage.md#caching-packages-data)
5. [Using multiple operating systems and architectures](docs/advanced-usage.md#multiple-operating-systems-and-architectures)
6. [Publishing to npmjs and GPR with npm](docs/advanced-usage.md#publish-to-npmjs-and-gpr-with-npm)
7. [Publishing to npmjs and GPR with yarn](docs/advanced-usage.md#publish-to-npmjs-and-gpr-with-yarn)
8. [Using private packages](docs/advanced-usage.md#use-private-packages)
## License
2019-08-04 09:49:54 +08:00
The scripts and documentation in this project are released under the [MIT License](LICENSE)
## Contributions
2019-08-04 09:49:54 +08:00
Contributions are welcome! See [Contributor's Guide](docs/contributors.md)
2020-04-17 06:43:02 +08:00
## Code of Conduct
:wave: Be nice. See [our code of conduct](CODE_OF_CONDUCT.md)