Mise Version Manager

There is no AI here. All content is human-authored and tested for accuracy.

JavaScript Node.js with Mise

Mise simplifies Node.js version management for the JavaScript Node.js runtime on Mac, replacing Node's nvm version manager with a single tool that handles multiple languages. Use mise to install and switch between Node.js versions, manage npm packages, and enable automatic version switching in your projects.

Mise is a multi-language version manager that handles Node.js, Python, Ruby, Java, and more from a single command line tool and configuration file. Mise unifies version management across your entire development environment. See Mise on Mac to understand how mise works and why developers switch from language-specific managers.

Managing Node.js versions is one step in setting up your Mac for development. See the full roadmap to set up a Mac for software development.

Before you get started

You'll need a terminal application to install and use the mise version manager for Node. Apple includes the Mac terminal but I prefer Warp Terminal. Warp is an easy-to-use terminal application, with AI assistance to help you learn and remember terminal commands. Download Warp Terminal now; it's FREE and worth a try.

First steps for Node.js with Mise

If you haven't installed mise yet, see the Install Mise on Mac guide. Verify that mise is working by running mise --version in your terminal. You should also run mise doctor after installation to ensure mise is activated by the ~/.zshrc file and shell hooks load correctly. This allows mise to automatically switch Node versions when you enter directories with a .mise.toml or .nvmrc file.

Set a global Node.js version

To set a default Node.js version for your entire system, run mise use with the --global flag. This version applies whenever you're in a directory without a .mise.toml file.

$ mise use --global node@24

The global version is stored in ~/.config/mise/config.toml. You can have multiple project-specific versions and still maintain a system-wide default. Mise downloads the latest precompiled Node.js binary and installs it to ~/.local/share/mise/installs/node/.

Project configuration files

You'll need a .mise.toml file in your project root to specify the exact Node.js version your project requires. This file enables automatic version switching: whenever you navigate into the project directory, mise activates the configured version. Commit this file to version control so your team uses identical Node versions. See Mise Configuration on Mac for other settings including environment variables, automated tasks, and advanced setup.

Existing projects with Mise for Node.js

If you have an existing JavaScript project with Node, you can use mise edit to create a .mise.toml configuration file. Instead of writing a file by hand, mise edit launches a terminal-based interactive editor (a TUI) that knows the structure of mise configuration and auto-detects language runtimes from your project files (reading engines.node from package.json), so existing projects get a pre-populated configuration with no manual work.

New projects with Mise for Node.js

If you are starting a new JavaScript project, open your terminal application and navigate to your project directory. Run the command mise use to install the latest Node.js version.

$ mise use node

If you haven't installed a global Node.js version yet, Mise downloads the latest precompiled Node.js binary and installs it to ~/.local/share/mise/installs/node/. The command creates a .mise.toml file in your current directory with the installed version.

The configuration file is simple:

[tools]
node = "latest"

To verify the installation, check the Node.js version and confirm npm is available.

$ node --version
$ npm --version

Both commands should display version numbers. The npm tool is bundled with your Node.js installation.

Install a specific Node.js version

If your project requires a particular major or minor version, use fuzzy matching to let mise select the latest patch version.

$ mise use node@24

This installs the latest version in the Node.js 24 series. To pin an exact version, use the --pin flag.

$ mise use --pin [email protected]

The --pin flag records the complete version string in .mise.toml, ensuring consistent behavior across your team.

Discover available Node.js versions

Before installing, you can browse all available Node.js versions using mise ls-remote node. This command shows every version available for installation.

$ mise ls-remote node

The output lists versions from oldest to newest. You can filter by major version to see all releases within a series.

$ mise ls-remote node@24

This shows every 24.x release available. The output includes version numbers and creation timestamps, helping you choose appropriate releases.

Node.js release cycles

Node.js follows a predictable release schedule. Even-numbered major versions (22, 24, etc.) are designated LTS (Long Term Support) versions after a period of active development.

For production applications, always use LTS versions. These receive security updates and critical bug fixes for extended periods. As of 2026, Node.js 24 is the current LTS with maintenance lasting until late 2027.

Odd-numbered versions like 25 are current releases that transition out of support after 6 months. Use these for development and testing when you need cutting-edge features.

Handle .nvmrc files

