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

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 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. This file declares the core backend identifier, available binaries, and automatic detection heuristics for Node.js projects.

# 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. This parser handles alias mapping, converting shorthand references like node or nodejs into the fully-qualified backend identifier core:node.

// 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, which dispatches to the core installer when it encounters the core:node backend string. This architecture ensures consistent behavior across all core-managed languages.

// 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#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:

# 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 file. This configuration declares which versions to install and which serves as the default.

# 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 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.

# 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, declaring core:node as the backend and defining detection files like package.json and .nvmrc.
• Backend resolution: The parser in src/config/config_file/mise_toml.rs normalizes aliases to core:node, which src/backend/mod.rs routes to the built-in installer.
• Version sourcing: 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 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 file if one exists.

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

According to registry/node.toml, mise scans for 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. Project-specific .mise.toml files take precedence over these idiomatic files.

Can I use multiple Node.js versions simultaneously?

Yes. The versions array in .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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}