Skip to content
Hagicode Docs
Blog

Installing Node.js

Edit page

This guide covers Node.js installation on Windows, macOS, and Linux. Node.js is a key dependency for HagiCode local tooling, including OpenSpec, frontend tooling, and several developer CLIs.

Version Requirements

HagiCode recommends Node.js 24+ (minimum supported Node.js >= 18.0). In most cases, install the latest LTS version and then verify that your version meets the requirement.

Installing Node.js

  1. Visit the Node.js Official Website
  2. Download the LTS (Long Term Support) version Windows installer (.msi file)
  3. Double-click to run the installer
  4. Follow the installation wizard prompts to complete installation:
    • Accept the license agreement
    • Choose installation path (default is fine)
    • Make sure “Automatically install the necessary tools” is checked
    • Click “Install” to start installation
  5. After installation completes, click “Finish”

Method Two: Using winget

Open PowerShell or Command Prompt and run:

Terminal window
winget install OpenJS.NodeJS.LTS

After installation, reopen the terminal for changes to take effect.

Using Version Management Tools

If you need to switch between multiple Node.js versions, you can use version management tools.

nvm (Node Version Manager)

Linux/macOS

Terminal window
# Install using curl
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash


# Or install using wget
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

After installation, reload your shell configuration:

Terminal window
source ~/.bashrc
# Or for Zsh users
source ~/.zshrc

Windows

On Windows, we recommend using nvm-windows:

  1. Download the latest nvm-setup.exe from nvm-windows releases
  2. Run the installer
  3. Reopen Command Prompt or PowerShell

fnm (Fast Node Manager)

fnm is a faster and simpler Node.js version management tool built with Rust.

Linux/macOS

Terminal window
# Install using curl
curl -fsSL https://fnm.vercel.app/install | bash


# After installation, reload shell configuration
source ~/.bashrc
# Or for Zsh users
source ~/.zshrc

Windows

Use scoop or winget:

Terminal window
# Use scoop
scoop install fnm


# Or use winget
winget install Schniz.fnm

Acceleration for Mainland China Users

If you are in Mainland China, downloading Node.js and npm packages may be slow. Here are some acceleration solutions.

Using Domestic Mirror Sources

Terminal window
# Temporarily use Taobao mirror
npm install --registry=https://registry.npmmirror.com


# Permanently set Taobao mirror
npm config set registry https://registry.npmmirror.com


# Verify mirror is set successfully
npm config get registry

Using nrm to Manage Mirror Sources

nrm (npm registry manager) helps you quickly switch npm mirror sources:

Terminal window
# Install nrm
npm install -g nrm


# List available mirror sources
nrm ls


# Switch to Taobao mirror
nrm use taobao


# Test mirror source speed
nrm test

Accelerating Node.js Installer Downloads

Taobao provides mirror downloads for Node.js installers:

Visit the above address and select the version you need to download.

Domestic Homebrew Mirrors

If you use Homebrew in Mainland China, you can configure domestic mirrors for acceleration:

Terminal window
# Install Homebrew using domestic mirror
/bin/bash -c "$(curl -fsSL https://gitee.com/ineo6/homebrew-install/raw/master/install.sh)"


# Or use USTC mirror
export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles

Mainland China Specific Package Managers

cnpm

cnpm is an npm client provided by the Taobao team that uses the Taobao mirror by default:

Terminal window
# Install cnpm
npm install -g cnpm --registry=https://registry.npmmirror.com


# Use cnpm to install packages
cnpm install <package-name>

cnpm is mostly compatible with npm commands and can be used as a direct replacement.

Verifying Mirror Acceleration Effect

After setting up mirrors, verify by:

Terminal window
# Test download speed
time npm install express --registry=https://registry.npmmirror.com


# Compare with official source speed
time npm install express --registry=https://registry.npmjs.org

Verifying Installation

After installation, verify that Node.js and npm are installed correctly:

Terminal window
# Check Node.js version
node --version


# Check npm version
npm --version

Make sure Node.js version >= 18.0 (Node.js 24+ is recommended). If the version is too low, please reinstall using the above methods or use version management tools to install the correct version.

Sample Verification Output

Successful verification output should look like:

$ node --version
v24.3.0


$ npm --version
10.2.3

Troubleshooting

Windows Issues

If node or npm commands are not available after installation:

  1. Restart Command Prompt or PowerShell
  2. If still not available, manually add Node.js to PATH:
    • Search for “Environment Variables” and open “Edit system environment variables”
    • Click “Environment Variables”
    • Find “Path” in “System variables” and click “Edit”
    • Add Node.js installation path (default: C:\Program Files\nodejs\)
    • Click “OK” to save changes

macOS Issues

If you encounter permission errors when installing global npm packages:

Terminal window
# Fix npm permissions
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

Linux Issues

If you encounter permission errors when installing global npm packages, it is recommended to use Node.js version management tools (like nvm or fnm) instead of system package managers.

Checking Environment

If verification fails, check the following:

Terminal window
# Check if Node.js is in PATH
where node


# Check installation path
Get-Command node

Next Steps

After Node.js installation is complete, you can continue with the following steps:

Install OpenSpec Install the OpenSpec specification-driven development tool to manage proposals, specs, and changes.
Install AI Agent CLI Use one registry for the official install entries for Claude Code, Codex, Gemini, GitHub Copilot, CodeBuddy, OpenCode, Kimi, QoderCLI, and Kiro.
Return to Installation Guide Return to the main installation guide to continue configuring other dependencies.

Need More Help?

If you encounter issues not covered here:

  1. Visit the Node.js Official Documentation
  2. Review the HagiCode Product Overview for current product and tooling context
  3. Visit the HagiCode website for the latest support entry points