beatrizsmerino / beatrizsmerino/angular-setup
feat(node): configure `node` and `npm` versions
- Dominant language
- No language data
- Stars
- 0
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
# feat(node): configure `node` and `npm` versions
| β±οΈ Estimate | π Priority | π Size | π
Start | π
End |
| --- | --- | --- | --- | --- |
| 1h | P1 | XS | 02-03-2026 | 02-03-2026 |
## πΈ Screenshots
| Current | Expected |
| :---: | :---: |
| N/A β This change has no visual impact. | N/A β This change has no visual impact. |
## π Summary
- Create `.nvmrc` file to lock `Node.js` version to `v24.13.0`
- Create `.npmrc` file with `engine-strict=true`
- Add `engines` field to `package.json` specifying `Node.js` and `npm` versions
## π‘ Why this change?
> [!CAUTION]
> ```
> Error: This version of Angular CLI requires a minimum Node.js version of v20.19.0 or higher.
> You are currently using v18.x.x.
>
> Please update your Node.js version.
> ```
- `Angular CLI 21` requires a minimum `Node.js` version of `v20.19`, `v22.12` or `v24.0.0`
- Using an incompatible version (e.g., v18.x) results in this installation error
## β Benefits
- Prevent `npm` from installing packages with incompatible engine versions
- Ensure all developers use compatible `Node.js` versions
- Consistent development environment across all machines
- Automatic version switching with `nvm` (`nvm use`)
- Prevent installation errors due to version mismatches
- Dependencies can still use `^` or `~` for flexibility
## π Steps
### Phase 1: Create `.nvmrc` file
- [x] Create `.nvmrc` file with `v24.13.0` for automatic version switching with `nvm`:
```bash
echo "v24.13.0" > .nvmrc
```
```diff
+v24.13.0
```
### Phase 2: Create `.npmrc` file
- [x] Create `.npmrc` file with `engine-strict=true` to prevent installation with incompatible versions:
```bash
echo "engine-strict=true" > .npmrc
```
```diff
+engine-strict=true
```
### Phase 3: Update `package.json`
- [x] Add `engines` field to `package.json` to enforce version requirements:
```bash
npm pkg set engines.node="^20.19.0 || ^22.12.0 || ^24.0.0"
npm pkg set engines.npm=">=9.6.7"
```
```diff
"private": true,
"packageManager": "npm@11.6.2",
+"engines": {
+ "node": "^20.19.0 || ^22.12.0 || ^24.0.0",
+ "npm": ">=9.6.7"
+},
"dependencies": {
...
},
```
## π§ͺ Tests
- [x] Verify `.nvmrc` file is valid:
```bash
nvm use
```
- [x] Verify `.npmrc` settings are applied
- [x] Verify `engines` field prevents incompatible installations
## π Notes
### Version changes
| File | Configuration | From | To | Type |
| --- | --- | --- | --- | --- |
| `.nvmrc` | `Node version` | - | `24.13.0` | - |
| `.npmrc` | `engine-strict` | - | `true` | - |
| `package.json` | `engines.node` | - | `^20.19.0 \|\| ^22.12.0 \|\| ^24.0.0` | - |
| `package.json` | `engines.npm` | - | `>=9.6.7` | - |
### How the configuration works
- The **`.nvmrc`** file specifies which `Node.js` version the project uses
- The **`.npmrc`** file with `engine-strict=true` makes `npm` fail if `Node.js`/`npm` versions do not match requirements
- The **`engines`** field in `package.json` enforces version requirements at installation time
- Dependencies can still use `^` or `~` for version ranges (we do not use `save-exact=true`)
### Automatic version switching
Three options for auto-switching `Node.js` version when entering a directory with `.nvmrc`:
- **Manual**: Run `nvm use` when entering the project directory
- The **`zsh` auto-switch script** automatically detects `.nvmrc` and switches `Node.js` version on directory change. Simple setup, no extra files
- The **`direnv`** tool is an industry-standard that loads environment variables per-directory. Also supports `nvm` auto-switch but requires `.envrc` file per project
| Feature | `zsh` script | `direnv` |
| --- | --- | --- |
| Setup complexity | Simple | Medium |
| Auto `nvm` switch | β
| β
|
| Auto env variables | β | β
|
| Industry standard | β | β
|
| Extra files | None | `.envrc` per project |
| Security prompt | β | β
(safer) |
| Setup per project | β (once for all) | β
(allow each project) |
Use `zsh` script if you only need `nvm` auto-switch. Use `direnv` if you also need automatic environment variables loading.
## π References
### Files to create
- `.nvmrc`
- `.npmrc`
### Files to modify
- `package.json`
### Documentation
- https://github.com/nvm-sh/nvm
- https://docs.npmjs.com/cli/v10/configuring-npm/npmrc
- https://docs.npmjs.com/cli/v10/configuring-npm/package-json#engines
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.