Skip to main content
This guide sets up Miniconda as a per‑project Node.js version manager on macOS. It’s the recommended approach for WRLD team machines that already use conda for Python work, or where tools (like Mintlify) require a specific Node LTS that conflicts with the system Node.
When to use this vs. nvm / fnm
  • Use conda if you already rely on it for Python, or if you want one tool to manage both Node and Python environments.
  • Use fnm or nvm if this machine is mostly JavaScript/Node — they’re lighter and honor .nvmrc / .node-version files automatically.

​
Prerequisites

  • macOS (Apple Silicon or Intel)
  • Admin access to your user account (no sudo required for the steps below)
  • zsh (the default shell on modern macOS)

​
Install Miniconda

1

Download the installer

Apple Silicon (M1/M2/M3/M4):
Intel Macs:
2

Run the installer

Accept the license, accept the default install location (~/miniconda3), and answer yes when asked whether to update your shell profile.
3

Reload your shell

Close and reopen your terminal, or run:
Verify:
4

(Optional) Stop auto-activating `base`

By default, conda activates its base environment in every new terminal. To disable that:
5

Accept channel Terms of Service

Newer conda releases require explicit ToS acceptance for the default Anaconda channels before you can install packages:
6

Clean up the installer

​
Create a Node environment

Create one environment per project and pin the Node major version. Use the conda-forge channel — it ships more current Node builds than defaults.
Example — a dedicated env for this docs site (Mintlify requires Node LTS):
Pinning nodejs=22 prevents conda from silently upgrading you to a non‑LTS release on the next conda update.

​
Daily workflow

Global npm installs (npm i -g ...) while an env is active install into that env only — they won’t pollute your system Node or other envs. This is the whole point of using conda for Node.

​
Managing environments

​
Example: running mint dev for this docs site

1

One-time setup

2

Every time you work on docs

The preview runs at http://localhost:3000.

​
Troubleshooting

Your shell hasn’t been initialized for conda. Run once:
If that still fails, source conda’s hook directly in the current shell:
A globally installed Node is shadowing the env. Confirm with:
The first result should be inside ~/miniconda3/envs/<env-name>/bin/. If it isn’t, check your ~/.zshrc / ~/.zprofile for a stray PATH export (e.g. from a previous Homebrew node install) that’s prepended after conda’s init block. Move conda’s init below those lines, or uninstall the shadowing Node:
You haven’t accepted the Anaconda channel Terms of Service yet. Run:
The env doesn’t exist yet — conda activate can only activate envs that were already created with conda create. List what you have:
Then create the one you need (see Create a Node environment).
You’re running a non‑LTS Node. Activate an env pinned to Node 22 (or any current LTS) and reinstall the CLI inside that env: