Installing Node.js

This guide explains how to install Node.js on Windows, macOS, and Linux. Node.js is a core dependency for HagiCode-related local tooling such as OpenSpec, frontend tooling, and several developer CLIs.

Version Requirements

HagiCode recommends using Node.js 24+ (minimum supported Node.js >= 18.0). It is recommended to install the latest LTS version for best performance and security. After installation, please verify that your version meets this requirement.

Installing Node.js

Windows

Method One: Official Installer (Recommended)

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:

winget install OpenJS.NodeJS.LTS

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

macOS

Method One: Official Installer (Recommended)

1. Visit the Node.js Official Website
2. Download the LTS (Long Term Support) version macOS installer (.pkg file)
3. Double-click to run the installer
4. Follow the installation wizard prompts to complete installation:
   • Click “Continue”
   • Accept the license agreement
   • Choose installation disk
   • Click “Install” and enter administrator password
5. After installation completes, click “Close”

Method Two: Using Homebrew

If you have Homebrew installed, you can install Node.js via terminal:

brew install node

Tip

Homebrew will automatically add Node.js to your PATH. If the command is not available, restart the terminal or run:

eval "$(/opt/homebrew/bin/brew shellenv)"

Ubuntu/Debian

Using NodeSource Repository (Recommended)

This is the best way to get the latest Node.js version:

# Use curl to download the installation script
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

Using apt Package Manager

If you don’t need the latest version, you can use the default Ubuntu repository:

sudo apt-get update
sudo apt-get install -y nodejs npm

Note

The Node.js version in the default repository may be older. After installation, check the version to ensure it meets Node.js >= 18.0 requirements (Node.js 24+ is recommended).

CentOS/RHEL

Using NodeSource Repository (Recommended)

# Use curl to download the installation script
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo yum install -y nodejs

Using yum Package Manager

sudo yum install -y nodejs npm

Fedora

Using dnf Package Manager

sudo dnf install -y nodejs npm

Tip

Fedora’s software repository usually contains newer Node.js versions and can be installed directly via dnf.

Using Version Management Tools

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

nvm (Node Version Manager)

Installing nvm

Linux/macOS

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

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

Using nvm

After installing nvm, you can use it to install and manage Node.js versions:

# Install the latest LTS version (recommended)
nvm install --lts

# Install Node.js 24 (recommended version)
nvm install 24

# Install a specific Node.js version
nvm install 18.20.0

# List installed versions
nvm list

# Switch to a specified Node.js version
nvm use 24

# Set default version
nvm alias default 24

# Windows nvm-windows syntax is slightly different
nvm install 24
nvm use 24

fnm (Fast Node Manager)

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

Installing fnm

Linux/macOS

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

# Use scoop
scoop install fnm

# Or use winget
winget install Schniz.fnm

Using fnm

# Install the latest LTS version (recommended)
fnm install --lts

# Install Node.js 24 (recommended version)
fnm install 24

# Install a specific Node.js version
fnm install 18.20.0

# List installed versions
fnm list

# Switch to a specified Node.js version
fnm use 24

# Set default version
fnm default 24

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

npm Taobao Mirror (Recommended)

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

# 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 Node.js Mirror

Taobao provides mirror downloads for Node.js installers:

• Download Address: https://npmmirror.com/mirrors/node/

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

FastGit Acceleration

If downloading nvm or other tools from GitHub is slow, you can use the FastGit mirror:

# Use FastGit to accelerate nvm installation
curl -o- https://fastgit.org/nvm-sh/nvm/raw/master/install.sh | bash

Note

FastGit service may change, please refer to official information.

Domestic Homebrew Mirrors

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

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

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

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

Tip

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:

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

# Check Node.js version
node --version

# Check npm version
npm --version

Note

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

Command Not Available

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

PowerShell Execution Policy

If you encounter execution policy errors when using nvm:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

macOS Issues

Permission Errors

If you encounter permission errors when installing global npm packages:

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

Command Not Available

If commands are not available after installation, restart the terminal or manually add to PATH (usually in /usr/local/bin).

Linux Issues

Permission Errors

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.

Version Too Old

If the Node.js version installed via system package manager is too old:

1. Use NodeSource repository (recommended, see above)
2. Or use version management tools (nvm/fnm)

Checking Environment

If verification fails, check the following:

Windows

# Check if Node.js is in PATH
where node

# Check installation path
Get-Command node

macOS

# Check if Node.js is in PATH
which node

# Check installation path
ls -l $(which node)

Linux

# Check if Node.js is in PATH
which node

# Check installation path
ls -l $(which node)

# Check version details
node -v

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 Claude Code Install Claude Code AI-assisted development tool and experience the smart programming assistant.

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