If you're migrating from nvm or have projects using .nvmrc files, mise reads them automatically. No conversion is necessary.

Mise recognizes several legacy version file formats without any configuration:

  • .nvmrc (nvm format)
  • .node-version (nodenv format)
  • .tool-versions (asdf format)

When mise finds any of these files, it automatically switches to the specified version upon entering the directory. To ensure .nvmrc compatibility is fully enabled, run this command once.

$ mise settings add idiomatic_version_file_enable_tools node

This enables automatic version switching for all version file formats. After running this, your existing nvm setups work seamlessly with mise. But you might want to use a .mise.toml file because it gives you more options, as described in Mise Configuration.

Manage global npm packages

Global npm packages are tools installed system-wide, such as typescript, eslint, or nodemon. Mise can automatically install default global packages for any project whenever a new Node.js version is set up.

Create a file at ~/.default-npm-packages with one package name per line.

typescript
eslint
prettier
jest
nodemon

Each time mise installs a Node.js version, these packages are installed globally for that version. This eliminates the need to manually install tools after switching versions.

Alternatively, specify global packages directly in your .mise.toml file. Use mise edit or a text editor.

[tools]
node = "24"

[env]
npm:typescript = "latest"
npm:eslint = "latest"

Both approaches work. The .default-npm-packages file applies to all Node versions globally, while .mise.toml packages are project-specific.

Corepack for JavaScript package managers

Corepack is a Node.js tool that sits between your project and npm, Yarn, or pnpm and makes them version‑aware. It reads the packageManager field in package.json and ensures the matching package‑manager version is installed and used for that project. Corepack was introduced as an experimental feature in Node 14 and 16 and is still marked experimental today. The Node.js maintainers have voted to stop shipping Corepack in future Node releases (Node 25 and later), so long‑term it will no longer be bundled with Node.

Using Yarn with Mise (recommended, no Corepack)

Set up Yarn by letting Mise manage it directly:

  1. Add tools to .mise.toml:

    [tools]
node = "24"
yarn = "4.3.0"

  2. Run mise install to install Node 24 and Yarn 4.3.0.

Mise now provides both node and yarn on your PATH. Every developer using this repo with Mise will use the same Yarn version without installing Yarn globally or depending on Corepack. You can optionally document this in package.json:

{
  "name": "my-app",
  "version": "1.0.0",
  "packageManager": "[email protected]"
}

In this setup, packageManager is a hint for tools and teammates, but Yarn itself comes from Mise.

Using pnpm with Mise (recommended, no Corepack)

Set up pnpm in the same way:

  1. Add tools to .mise.toml:

    [tools]
node = "24"
pnpm = "9.0.0"

  2. Run mise install to install Node 24 and pnpm 9.0.0.

Mise now provides both node and pnpm on your PATH, so pnpm install uses the pnpm that Mise installed. This keeps your whole team on the same pnpm version with no global installs and no Corepack. You can optionally add to package.json:

{
  "name": "my-app",
  "version": "1.0.0",
  "packageManager": "[email protected]"
}

Again, packageManager documents the intended version, while Mise actually supplies pnpm.

Using Corepack with Mise

If you want Node’s Corepack to manage package‑manager versions via the packageManager field in package.json instead of letting Mise manage Yarn or pnpm directly, you can configure the Mise .mise.toml file to enable and defer to Corepack.

  [hooks]
  # Enabling corepack will install the `pnpm` package manager specified in your package.json
  # alternatively, you can also install `pnpm` with mise
  postinstall = 'npx corepack enable'

Migrate from nvm to mise

If you currently use nvm, switching to mise takes just a few steps. Your existing Node.js installations don't need to be reinstalled immediately.

You can install Node.js globally with mise use -g node@24 (using the -g flag) or install Node.js versions with mise in each of your projects:

$ mise use node@24

Then comment out the nvm initialization lines in your shell configuration file. If you use zsh, open ~/.zshrc and find lines that source nvm (usually near the end). Comment them out or delete them, then save the file.

After restarting your terminal, mise handles Node version management instead of nvm. Your existing .nvmrc files work automatically with mise.

Switch between Node.js versions per project

One of mise's most powerful features is automatic version switching. When you navigate into a project directory with a .mise.toml or .nvmrc file, mise automatically switches to that project's Node version.

