# Node

Like `nvm`, (or `volta`, `fnm` or `asdf`...), `mise` can manage multiple versions of Node.js on the same system.

> The following are instructions for using the node mise core plugin. This is used when there isn't a
> git plugin installed named "node".
> If you want to use [asdf-nodejs](https://github.com/asdf-vm/asdf-nodejs)
> then run `mise plugins install node https://github.com/asdf-vm/asdf-nodejs`

The code for this is inside the mise repository at [`./src/plugins/core/node.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/node.rs).

## Usage

The following installs the latest version of node-26.x and makes it the global
default:

```sh
mise use -g node@26
```

See the [Node.JS Cookbook](/mise-cookbook/nodejs.html) for common tasks and examples.

## Tool Options

The following [tool-options](/dev-tools/#tool-options) are available for the `node` backend.
These options go in the `[tools]` section in `mise.toml`.

### `install_env`

Set environment variables for source builds, default package installation, Corepack setup, and
install-time verification commands run by the core `node` backend:

```toml
[tools]
node = { version = "latest", install_env = { CFLAGS = "-O2" } }
```

## Pinning npm version

By default, Node.js ships with a bundled version of npm. If you need a specific npm version
(e.g. to keep your entire team on the same version and avoid `package-lock.json` conflicts),
you can pin it alongside Node in your `mise.toml`:

```toml [mise.toml]
[tools]
node = "26"
npm = "11"
```

To pin both to exact versions:

```sh
mise use --pin node@lts npm@latest
```

This resolves aliases like `lts` and `latest` to exact version numbers in `mise.toml`, e.g.:

```toml [mise.toml]
[tools]
node = "26.1.0"
npm = "11.12.1"
```

The pinned npm version takes precedence over the one bundled with Node, so `npm --version` will
always return the version specified in `mise.toml`.

## `.nvmrc`, `.node-version` and `package.json` support

By default, mise uses a `mise.toml` file for auto-switching between software versions.

It also supports `.tool-versions` file to specify versions for ASDF compatibility. Additionally, `.nvmrc`, `.node-version`, and the `devEngines` field in `package.json` are supported but require explicit enabling (see tip below).

This makes it a drop-in replacement for `nvm`. See [idiomatic version files](/configuration.html#idiomatic-version-files) for more information.

::: tip
Idiomatic version files (`.nvmrc`, `.node-version`, `devEngines` field in `package.json`) are disabled by default and must be explicitly enabled:

```sh
mise settings add idiomatic_version_file_enable_tools node
```

Or in `~/.config/mise/config.toml`:

```toml
[settings]
idiomatic_version_file_enable_tools = ["node"]
```

To keep `.nvmrc` or `.node-version` enabled while preventing node from using
`devEngines.runtime` in `package.json`:

```sh
mise settings add idiomatic_version_file_disable_files node:package.json
```

:::

## Default node packages

::: warning Planned deprecation
Default package files are deprecated. They are still supported for now, but mise will start warning
in `2026.11.0` and support will be removed in `2027.11.0`.

For npm CLIs, install the tool directly with the [npm backend](/dev-tools/backends/npm.html):

```toml
[tools]
"npm:typescript" = "latest"
```

For packages that really should be installed into every Node.js version, use a tool-level
`postinstall` hook:

```toml
[tools]
node = { version = "22", postinstall = "npm install -g typescript" }
```

:::

mise-node can automatically install a default set of npm packages right after installing a node
version. To use this legacy feature, provide a `$HOME/.default-npm-packages` file that lists one
package per line, for example:

```text
lodash
request
express
```

You can specify a non-default location of this file by setting a `MISE_NODE_DEFAULT_PACKAGES_FILE` variable.

## "nodejs" -> "node" Alias

You cannot install/use a plugin named "nodejs". If you attempt this, mise will just rename it to
"node". See the [FAQ](/faq.html#what-is-the-difference-between-nodejs-and-node-or-golang-and-go)
for an explanation.

## Building from source

If compiling from source, see [BUILDING.md](https://github.com/nodejs/node/blob/main/BUILDING.md#building-nodejs-on-supported-platforms) in node's documentation for
required system dependencies.

```shell
mise settings node.compile=1
mise use node@latest
```

## Unofficial Builds

Nodejs.org offers a set of [unofficial builds](https://unofficial-builds.nodejs.org/) which are
compatible with some platforms that are not supported by the official binaries. These are a nice alternative to
compiling from source for these platforms.

To use, first set the mirror url to point to the unofficial builds:

```sh
mise settings node.mirror_url=https://unofficial-builds.nodejs.org/download/release/
```

If your goal is to simply support an alternative arch/os like linux-loong64 or linux-armv6l, this is
all that is required. Node also provides flavors such as musl or glibc-217 (an older glibc version
than what the official binaries are built with).

To use these, set `node.flavor`:

```sh
mise settings node.flavor=musl
mise settings node.flavor=glibc-217
```

For the common musl case, `mise settings libc=musl` also selects Node's `musl`
flavor when `node.flavor` is unset.

## Settings

<script setup>
import Settings from '/components/settings.vue';
</script>
<Settings child="node" :level="3" />
