Install Node.js and Your First Project

Node.js is the runtime that lets you run JavaScript on servers, build command-line tools, and power everything from small APIs to massive microservice architectures. A correct Node.js installation is the foundation for your entire backend journey.

This guide walks you through setting up Node.js on any operating system, choosing a package manager, configuring your editor, and creating your first real project. You won’t just install tools—you’ll understand why each step matters and how it fits into modern development workflows.

By the end, you’ll have:

• Node.js and npm running on your machine
• A proper development environment with VS Code
• A scaffolded project with a clean folder structure
• An understanding of package.json, dependencies, and scripts

Prerequisites: basic familiarity with the command line (Terminal, PowerShell, or Command Prompt) is helpful but not required—we’ll explain every command.

What You Will Build

You’ll create a minimal “Hello Node.js” project that responds to HTTP requests, giving you a real, runnable application instead of just a console.log. The process follows a clear pipeline:

Once you finish, you’ll be able to open http://localhost:3000 in a browser and see your first Node.js server response.

Install Node.js

Node.js comes in two release lines:

• LTS (Long‑Term Support): recommended for production and beginners. It gets security patches and bug fixes for 30 months.
• Current: the latest features, but support ends quickly once a new major version ships.

[!NOTE] Always choose the LTS version. It’s stable, widely adopted, and supported by every package and cloud platform.

The official installer bundles npm (Node Package Manager) automatically. You get everything you need in one step.

Version Management (Optional but Recommended)

If you work on multiple projects, you may need to switch Node.js versions. Consider a version manager:

Tool	Platforms	Notes
nvm	macOS, Linux, WSL	Most popular; installs per‑user
fnm	Windows, macOS, Linux	Fast, Rust‑based, compatible with .node-version
nvm‑windows	Windows	nvm‑like experience for Windows
Volta	All platforms	Rust‑based, integrates with npm

If you’re just starting, a single LTS installation is perfectly fine. You can add a version manager later.

Install on Windows

1. Visit nodejs.org and download the LTS Windows Installer (.msi).
2. Run the installer. Accept the license and keep the default installation path.
3. On the Custom Setup screen, ensure Add to PATH is selected.
4. Complete the installation.

After installation, open PowerShell or Command Prompt and verify:

node -v
npm -v

Expected output (versions may differ):

v20.11.0
10.2.4

[!TIP] If you see 'node' is not recognized, restart your terminal or re‑run the installer and confirm the PATH option is enabled.

Install on macOS

You have two options:

Option 1: Official Installer

Download the macOS .pkg from nodejs.org and follow the wizard. It installs Node.js and npm into /usr/local/bin.

Option 2: Homebrew (Recommended)

Homebrew makes updates and version switching easier.

brew install node

Homebrew automatically manages PATH. Verify:

node -v
npm -v

[!TIP] Homebrew keeps your Node.js in a consistent location and lets you upgrade with a single brew upgrade node command.

Install on Linux

Use your distribution’s package manager, but avoid the default system package—it’s often outdated. Instead, use NodeSource or the official binary.

Ubuntu / Debian (using NodeSource)

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

Fedora

curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo dnf install nodejs -y

CentOS / RHEL

Same as Fedora using the NodeSource RPM repository.

Arch Linux

sudo pacman -S nodejs npm

After installation, verify with node -v and npm -v.

Verify Installation

Open a terminal and run:

node -v
npm -v

You should see version numbers, not error messages. If you get a command not found, the installation PATH likely needs adjusting—consult the troubleshooting section.

Choose a Package Manager

Node.js ships with npm, but two other excellent options exist. The table below helps you choose.

Feature	npm	pnpm	Yarn
Speed	Good (improved in v8+)	Fastest (via hard links)	Fast
Disk efficiency	Duplicates packages per project	Deduplicates globally; saves GBs	PnP mode avoids node_modules
Workspace support	Native (v7+)	Excellent, production‑proven	Mature
Lock file	package-lock.json	pnpm-lock.yaml	yarn.lock
Strictness	Moderate	Strict (no phantom deps)	Strict (in PnP mode)
Recommended for beginners	✅ Start here	✅ Switch when managing monorepos	✅ Good for established teams

[!TIP] Start with npm. It’s pre‑installed, heavily documented, and perfectly fine for learning. Once you build larger monorepos or need performance optimizations, adopt pnpm.