Create two project directories with different Node versions to see this in action. In the first project, create a .mise.toml specifying Node 24.

$ cd project-a/
$ mise use node@24
$ node --version
v24.x.x

Create a second project directory and install Node 20.

$ cd ../project-b/
$ mise use node@20
$ node --version
v20.x.x

Now navigate back to project-a. Mise automatically switches the version.

$ cd ../project-a/
$ node --version
v24.x.x

This automatic switching happens whenever you enter a directory containing version specifications, making it impossible to accidentally use the wrong Node version.

Follow best practices for Node.js versions

When managing Node.js versions across your projects, follow these practices to prevent conflicts and maintain consistency.

Always specify Node versions in .mise.toml for projects you plan to share with others or maintain long-term. This ensures new team members and future versions of yourself use identical configurations.

Use exact version pinning for production projects. The --pin flag creates reproducible builds across environments.

$ mise use --pin [email protected]

For monorepos with multiple packages, each subdirectory can have its own .mise.toml. Mise automatically switches versions when entering different subdirectories.

Keep your global Node version at a reasonable LTS level that matches your most common work. This provides a sensible fallback when you're outside project directories.

Regular updates to Node versions are important for security. Patch releases address vulnerabilities. Review Node.js release notes before updating to new major versions, as breaking changes sometimes require code updates.

Manage npm scripts and tooling

Npm scripts defined in package.json run with the Node version set by mise. This ensures consistency between development and CI environments.

Define common development commands as npm scripts in your package.json file.

{
  "name": "my-app",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "test": "jest",
    "lint": "eslint src/"
  }
}

Run these scripts using npm run and they execute with the correct Node version automatically.

$ npm run build

Global tools like nodemon, tsx, or ts-node should be listed in your .default-npm-packages file or .mise.toml configuration. This ensures they're always available for the current Node version.

Use different Node versions for different tasks

Advanced workflows sometimes require different Node versions for different purposes. Mise supports executing specific commands with non-default versions.

Use mise exec to run a single command with a specific Node version without changing your default.

$ mise exec node@20 -- node --version
v20.x.x

This approach is useful for testing compatibility with older versions or running tools that require specific Node versions without permanently switching.

Verify your setup

After configuring mise for Node.js, verify the setup is complete and working correctly.

Check that mise is recognizing your .mise.toml configuration.

$ mise current node

This displays the current Node version mise is using. It should match your .mise.toml specification.

Verify that npm packages are available by listing globally installed packages.

$ npm list --global --depth 0

This output shows all global npm packages for the current Node version. After switching Node versions, you might need to reinstall global packages if you set them up differently for different versions.

Troubleshoot common Node.js issues

If version switching isn't working, verify that mise's shell hooks are loaded. Restart your terminal completely (close all tabs) to ensure the latest shell configuration is loaded. Run mise doctor for diagnostics to ensure mise is activated by the ~/.zshrc file.

Check that .mise.toml exists in your project directory and contains valid configuration.

$ cat .mise.toml

The file should have a [tools] section with node = "version". If the file is missing, run mise use node@version to create it.

If npm packages aren't found after switching versions, verify the npm version matches your expectations.

$ npm --version

Global packages might not be installed. Run npm install --global with the specific package names to manually install them for the current Node version.

Troubleshoot npm issues

When npm or Node.js behaves unexpectedly, often the issue is version-related.

If you receive "command not found" errors for npm tools, check that the tools were installed for your current Node version.

$ npm list --global package-name

If the package isn't listed, install it for the current version.

$ npm install --global package-name

If npm is slow or unresponsive, clear npm's cache to eliminate corruption.

$ npm cache clean --force

After clearing the cache, npm might take slightly longer on the next command as it rebuilds the cache, but performance typically improves afterward.

Use Node.js across your stack

Mise's true power emerges when managing multiple languages. If your project uses Node.js and Python, you can specify both in a single .mise.toml file.

[tools]
node = "24"
python = "3.12"

When you enter this directory, both versions activate automatically. This single-file approach eliminates tool switching and makes your project setup reproducible.

For web applications using Node.js alongside server-side languages, this multi-language approach keeps your entire development environment synchronized.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.