# How to Manage Node.js Versions with mise: A Complete Guide

> Master Node.js versions with mise, the ultimate tool manager. Install any version with `mise install` and pin project versions effortlessly using .mise.toml files. Streamline your development workflow today.

- Repository: [jdx/mise](https://github.com/jdx/mise)
- Tags: how-to-guide
- Published: 2026-08-09

---

**mise manages Node.js versions through a registry-based architecture that maps tool aliases to the `core:node` backend, enabling installation via `mise install node@<version>` and project-level pinning through [`.mise.toml`](https://github.com/jdx/mise/blob/main/.mise.toml) files.**

The `jdx/mise` repository provides a polyglot tool manager that treats Node.js as a first-class citizen within its ecosystem. Understanding how to manage Node.js versions with mise requires familiarity with its registry system, backend resolution logic, and configuration file formats.

## Understanding the Node.js Tool Registry

At the heart of mise's Node.js support lies the centralized registry entry in [`registry/node.toml`](https://github.com/jdx/mise/blob/main/registry/node.toml). This file declares the **core backend** identifier, available binaries, and automatic detection heuristics for Node.js projects.

```toml

# https://github.com/jdx/mise/blob/main/registry/node.toml

backends = ["core:node"]
bins = ["node", "npm", "npx"]
detect = ["package.json", ".nvmrc", ".node-version"]
idiomatic_files = [".nvmrc", ".node-version", "package.json"]

```

The `backends` field specifies that Node.js uses the built-in core installer rather than an external plugin. The `bins` array lists the executables shimmed into your `PATH`, while `detect` and `idiomatic_files` tell mise which files to scan when auto-detecting project runtime requirements.

## Backend Resolution and Alias Handling

When you execute `mise install node@18`, the tool name undergoes normalization in [`src/config/config_file/mise_toml.rs`](https://github.com/jdx/mise/blob/main/src/config/config_file/mise_toml.rs). This parser handles alias mapping, converting shorthand references like `node` or `nodejs` into the fully-qualified backend identifier `core:node`.

```rust
// https://github.com/jdx/mise/blob/main/src/config/config_file/mise_toml.rs#L1458-L1475
/// fully-qualified `"core:node"` that `mise use node` rewrites to `node`.

```

Once normalized, the request routes through [`src/backend/mod.rs`](https://github.com/jdx/mise/blob/main/src/backend/mod.rs), which dispatches to the core installer when it encounters the `core:node` backend string. This architecture ensures consistent behavior across all core-managed languages.

```rust
// https://github.com/jdx/mise/blob/main/src/backend/mod.rs#L461-L468
// Handles "core:node" (and other core backends) by delegating to the core installer.

```

## Installing and Switching Node.js Versions

mise provides several interfaces for version management, from one-off installations to persistent project configuration. The version resolution logic fetches available releases from the URLs defined in [`src/versions_host.rs`](https://github.com/jdx/mise/blob/main/src/versions_host.rs).

```rust
// https://github.com/jdx/mise/blob/main/src/versions_host.rs#L643-L652
track_install_url("node") → "https://mise-versions.jdx.dev/api/tools/node"
version_list_url("node") → "https://mise-versions.jdx.dev/data/node.toml"

```

Install specific versions or ranges using the following commands:

```bash

# Install a specific Node.js version

mise install node@18          # grabs the latest 18.x release

mise install node@20.0.0      # installs exactly 20.0.0

# Use a version in the current shell

mise use node@20              # activates Node 20 for the rest of the session

node -v                       # → v20.x.x

# List all discoverable Node.js versions

mise list node                # shows remote versions from the version host

```

## Project-Level Version Management with .mise.toml

For team consistency and reproducible builds, pin Node.js versions in a project-local [`.mise.toml`](https://github.com/jdx/mise/blob/main/.mise.toml) file. This configuration declares which versions to install and which serves as the default.

```bash

# Pin a version in a project .mise.toml

cat > .mise.toml <<EOF
[node]
versions = ["18", "20"]      # install both; the latest will be the default

EOF
mise install                  # installs the declared versions

```

The `idiomatic_files` detection also enables mise to respect existing `.nvmrc` or `.node-version` files without manual configuration. When present in the project root, mise automatically uses the specified version if no [`.mise.toml`](https://github.com/jdx/mise/blob/main/.mise.toml) overrides it.

## Executing Commands with Specific Versions

Use the `mise x` (execute) command to run one-off commands with a specific Node.js version without changing the global or project default. This creates temporary shims that exist only for the duration of the command.

```bash

# Switch between installed versions

mise x node@18 -- node -v    # run a one-off command with Node 18

```

The installer downloads official Node.js tarballs, extracts the `node`, `npm`, and `npx` binaries, and places them in the mise data directory. Shim files in your `PATH` then delegate to the active version based on the current directory context.

## Summary

- **Registry-based architecture**: Node.js configuration lives in [`registry/node.toml`](https://github.com/jdx/mise/blob/main/registry/node.toml), declaring `core:node` as the backend and defining detection files like [`package.json`](https://github.com/jdx/mise/blob/main/package.json) and `.nvmrc`.
- **Backend resolution**: The parser in [`src/config/config_file/mise_toml.rs`](https://github.com/jdx/mise/blob/main/src/config/config_file/mise_toml.rs) normalizes aliases to `core:node`, which [`src/backend/mod.rs`](https://github.com/jdx/mise/blob/main/src/backend/mod.rs) routes to the built-in installer.
- **Version sourcing**: [`src/versions_host.rs`](https://github.com/jdx/mise/blob/main/src/versions_host.rs) supplies metadata URLs pointing to `mise-versions.jdx.dev` for available releases and installation packages.
- **Flexible usage**: Use `mise install` for permanent installation, `mise use` for session activation, and `mise x` for one-off command execution with specific versions.
- **Project configuration**: Define versions in [`.mise.toml`](https://github.com/jdx/mise/blob/main/.mise.toml) or rely on idiomatic files (`.nvmrc`, `.node-version`) for automatic detection.

## Frequently Asked Questions

### What is the difference between `mise install` and `mise use`?

`mise install node@<version>` downloads and installs the specified Node.js version to the local cache but does not change the active runtime in your current shell. `mise use node@<version>` immediately activates that version for the current session by updating environment variables and shims, and it persists the choice to a local [`.mise.toml`](https://github.com/jdx/mise/blob/main/.mise.toml) file if one exists.

### How does mise detect which Node.js version to use in a project?

According to [`registry/node.toml`](https://github.com/jdx/mise/blob/main/registry/node.toml), mise scans for [`package.json`](https://github.com/jdx/mise/blob/main/package.json), `.nvmrc`, and `.node-version` files. When found, it reads the version requirement and resolves it against the available versions from [`src/versions_host.rs`](https://github.com/jdx/mise/blob/main/src/versions_host.rs). Project-specific [`.mise.toml`](https://github.com/jdx/mise/blob/main/.mise.toml) files take precedence over these idiomatic files.

### Can I use multiple Node.js versions simultaneously?

Yes. The `versions` array in [`.mise.toml`](https://github.com/jdx/mise/blob/main/.mise.toml) accepts multiple entries, installing all specified versions while defaulting to the latest listed. For ad-hoc switching without changing defaults, use `mise x node@<version> -- <command>` to execute individual commands with alternate versions.

### Where does mise download Node.js binaries from?

As implemented in [`src/versions_host.rs`](https://github.com/jdx/mise/blob/main/src/versions_host.rs), mise fetches version metadata from `https://mise-versions.jdx.dev/data/node.toml` and installation packages from `https://mise-versions.jdx.dev/api/tools/node`. These endpoints proxy or reference the official Node.js release tarballs, which the `core:node` backend then downloads and extracts.