To switch to pnpm later:

npm install -g pnpm
pnpm --version

Install Visual Studio Code

VS Code is the de facto editor for Node.js development. Download it from code.visualstudio.com.

Recommended Extensions

Extension	Purpose
ESLint	Lint JavaScript/TypeScript
Prettier	Code formatter
JavaScript (ES6) code snippets	Productivity shortcuts
npm Intellisense	Auto‑complete package imports
DotENV	Syntax highlighting for .env files
Thunder Client	REST API testing inside VS Code

[!NOTE] The integrated terminal (`Ctrl + ``) is your best friend—you can run Node.js, npm, and Git without leaving the editor.

Create Your First Node.js Project

Open a terminal and create a project folder:

mkdir hello-node
cd hello-node
npm init -y

The -y flag accepts all defaults, producing a package.json file.

Your folder now contains:

hello-node/
└── package.json

Understand package.json

Open package.json. It’s the heart of any Node.js project—a manifest that holds metadata, scripts, and dependencies.

{
  "name": "hello-node",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Important Fields

Field	Description
name	Project name (lowercase, no spaces).
version	Semantic versioning.
scripts	Custom commands runnable via npm run <name>.
dependencies	Packages needed in production (populated after npm install).
devDependencies	Packages needed only during development (testing, linting).
type	If set to "module", enables ES Module imports (import instead of require).
engines	Specifies required Node.js version range (e.g., "node": ">=18").

Create Your First JavaScript File

Create index.js in the project root:

const express = require('express');
const app = express();
const port = 3000;

app.get('/', (req, res) => {
  res.send('Hello Node.js from NodeDevPro.com!');
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

This small file creates a web server using Express—a real backend, not just a console.log.

Run Your First Program

Since Express isn’t installed yet, you’ll get an error if you run the above code now. We’ll fix that next. First, let’s run a simpler version to confirm Node.js works.

Temporarily replace index.js with:

console.log("Hello Node.js! Your installation is perfect.");

Then run:

node index.js

Output:

Hello Node.js! Your installation is perfect.

Node.js reads the file, executes the JavaScript, and exits. Now you’re ready for dependencies.

Install Your First Dependency

Bring the Express server code back into index.js. Then install Express:

npm install express

This command does three things:

1. Downloads Express and its own dependencies into a node_modules folder.
2. Adds express to dependencies in package.json.
3. Creates or updates package-lock.json to lock exact versions for reproducible builds.

Now run the server:

node index.js

Open http://localhost:3000 in your browser. You’ll see the response from your first Node.js API.

[!WARNING] Never delete package-lock.json unless you’re troubleshooting. Always commit it to version control—it ensures every teammate gets the same dependency tree.

Recommended Project Structure

For anything beyond a single file, organize your code early. Here’s a production‑ready folder layout:

hello-node/
├── src/
│   ├── controllers/   # Request handling logic
│   ├── routes/        # Route definitions
│   ├── services/      # Business logic
│   ├── middlewares/   # Custom middleware (auth, logging)
│   └── utils/         # Helper functions
├── config/            # Environment‑based configuration
├── tests/             # Unit and integration tests
├── package.json
├── .env.example       # Template for environment variables
├── .gitignore
└── README.md

For this first project, just add an src folder and move your index.js there. You’ll evolve the structure as you build more complex applications.

Configure Git

Initialize a Git repository to track changes:

git init

Create a .gitignore file to prevent bulky or sensitive files from being committed:

# Dependencies
node_modules/

# Environment variables
.env

# IDE specific
.vscode/
.idea/

# Logs
*.log

# OS files
.DS_Store
Thumbs.db

Then commit your work:

git add .
git commit -m "Initial commit: Node.js project setup"

Useful npm Scripts

Replace the default test script in package.json with practical commands:

"scripts": {
  "start": "node src/index.js",
  "dev": "node --watch src/index.js",
  "test": "echo \"Add tests soon\" "
}

• npm start – runs the app in production mode.
• npm run dev – uses the built‑in --watch flag (Node.js 18+) to restart on file changes.
• npm test – placeholder for future test suites.

[!NOTE] For more advanced auto‑restarts, you’ll later adopt nodemon or pm2. But the native --watch is perfect for your first project.

Development Workflow

A modern Node.js workflow looks like this:

You don’t need all of this today. Just get comfortable with coding, running, and committing. The rest will be introduced in later guides.

Common Installation Problems

'node' is not recognized

Cause: Node.js is not in your PATH.
Fix: Re‑run the installer and ensure “Add to PATH” is selected, or manually add the Node.js installation directory to your system PATH.

npm install permission errors (EACCES)

Cause: Global installations try to write to a protected folder.
Fix: Use a Node version manager (nvm, fnm, Volta) which installs Node.js to your user directory and avoids permission problems.

npm command not found on Linux

Cause: Missing or broken installation.
Fix: Re‑install using NodeSource or verify that /usr/bin/node exists. Check your shell’s PATH (echo $PATH).

Version conflicts

Cause: Global packages depend on a different Node.js version.
Fix: Use nvm or fnm to switch versions per project. A .nvmrc or .node-version file can automate this.

Proxy / network issues

Cause: Corporate firewall blocks npm registry.
Fix: Configure npm proxy settings or switch to a mirror registry.

SSL certificate errors

Cause: Outdated root certificates.
Fix: Update Node.js to the latest LTS, or temporarily use npm config set strict-ssl false (not recommended long‑term).

Package installation failures

Cause: Corrupted cache or incompatible peer dependencies.
Fix: Clear npm cache (npm cache clean --force) and delete node_modules and package-lock.json, then reinstall.

Best Practices

• Always use LTS versions in production. Current releases may break.
• Keep Node.js updated. At minimum, stay on the latest LTS to receive security patches.
• Avoid global packages whenever possible. Use npx to run tools like create-react-app without installing globally.
• Commit package-lock.json. It ensures reproducible installs across environments.
• Use environment variables for config. Never hard‑code secrets; use a .env file and load with dotenv.
• Keep dependencies updated regularly. Use npm outdated to see what needs upgrading.
• Prefer pnpm for large projects or monorepos. It reduces disk usage and enforces strict dependency resolution.
• Use .gitignore from the start. Prevent node_modules from polluting your repository.

Frequently Asked Questions

1. Should I install LTS or Current?
LTS. It’s stable, supported, and what you’ll use in 99% of professional environments.

2. Do I need npm if I use pnpm?
No. pnpm replaces npm entirely for package management. You can still use npm occasionally for other tasks, but pnpm is your primary client.

3. What is node_modules?
The folder where all installed dependencies live. You should never manually edit files inside it, and it should be excluded from version control.

4. Can I have multiple Node.js versions installed?
Yes, using a version manager like nvm or fnm. This is essential when working on multiple projects with different requirements.

5. Why is package-lock.json important?
It locks the exact version of every dependency, guaranteeing that every environment installs the same code. Without it, subtle version differences can cause hard‑to‑debug bugs.

6. What is the --save flag? Is it still needed?
No. Since npm v5, npm install automatically saves to dependencies. --save-dev is still required for dev dependencies.

7. How do I update Node.js?
Use your version manager (nvm install --lts) or download the latest LTS installer. For macOS with Homebrew: brew upgrade node.

8. Can I use ES modules (import) instead of require?
Yes. Either add "type": "module" to package.json or use the .mjs extension. Our examples start with CommonJS for broad compatibility.

9. Why do I need VS Code extensions?
They provide linting, formatting, and IntelliSense that catch errors early and make you more productive. You can start without them, but you’ll benefit immediately.

10. What if I encounter a bug in Node.js?
Check the official GitHub issues and documentation. Most problems are solved by ensuring you’re on the latest LTS and have cleared your npm cache.

Summary

You’ve successfully completed a Node.js installation and created your first project. More importantly, you now understand the toolchain that powers millions of backend applications:

• Node.js LTS is installed and verified on your OS.
• npm (or your chosen package manager) is ready.
• VS Code is configured for Node.js development.
• Your first project, including package.json and a folder structure, is set up.
• You’ve installed Express and run a real HTTP server.

From here, deepen your knowledge by exploring the package manager ecosystem, project architecture, and Node.js core concepts. The next recommended articles in this series are:

• Understanding npm, pnpm, and Yarn – master package management
• Node.js Project Structure Best Practices – architect maintainable applications
• Understanding the Node.js Event Loop – the engine behind every Node.js process

Every advanced Node.js journey begins with a single node index.js. You just took that step. Keep building.