Installing Node.js and npm for the First Time

For those who are using JavaScript to develop a web project for the first time, installing Node.js and npm (Node’s default package manager) is an essential first step.

These tools are required to run and build JavaScript/TypeScript projects, including Astro-based websites.

Step-by-step Guide to Install Node.js and npm Globally:#

Option 1: Install via Node.js Official Website#

Visit: https://nodejs.org
Download the LTS version (Long Term Support), which is the most stable for development.
Install it like a regular app (on macOS, Windows, or Linux).

After installation, open your terminal (or WebStorm’s built-in terminal) and check:

node -v     # shows Node.js version
npm -v      # shows npm version

You should see something like:

v20.11.1
10.2.4

If these show up, you’re ready to use JavaScript tools like npm, pnpm, or yarn.

# Then install pnpm globally

npm install -g pnpm

Option 2: Use `nvm` to Manage Multiple Node.js Versions (Recommended for Developers)#

If you’d like more flexibility (for example, different projects require different Node versions), use nvm (Node Version Manager):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Restart terminal, then run:
nvm install --lts
nvm use --lts

Then check:

node -v
npm -v

This method is especially useful for managing environments, similar to using pyenv or conda in Python.

After Node.js and npm are installed, you can install pnpm globally if your project uses it:

npm install -g pnpm

Then run:

pnpm install
pnpm dev

Your Astro/JavaScript project should now be up and running.

Recap#

For first-time WebStorm or JavaScript users:

Yes, you do need to install Node.js + npm globally;
Tools like nvm make managing Node.js versions cleaner and safer;
Once installed, pnpm, npm, and node_modules handle everything inside the project — no need for a separate “virtual environment” like in Python.

Common Errors When Installing Node.js and pnpm (And How to Fix Them)#

When setting up a Node.js-based project (e.g. Astro) for the first time, it’s common to encounter installation-related errors. This section explains several typical issues and how to resolve them.

Error 1: command not found: pnpm#

Cause: pnpm is not installed globally on the system.

How to fix:

Install pnpm using npm:

npm install -g pnpm

If pnpm -v shows a version number afterwards, you’re good to go.

Error 2: EEXIST: file already exists#

Error message example:

npm ERR! EEXIST: file already exists, symlink '/usr/local/bin/pnpx'

Cause: There’s a leftover or conflicting file at /usr/local/bin/pnpx, which blocks the installation of pnpm.

Solutions:

✅ Option 1: Force the installation (quick fix)

npm install -g pnpm --force

✅ Option 2: Clean the conflicting file (recommended)

sudo rm /usr/local/bin/pnpx
npm install -g pnpm

After that, verify installation:

pnpm -v

Error 3: astro: command not found#

Cause: You are trying to run the project with pnpm dev before installing dependencies, so the astro command is missing.

Solution:

Install all dependencies first:

pnpm install

Then start the development server:

pnpm dev

This should launch your Astro project on http://localhost:4321/.

Extra Tip: How to Confirm Your Setup is Working#

After installation, check the following versions:

node -v   # should return something like v20.11.1
npm -v    # e.g. 10.2.4
pnpm -v   # e.g. 9.1.2

If all three commands work, you’re ready to develop!