1. Introduction

Before you can build anything with Node.js, you need a properly configured environment. This tutorial walks through installing Node.js, choosing the right package manager, and setting up a clean, production-ready project structure — including package.json, dependencies, linting, formatting, and TypeScript. 🛠️

2. Preparing Your Environment

System Requirements

Installing Node.js

There are several ways to install Node.js, and the right one depends on how much control you want over versions later on.

# Using Homebrew
brew install node

winget install OpenJS.NodeJS.LTS

# Debian / Ubuntu
sudo apt update
sudo apt install nodejs npm

Node.js Release Types

Node.js publishes two parallel release lines simultaneously, each serving a different purpose.

LTS vs Current

Every even-numbered major Node.js version (e.g. 18, 20, 22) eventually becomes an LTS release, receiving bug fixes and security patches for 30 months. Odd-numbered versions are short-lived and never promoted to LTS.

Node Version Manager (nvm)

nvm lets you install and switch between multiple Node.js versions on the same machine — essential when different projects require different versions.

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

# Install and use the latest LTS version
nvm install --lts
nvm use --lts

# Install a specific version
nvm install 20.11.0

# Switch between installed versions
nvm use 18

Verifying Installation

Once installed, confirm that both Node.js and npm are available on your PATH:

node --version
# v20.11.0

npm --version
# 10.2.4

3. Package Managers

Understanding npm

npm (Node Package Manager) is installed automatically with Node.js. It manages your project's dependencies, exposes scripts for common tasks, and connects you to the public npm registry — home to over a million packages. 📦

Understanding Package Managers

A package manager resolves, downloads, and organizes your project's dependencies (and their own sub-dependencies) so you don't have to manage them by hand. Several alternatives to npm have emerged, each with different trade-offs around speed, disk usage, and strictness.

npm

npm install express
npm install --save-dev nodemon
npm run start

Yarn

yarn add express
yarn add --dev nodemon
yarn start

pnpm

pnpm add express
pnpm add -D nodemon
pnpm run start

Bun

bun add express
bun add -d nodemon
bun run start

4. Creating Your First Node.js Project

Project Structure

A clean, conventional project structure makes a codebase easier to navigate as it grows. A typical setup looks like this:

Understanding package.json

package.json is the manifest file at the root of every Node.js project. It records the project's name, version, dependencies, scripts, and metadata.

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "A sample Node.js project",
  "main": "src/index.js",
  "type": "module",
  "scripts": {
    "start": "node src/index.js",
    "dev": "nodemon src/index.js",
    "test": "vitest"
  },
  "dependencies": {
    "express": "^4.19.2"
  },
  "devDependencies": {
    "nodemon": "^3.1.0"
  }
}

Understanding package-lock.json

While package.json declares version ranges (like ^4.19.2), package-lock.json records the exact version of every installed package — including sub-dependencies — ensuring everyone on a team installs identical dependency trees.

Initializing a Project

mkdir my-app && cd my-app
npm init -y

The -y flag accepts all default values. Omit it if you'd like npm to prompt you interactively for each field.

Installing Dependencies

npm install express dotenv

This adds both packages under dependencies in package.json and downloads them into node_modules.

Installing Development Dependencies

Development dependencies are tools needed only while building the project — like test runners, linters, and formatters — not when it runs in production.

npm install --save-dev eslint prettier nodemon

Running Scripts

Scripts defined in package.json can be run with npm run <script-name>. A few conventional names — like start and test — can be run without the run keyword.

npm start
npm test
npm run dev

5. Writing and Running Code

Creating Your First Program

console.log('Hello, Node.js! 👋');

Running Node.js Applications

node src/index.js

The Node.js REPL

Typing node with no arguments opens the REPL (Read-Eval-Print Loop) — an interactive shell for experimenting with JavaScript directly in your terminal.

$ node
> 2 + 2
4
> const greet = (name) => `Hi, ${name}`;
undefined
> greet('Node')
'Hi, Node'
> .exit

Environment Variables

Environment variables let you keep configuration and secrets (like API keys) outside your codebase. The dotenv package loads variables from a .env file into process.env.

PORT=3000
DATABASE_URL=postgres://localhost:5432/mydb

import 'dotenv/config';

console.log(process.env.PORT); // 3000

6. Module Systems and Tooling

ES Modules Setup

ES Modules (import / export) are the modern, standardized module format shared with browser JavaScript. Enable them by setting "type": "module" in package.json.

{
  "type": "module"
}

export function add(a, b) {
  return a + b;
}

import { add } from './math.js';

console.log(add(2, 3)); // 5

CommonJS Setup

CommonJS (require / module.exports) is Node.js's original module system and remains the default when "type" is omitted or set to "commonjs".

function add(a, b) {
  return a + b;
}

module.exports = { add };

const { add } = require('./math.js');

console.log(add(2, 3)); // 5

ESLint Setup

ESLint analyzes your code for potential errors and enforces consistent style rules.

npm install --save-dev eslint
npx eslint --init

{
  "env": { "node": true, "es2022": true },
  "extends": "eslint:recommended",
  "rules": {
    "no-unused-vars": "warn",
    "no-console": "off"
  }
}

Prettier Setup

Prettier automatically formats your code for consistent style, complementing ESLint's focus on correctness.

npm install --save-dev prettier

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5"
}

TypeScript Setup

TypeScript adds static typing to JavaScript, catching many errors before code ever runs.

npm install --save-dev typescript @types/node
npx tsc --init

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src"]
}

7. Ongoing Maintenance

Development Workflow

A typical daily workflow combines several of the tools covered above:

Updating Dependencies

# See which packages are outdated
npm outdated

# Update within the version ranges in package.json
npm update

# Check for known vulnerabilities
npm audit
npm audit fix

Common Installation Issues

Troubleshooting

rm -rf node_modules package-lock.json
npm install

8. Summary

Best Practices

Summary

A solid Node.js setup starts with the right installation strategy, a well-chosen package manager, and a clean project structure governed by package.json. Layering in linting, formatting, and optionally TypeScript establishes a foundation that scales comfortably as your project grows. ✅