preferred-node-version

Get the preferred Node.js version of a user or project.

This looks for any .nvmrc or package.json (engines.node field) in the current directory, parent directories or home directory.

nvm aliases (like current or lts/erbium) and version ranges (like 12 or >=12) are resolved to regular "major.minor.patch" version strings.

This also looks for any .node-version, .n-node-version, .naverc, .nodeenvrc file or NODE_VERSION, NODIST_NODE_VERSION environment variable.

Examples

import preferredNodeVersion from 'preferred-node-version'

// Look for any `.nvmrc` or `package.json` (`engines.node` field)
const { version } = await preferredNodeVersion()
console.log(version) // 12.10.0

// Search only the home directory and environment variables
const { version } = await preferredNodeVersion({ global: true })

// Start looking for a Node.js version file from this directory instead
const { version } = await preferredNodeVersion({ cwd: '/path/to/cwd' })

Install

npm install preferred-node-version

This package is an ES module and must be loaded using an import or import() statement, not require().

Usage

preferredNodeVersion(options?)

options: object?
Returns: Promise<object>

Return value

The returned promise resolves to an object with the following properties. An empty object is returned if no preferred Node.js version was found.

If a file cannot be read or if it contains an invalid version, the promise is rejected with an error.

version

Type: string

Full Node.js version. For example 12.16.2

rawVersion

Type: string

Node.js version as specified in the Node.js version file. This might include aliases or version ranges. For example latest, lts/erbium, 12 or 12.16.2.

filePath

Type: string?

Absolute path to the Node.js version file. Either filePath or envVariable is defined.

envVariable

Type: string?

Name of the environment variable containing the version. For example NODE_VERSION. Either filePath or envVariable is defined.

options

cwd

Type: string | URL
Default: process.cwd()

Start looking for a Node.js version file from this directory.

global

Type: boolean
Default: false

If true, find the global Node.js version instead:

• use only the home directory and environment variables
• ignore the current directory and parent directories

mirror

Type: string
Default: https://nodejs.org/dist

Base URL to fetch the list of available Node.js versions. Can be customized (for example https://npmmirror.com/mirrors/node).

The following environment variables can also be used: NODE_MIRROR, NVM_NODEJS_ORG_MIRROR, N_NODE_MIRROR or NODIST_NODE_MIRROR.

fetch

Type: boolean
Default: undefined

The list of available Node.js versions is cached for one hour by default. If the fetch option is:

• true: the cache will not be used
• false: the cache will be used even if it's older than one hour

See also

• nve: Run a specific Node.js version (CLI)
• nvexeca: Run a specific Node.js version (programmatic)
• get-node: Download Node.js
• normalize-node-version: Normalize and validate Node.js versions
• node-version-alias: Resolve Node.js version aliases like latest, lts or erbium
• all-node-versions: List all available Node.js versions
• fetch-node-website: Fetch releases on nodejs.org

Support

For any question, don't hesitate to submit an issue on GitHub.

Everyone is welcome regardless of personal background. We enforce a Code of conduct in order to promote a positive and inclusive environment.

Contributing

This project was made with ❤️. The simplest way to give back is by starring and sharing it online.

If the documentation is unclear or has a typo, please click on the page's Edit button (pencil icon) and suggest a correction.

If you would like to help us fix a bug or add a new feature, please check our guidelines. Pull requests are welcome!

Thanks go to our wonderful contributors:

ehmicky 💻 🎨 🤔 📖

Adrien Becchis 💻 ⚠️ 🤔

Changelog

3.1.0

Features

• Add TypeScript types