JWT (JSON Web Token) is a popular, stateless way to handle authentication. Once a user logs in, you give them a token. They include this token with every request, and you verify it to confirm they're authenticated.

Why Authentication Exists

Imagine a banking app. You log in, and your account is yours alone. If anyone could access anyone else's account, the app would be useless and insecure.

Authentication answers one question: "Who are you?" Once you've answered that question by logging in, the app trusts that you are who you claim to be.

What Is JWT?

JWT is a self-contained token that includes:

1. User information (claims)

2. A signature to verify it hasn't been tampered with

3. An expiry time so old tokens eventually become invalid

It's like a digital ID card that proves you are who you say you are.

JWT Structure

A JWT has three parts separated by dots:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Part 1: Header

{
  "alg": "HS256",
  "typ": "JWT"
}

This tells you the algorithm used to sign the token and that it's a JWT.

Part 2: Payload (Claims)

{
  "userId": 123,
  "username": "john",
  "email": "john@example.com",
  "iat": 1516239022,
  "exp": 1516325422
}

This is the data about the user. iat is when it was issued, exp is when it expires.

Part 3: Signature

SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

This is created by signing the header and payload with a secret key. It prevents tampering.

Login Flow with JWT

Here's how JWT authentication works:

1. User logs in → Sends username and password

2. Server validates → Checks credentials in database

3. Server creates token → Encodes user info into JWT

4. Server returns token → Sends JWT to client

5. Client stores token → Saves it in localStorage or a cookie

6. Client sends token → Includes it with every request

7. Server verifies token → Checks signature and expiry

8. Server grants access → If valid, allows the request

Setting Up JWT in Express

First, install the jsonwebtoken package:

npm install jsonwebtoken

Here's a basic example:

import express from 'express';
import jwt from 'jsonwebtoken';

const app = express();
app.use(express.json());

const SECRET_KEY = 'your-secret-key-keep-it-safe';

// Login route
app.post('/login', (req, res) => {
  // In real apps, validate username/password against database
  const user = {
    userId: 123,
    username: 'john',
    email: 'john@example.com'
  };

  // Create JWT token
  const token = jwt.sign(user, SECRET_KEY, { expiresIn: '1h' });

  res.json({ message: 'Login successful', token });
});

app.listen(3000, () => {
  console.log('Server running');
});

When someone posts to /login, they receive a JWT token.

Verifying Tokens

Now protect routes by checking if the token is valid:

import express from 'express';
import jwt from 'jsonwebtoken';

const app = express();
app.use(express.json());

const SECRET_KEY = 'your-secret-key-keep-it-safe';

// Middleware to verify token
function verifyToken(req, res, next) {
  const token = req.headers.authorization?.split(' ')[1];

  if (!token) {
    return res.status(401).json({ error: 'No token provided' });
  }

  try {
    const decoded = jwt.verify(token, SECRET_KEY);
    req.user = decoded;
    next();
  } catch (error) {
    res.status(401).json({ error: 'Invalid token' });
  }
}

app.post('/login', (req, res) => {
  const user = { userId: 123, username: 'john' };
  const token = jwt.sign(user, SECRET_KEY, { expiresIn: '1h' });
  res.json({ token });
});

// Protected route
app.get('/profile', verifyToken, (req, res) => {
  res.json({ message: `Welcome ${req.user.username}` });
});

app.listen(3000);

The verifyToken middleware checks the token before allowing access to /profile.

How to Send a Token

After login, clients include the token in the Authorization header:

// Client-side (in browser or mobile app)
const token = 'eyJhbGc...'; // Token received from login

fetch('http://localhost:3000/profile', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})
.then(res => res.json())
.then(data => console.log(data));

The format is: Authorization: Bearer [token]

The server extracts the token after the word "Bearer".

Complete Authentication Example

Here's a complete login and protected route system:

import express from 'express';
import jwt from 'jsonwebtoken';

const app = express();
app.use(express.json());

const SECRET_KEY = 'super-secret-key';

// Sample user database
const users = [
  { id: 1, username: 'john', password: 'password123' },
  { id: 2, username: 'jane', password: 'password456' }
];

// Middleware to verify token
function verifyToken(req, res, next) {
  const token = req.headers.authorization?.split(' ')[1];

  if (!token) {
    return res.status(401).json({ error: 'No token provided' });
  }

  try {
    const decoded = jwt.verify(token, SECRET_KEY);
    req.user = decoded;
    next();
  } catch (error) {
    res.status(401).json({ error: 'Invalid or expired token' });
  }
}

// Login route
app.post('/login', (req, res) => {
  const { username, password } = req.body;

  // Find user (in real apps, check against hashed passwords)
  const user = users.find(u => u.username === username && u.password === password);

  if (!user) {
    return res.status(401).json({ error: 'Invalid credentials' });
  }

  // Create token
  const token = jwt.sign(
    { userId: user.id, username: user.username },
    SECRET_KEY,
    { expiresIn: '24h' }
  );

  res.json({ message: 'Login successful', token });
});

// Protected route
app.get('/profile', verifyToken, (req, res) => {
  res.json({
    message: `Hello ${req.user.username}`,
    userId: req.user.userId
  });
});

// Another protected route
app.get('/dashboard', verifyToken, (req, res) => {
  res.json({ message: 'Dashboard for ' + req.user.username });
});

app.listen(3000, () => {
  console.log('Auth server running');
});

Token Expiry

Tokens expire to limit damage if a token is stolen. Create tokens with an expiry:

const token = jwt.sign(user, SECRET_KEY, { expiresIn: '1h' });

After 1 hour, the token is invalid, and the user must log in again.

When someone uses an expired token, jwt.verify throws an error, and they get a 401 response.

Refresh Tokens

For better user experience, use refresh tokens. These are long-lived tokens that generate new short-lived access tokens:

app.post('/login', (req, res) => {
  const user = { userId: 123, username: 'john' };

  // Short-lived access token
  const accessToken = jwt.sign(user, SECRET_KEY, { expiresIn: '15m' });

  // Long-lived refresh token
  const refreshToken = jwt.sign(user, REFRESH_SECRET, { expiresIn: '7d' });

  res.json({ accessToken, refreshToken });
});

app.post('/refresh', (req, res) => {
  const { refreshToken } = req.body;

  try {
    const decoded = jwt.verify(refreshToken, REFRESH_SECRET);
    const newAccessToken = jwt.sign(
      { userId: decoded.userId, username: decoded.username },
      SECRET_KEY,
      { expiresIn: '15m' }
    );
    res.json({ accessToken: newAccessToken });
  } catch (error) {
    res.status(401).json({ error: 'Invalid refresh token' });
  }
});

Users use the short-lived access token for requests. When it expires, they use the refresh token to get a new access token without logging in again.

Important Security Practices

Keep your secret safe: Never commit it to Git. Use environment variables:

const SECRET_KEY = process.env.JWT_SECRET;

Use HTTPS only: Always transmit tokens over HTTPS to prevent interception.

Don't store sensitive data in tokens: JWT tokens are encoded, not encrypted. Anyone can decode them and read the payload. Don't include passwords or payment info.

Set reasonable expiry times: Shorter expiry means less damage if a token is stolen. Balance with user convenience.

Hash passwords: Never store plain passwords in your database. Always hash them.

Common Mistakes

Mistake 1: Storing passwords in JWT

// Wrong
const token = jwt.sign({
  username: user.username,
  password: user.password
}, SECRET_KEY);

// Right
const token = jwt.sign({
  userId: user.id,
  username: user.username
}, SECRET_KEY);

Mistake 2: Using a weak secret

// Wrong - too simple
const SECRET_KEY = 'secret';

// Better - long random string
const SECRET_KEY = process.env.JWT_SECRET;

Mistake 3: Not checking token expiry

jwt.verify handles expiry checking automatically. Don't skip it.

Key Takeaways

• JWT is a self-contained token with user information and a signature

• Users get a token after login and include it with every request

• Tokens expire to limit damage if stolen

• Verify tokens with jwt.verify before allowing access

• Use middleware to check tokens on protected routes

• Keep your secret key safe and use environment variables

• Tokens are encoded, not encrypted, so don't store sensitive data

• Use refresh tokens for better user experience with short-lived access tokens

JWT is a powerful, flexible way to handle authentication in Node.js applications. Once you understand the basics, you can build secure APIs.

What Are Cookies?

Cookies are small pieces of data stored on the client's browser. When you set a cookie, the browser automatically sends it with every request to your server.

Think of cookies like a stamp on your hand at an amusement park. Once you get the stamp, you show it to staff at each ride. The staff don't need to check your ticket every time.

Here's how cookies work:

1. Server sends a Set-Cookie header in the response

2. Browser stores the cookie

3. Browser automatically includes the cookie in every request back to the server

// Setting a cookie in Express
res.cookie('username', 'john', { httpOnly: true, maxAge: 3600000 });
res.send('Cookie set');

Cookies are just a transport mechanism. By themselves, they don't authenticate anyone. They need to work with either sessions or JWT to be useful.

What Are Sessions?

A session is server-side storage of user information. When a user logs in, the server creates a session and stores data about that user. The server then sends a session ID to the client, which stores it in a cookie.

How session-based authentication works:

1. User logs in with username and password

2. Server validates credentials and creates a session

3. Server stores session data (like user ID) in memory or a database

4. Server sends session ID in a cookie

5. Browser includes the session cookie in every request

6. Server looks up the session ID to find user information

This is stateful authentication. The server maintains state about who's logged in.

import express from 'express';
import session from 'express-session';

const app = express();

app.use(session({
  secret: 'your-secret-key',
  resave: false,
  saveUninitialized: true,
  cookie: { maxAge: 1000 * 60 * 60 * 24 } // 24 hours
}));

app.post('/login', (req, res) => {
  // Verify user credentials
  const userId = 123;
  
  // Store in session
  req.session.userId = userId;
  res.send('Logged in');
});

app.get('/profile', (req, res) => {
  if (req.session.userId) {
    res.send(`Welcome user ${req.session.userId}`);
  } else {
    res.status(401).send('Not logged in');
  }
});

What is JWT?

JWT stands for JSON Web Token. It's a self-contained token that includes all the information the server needs to authenticate a user. Instead of storing session data on the server, you encode the data into the token itself.

JWT structure:

A JWT has three parts separated by dots: header.payload.signature

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

• Header: Specifies the algorithm used to sign the token

• Payload: Contains claims (data) like user ID and username

• Signature: Ensures the token hasn't been tampered with

Here's how JWT authentication works:

1. User logs in with username and password

2. Server validates credentials

3. Server creates a JWT with user information

4. Server sends JWT to the client

5. Client stores JWT (usually in localStorage or a cookie)

6. Client sends JWT in the Authorization header with each request

7. Server verifies the signature and extracts user information

import express from 'express';
import jwt from 'jsonwebtoken';

const app = express();
const SECRET_KEY = 'your-secret-key';

app.post('/login', (req, res) => {
  // Verify user credentials
  const userId = 123;
  const username = 'john';
  
  // Create JWT
  const token = jwt.sign(
    { userId, username },
    SECRET_KEY,
    { expiresIn: '24h' }
  );
  
  res.json({ token });
});

app.get('/profile', (req, res) => {
  const token = req.headers.authorization?.split(' ')[1];
  
  if (!token) {
    return res.status(401).send('No token');
  }
  
  try {
    const decoded = jwt.verify(token, SECRET_KEY);
    res.send(`Welcome ${decoded.username}`);
  } catch (error) {
    res.status(401).send('Invalid token');
  }
});

Sessions vs JWT: Key Differences

When to Use Each

Use Sessions When:

• You're building a traditional web application with server-rendered pages

• You need immediate logout capability

• You're running on a single server or have a shared session store

• You want simpler implementation

Use JWT When:

• You're building a mobile app or single-page application

• You have multiple servers that need to authenticate users independently

• You want a stateless architecture

• You're building a public API

Use Cookies When:

• You're setting session IDs or tokens

• You need automatic browser handling

• You're building traditional web apps

Common Security Practices

For Sessions:

• Use secure, HttpOnly cookies

• Set appropriate session timeout

• Regenerate session ID on login

• Use HTTPS only

For JWT:

• Sign tokens with a strong secret

• Use HTTPS to prevent token interception

• Set reasonable expiry times

• Consider using refresh tokens for longer sessions

• Keep the secret safe

Real-World Example Comparison

Let's say you have a simple blogging platform. Here's how each approach handles a request flow:

Session-based flow:

1. User logs in → Server creates session with user ID

2. User requests profile → Server checks session, recognizes user

3. User logs out → Server deletes session

JWT-based flow:

1. User logs in → Server creates token with user ID

2. User requests profile → Token sent with request, server verifies signature

3. User logs out → Client simply deletes token

Key Takeaways

• Cookies are just a transport mechanism, not authentication by themselves

• Sessions are stateful: server stores user information

• JWT is stateless: user information is stored in the token itself

• Sessions are easier for traditional web apps and immediate logout

• JWT scales better for distributed systems and APIs

• Both can use cookies for transport; the difference is what data is stored where

Choose the approach based on your application architecture. Traditional web apps often use sessions, while modern APIs and mobile apps commonly use JWT.

What is an API?

An API (Application Programming Interface) is a contract between client and server. It says: "Send me this format, and I'll respond with that format."

For example, a social media API might say: "POST to /posts with a message, and I'll create a post."

What is REST?

REST (Representational State Transfer) is a style of designing APIs. It uses HTTP methods (GET, POST, PUT, DELETE) and URLs to represent operations on resources.

A resource is something you can create, read, update, or delete. Examples: users, posts, comments, products.

Instead of having endpoints like:

• /createUser
• /getUserData
• /deleteUser

REST uses the resource URL with HTTP methods:

• GET /users - Get all users
• POST /users - Create a user
• GET /users/123 - Get user 123
• PUT /users/123 - Update user 123
• DELETE /users/123 - Delete user 123

This is cleaner and more logical.

HTTP Methods for CRUD

REST maps HTTP methods to database operations:

These four methods handle all basic operations (CRUD: Create, Read, Update, Delete).

Basic REST API Example

Here's a simple REST API for managing blog posts:

import express from 'express';

const app = express();
app.use(express.json());

// Sample data
let posts = [
  { id: 1, title: 'First Post', content: 'Hello world' },
  { id: 2, title: 'Second Post', content: 'Another post' }
];

// GET all posts
app.get('/posts', (req, res) => {
  res.json(posts);
});

// GET a single post
app.get('/posts/:id', (req, res) => {
  const post = posts.find(p => p.id === parseInt(req.params.id));
  if (!post) {
    return res.status(404).json({ error: 'Post not found' });
  }
  res.json(post);
});

// CREATE a new post
app.post('/posts', (req, res) => {
  const newPost = {
    id: posts.length + 1,
    title: req.body.title,
    content: req.body.content
  };
  posts.push(newPost);
  res.status(201).json(newPost);
});

// UPDATE a post
app.put('/posts/:id', (req, res) => {
  const post = posts.find(p => p.id === parseInt(req.params.id));
  if (!post) {
    return res.status(404).json({ error: 'Post not found' });
  }
  post.title = req.body.title || post.title;
  post.content = req.body.content || post.content;
  res.json(post);
});

// DELETE a post
app.delete('/posts/:id', (req, res) => {
  const index = posts.findIndex(p => p.id === parseInt(req.params.id));
  if (index === -1) {
    return res.status(404).json({ error: 'Post not found' });
  }
  const deleted = posts.splice(index, 1);
  res.json({ message: 'Post deleted', post: deleted[0] });
});

app.listen(3000);

This API covers all CRUD operations for posts.

Naming Conventions

Follow these conventions for clean URLs:

• Use plural nouns for resources: /posts, /users, /products (not /post, /user)
• Use lowercase: /posts (not /Posts)
• Use hyphens for multi-word resources: /blog-posts (not /blogposts or /blog_posts)
• Avoid verbs in URLs: Use HTTP methods instead
  • Wrong: GET /posts/getAll
  • Right: GET /posts

Status Codes

Use appropriate HTTP status codes:

app.get('/posts/:id', (req, res) => {
  const post = posts.find(p => p.id === parseInt(req.params.id));
  if (!post) {
    return res.status(404).json({ error: 'Post not found' });
  }
  res.status(200).json(post); // 200 is default, can omit
});

app.post('/posts', (req, res) => {
  const newPost = { id: posts.length + 1, ...req.body };
  posts.push(newPost);
  res.status(201).json(newPost);
});

Handling Query Parameters

Use query parameters for filtering and sorting:

app.get('/posts', (req, res) => {
  let results = posts;

  // Filter by status
  if (req.query.status) {
    results = results.filter(p => p.status === req.query.status);
  }

  // Sort by date
  if (req.query.sort === 'date') {
    results.sort((a, b) => new Date(b.date) - new Date(a.date));
  }

  // Pagination
  const page = parseInt(req.query.page) || 1;
  const limit = parseInt(req.query.limit) || 10;
  const start = (page - 1) * limit;
  results = results.slice(start, start + limit);

  res.json(results);
});

Usage:

• GET /posts?status=published
• GET /posts?sort=date
• GET /posts?page=2&limit=5

Error Handling

Consistent error responses help clients:

app.get('/posts/:id', (req, res) => {
  const post = posts.find(p => p.id === parseInt(req.params.id));
  if (!post) {
    return res.status(404).json({
      error: {
        code: 'POST_NOT_FOUND',
        message: 'The requested post does not exist',
        details: `Post with ID ${req.params.id} not found`
      }
    });
  }
  res.json(post);
});

Structured error responses let clients handle errors properly.

Request Validation

Validate data before processing:

app.post('/posts', (req, res) => {
  const { title, content } = req.body;

  // Validation
  if (!title || !content) {
    return res.status(400).json({
      error: 'Title and content are required'
    });
  }

  if (title.length < 3) {
    return res.status(400).json({
      error: 'Title must be at least 3 characters'
    });
  }

  const newPost = { id: posts.length + 1, title, content };
  posts.push(newPost);
  res.status(201).json(newPost);
});

API Versioning

As your API grows, you might need to change it. Versioning helps:

app.get('/v1/posts', (req, res) => {
  // Version 1 implementation
  res.json(posts);
});

app.get('/v2/posts', (req, res) => {
  // Version 2 implementation (different format, more data, etc.)
  res.json(posts.map(p => ({
    id: p.id,
    title: p.title,
    description: p.content,
    createdAt: new Date()
  })));
});

This lets old clients continue using v1 while new clients use v2.

Authentication in REST APIs

Protect routes with authentication:

function authenticate(req, res, next) {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) {
    return res.status(401).json({ error: 'No token provided' });
  }
  // Verify token (simplified)
  req.user = { id: 1 };
  next();
}

app.post('/posts', authenticate, (req, res) => {
  // Create post as authenticated user
  const newPost = {
    id: posts.length + 1,
    ...req.body,
    userId: req.user.id
  };
  posts.push(newPost);
  res.status(201).json(newPost);
});

app.delete('/posts/:id', authenticate, (req, res) => {
  // Delete logic
});

Only authenticated users can create or delete.

CORS for Cross-Origin Requests

If your API is called from a different domain, enable CORS:

npm install cors

import cors from 'cors';

app.use(cors());
// or restrict to specific domains
app.use(cors({
  origin: 'https://example.com'
}));

Complete REST API Example

Here's a realistic REST API with authentication, validation, and proper status codes:

import express from 'express';

const app = express();
app.use(express.json());

let posts = [];
let nextId = 1;

// Middleware: log requests
app.use((req, res, next) => {
  console.log(`\({req.method} \){req.path}`);
  next();
});

// Middleware: authenticate
function authenticate(req, res, next) {
  const token = req.headers.authorization?.split(' ')[1];
  if (token === 'valid-token') {
    req.user = { id: 1 };
    next();
  } else {
    res.status(401).json({ error: 'Unauthorized' });
  }
}

// GET all posts
app.get('/posts', (req, res) => {
  res.json(posts);
});

// GET single post
app.get('/posts/:id', (req, res) => {
  const post = posts.find(p => p.id === parseInt(req.params.id));
  if (!post) return res.status(404).json({ error: 'Not found' });
  res.json(post);
});

// POST create post (requires auth)
app.post('/posts', authenticate, (req, res) => {
  const { title, content } = req.body;

  if (!title || !content) {
    return res.status(400).json({ error: 'Title and content required' });
  }

  const newPost = { id: nextId++, title, content, userId: req.user.id };
  posts.push(newPost);
  res.status(201).json(newPost);
});

// PUT update post
app.put('/posts/:id', authenticate, (req, res) => {
  const post = posts.find(p => p.id === parseInt(req.params.id));
  if (!post) return res.status(404).json({ error: 'Not found' });

  post.title = req.body.title || post.title;
  post.content = req.body.content || post.content;
  res.json(post);
});

// DELETE post
app.delete('/posts/:id', authenticate, (req, res) => {
  const index = posts.findIndex(p => p.id === parseInt(req.params.id));
  if (index === -1) return res.status(404).json({ error: 'Not found' });

  posts.splice(index, 1);
  res.json({ message: 'Deleted' });
});

app.listen(3000);

Key Takeaways

• REST uses HTTP methods (GET, POST, PUT, DELETE) to represent operations
• Resources are nouns, not verbs: /posts not /getPosts
• Status codes indicate operation success: 200, 201, 400, 404, 500
• Query parameters filter and sort results
• Validation catches bad data before processing
• Authentication protects sensitive operations
• Consistent error responses help clients handle errors
• Versioning lets you evolve your API without breaking clients

Build REST APIs following these principles, and you'll create clean, intuitive, maintainable APIs that developers love to use.

Why File Uploads Need Special Handling

Regular form data is text. But files are binary. When uploading files, the request format changes to multipart/form-data, which handles both text fields and binary files.

Express doesn't automatically parse this format. That's where Multer comes in.

What is Multer?

Multer is middleware for Express that handles file uploads. It parses multipart form data, extracts files, and saves them to disk or memory.

Install it:

npm install multer

Basic File Upload

Set up Multer to handle a single file:

import express from 'express';
import multer from 'multer';

const app = express();
const upload = multer({ dest: 'uploads/' });

app.post('/upload', upload.single('file'), (req, res) => {
  if (!req.file) {
    return res.status(400).send('No file uploaded');
  }
  res.send(`File ${req.file.filename} uploaded`);
});

app.listen(3000);

• multer({ dest: 'uploads/' }) saves files to the uploads/ folder

• upload.single('file') handles one file from a form field named "file"

• req.file contains file information

A user posts a file to /upload, and Multer saves it to uploads/.

Accessing File Information

After upload, req.file contains:

{
  fieldname: 'file',
  originalname: 'photo.jpg',
  encoding: '7bit',
  mimetype: 'image/jpeg',
  destination: 'uploads/',
  filename: 'file-1234567890',
  path: 'uploads/file-1234567890',
  size: 154321
}

Use this information to track what was uploaded:

app.post('/upload', upload.single('file'), (req, res) => {
  if (!req.file) {
    return res.status(400).send('No file uploaded');
  }

  res.json({
    message: 'File uploaded successfully',
    filename: req.file.filename,
    originalName: req.file.originalname,
    size: req.file.size,
    path: req.file.path
  });
});

Multiple File Uploads

Handle multiple files with upload.array():

import express from 'express';
import multer from 'multer';

const app = express();
const upload = multer({ dest: 'uploads/' });

app.post('/upload-multiple', upload.array('files'), (req, res) => {
  if (!req.files || req.files.length === 0) {
    return res.status(400).send('No files uploaded');
  }

  const fileInfo = req.files.map(file => ({
    filename: file.filename,
    originalName: file.originalname,
    size: file.size
  }));

  res.json({ files: fileInfo });
});

app.listen(3000);

req.files is an array of uploaded files.

You can limit the number of files:

upload.array('files', 5) // Max 5 files

Customizing File Names

By default, Multer generates random filenames. Configure storage to control this:

import express from 'express';
import multer from 'multer';
import path from 'path';

const app = express();

const storage = multer.diskStorage({
  destination: (req, file, cb) => {
    cb(null, 'uploads/');
  },
  filename: (req, file, cb) => {
    // Keep original extension
    const ext = path.extname(file.originalname);
    const name = path.basename(file.originalname, ext);
    const uniqueName = name + '-' + Date.now() + ext;
    cb(null, uniqueName);
  }
});

const upload = multer({ storage });

app.post('/upload', upload.single('file'), (req, res) => {
  res.json({ filename: req.file.filename });
});

app.listen(3000);

Now files are named: photo-1234567890.jpg instead of random names.

Filtering File Types

Validate file types to prevent unwanted uploads:

import express from 'express';
import multer from 'multer';

const app = express();

const storage = multer.diskStorage({
  destination: 'uploads/',
  filename: (req, file, cb) => {
    cb(null, Date.now() + '-' + file.originalname);
  }
});

const fileFilter = (req, file, cb) => {
  // Allow only images
  const allowedMimes = ['image/jpeg', 'image/png', 'image/gif'];
  
  if (allowedMimes.includes(file.mimetype)) {
    cb(null, true);
  } else {
    cb(new Error('Only image files are allowed'));
  }
};

const upload = multer({ storage, fileFilter });

app.post('/upload-image', upload.single('image'), (req, res) => {
  res.json({ message: 'Image uploaded', filename: req.file.filename });
});

app.listen(3000);

The fileFilter function checks the MIME type and rejects non-image files.

Limiting File Size

Prevent huge files from being uploaded:

const upload = multer({
  dest: 'uploads/',
  limits: {
    fileSize: 5 * 1024 * 1024 // 5MB
  }
});

app.post('/upload', upload.single('file'), (req, res) => {
  res.json({ message: 'File uploaded' });
});

Files larger than 5MB are rejected.

Handling Multiple File Fields

Upload different types of files in one request:

const app = express();

const upload = multer({ dest: 'uploads/' });

const fileUpload = upload.fields([
  { name: 'profilePic', maxCount: 1 },
  { name: 'coverPhoto', maxCount: 1 },
  { name: 'documents', maxCount: 5 }
]);

app.post('/upload-profile', fileUpload, (req, res) => {
  const profilePic = req.files.profilePic?.[0];
  const coverPhoto = req.files.coverPhoto?.[0];
  const documents = req.files.documents;

  res.json({
    profilePic: profilePic?.filename,
    coverPhoto: coverPhoto?.filename,
    documentCount: documents?.length || 0
  });
});

app.listen(3000);

req.files contains objects for each field name.

Complete Realistic Example

Here's a complete user profile upload system:

import express from 'express';
import multer from 'multer';
import path from 'path';
import { fileURLToPath } from 'url';

const app = express();
const __dirname = path.dirname(fileURLToPath(import.meta.url));

app.use(express.json());

// Configure storage
const storage = multer.diskStorage({
  destination: (req, file, cb) => {
    const uploadDir = 'uploads/profiles';
    cb(null, uploadDir);
  },
  filename: (req, file, cb) => {
    const ext = path.extname(file.originalname);
    const name = 'profile-' + Date.now() + ext;
    cb(null, name);
  }
});

// Filter to allow only images
const fileFilter = (req, file, cb) => {
  const allowedMimes = ['image/jpeg', 'image/png'];
  if (allowedMimes.includes(file.mimetype)) {
    cb(null, true);
  } else {
    cb(new Error('Only JPEG and PNG images allowed'));
  }
};

const upload = multer({
  storage,
  fileFilter,
  limits: { fileSize: 2 * 1024 * 1024 } // 2MB
});

// Serve uploaded files
app.use('/images', express.static('uploads/profiles'));

// Upload endpoint
app.post('/upload-profile', upload.single('profilePic'), (req, res) => {
  if (!req.file) {
    return res.status(400).json({ error: 'No file uploaded' });
  }

  const imageUrl = `/images/${req.file.filename}`;

  res.json({
    message: 'Profile picture uploaded',
    filename: req.file.filename,
    url: imageUrl,
    size: req.file.size
  });
});

// Error handler for Multer
app.use((err, req, res, next) => {
  if (err instanceof multer.MulterError) {
    if (err.code === 'FILE_TOO_LARGE') {
      return res.status(400).json({ error: 'File too large' });
    }
    return res.status(400).json({ error: err.message });
  }
  if (err) {
    return res.status(400).json({ error: err.message });
  }
  next();
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Memory Storage

Store files in memory instead of disk (useful for processing before saving):

const storage = multer.memoryStorage();
const upload = multer({ storage });

app.post('/process-file', upload.single('file'), (req, res) => {
  // File is in req.file.buffer (as a Buffer)
  const content = req.file.buffer.toString();
  res.json({ message: 'File processed' });
});

Common Mistakes

Mistake 1: Not handling errors

// Wrong - crashes on file too large
app.post('/upload', upload.single('file'), (req, res) => {
  res.send('Done');
});

// Right - add error handler
app.use((err, req, res, next) => {
  if (err instanceof multer.MulterError) {
    res.status(400).json({ error: err.message });
  } else {
    res.status(500).json({ error: 'Server error' });
  }
});

Mistake 2: Trusting original filename

// Wrong - security risk
const filename = file.originalname;

// Right - generate safe filename
const filename = Date.now() + '-' + file.originalname;

Mistake 3: Not validating file type

Always validate using MIME type or file extension, preferably both.

Key Takeaways

• Multer is middleware for handling file uploads in Express

• Use upload.single() for one file, upload.array() for multiple

• Configure storage to control where and how files are saved

• Use fileFilter to validate file types

• Set size limits to prevent huge uploads

• Always generate unique, safe filenames

• Use error handlers to gracefully handle upload errors

• Serve uploaded files as static files with express.static

File uploads are common in web applications. Master Multer, and you can confidently handle user-uploaded content.

Where Do Uploaded Files Live?

When a user uploads a file, it doesn't magically appear on the web. You need to decide where to store it.

There are two main approaches:

Local Storage (on your server): Files are saved to a folder on your server's disk. Your server then serves these files directly to users.

External Storage (cloud): Files are uploaded to a service like AWS S3, Google Cloud Storage, or Cloudinary. Your server doesn't store them; the cloud service does.

We'll focus on local storage first, as it's simpler to understand and perfect for learning.

Setting Up a Local Upload Folder

Create a folder where uploads will be stored:

project/
  uploads/
  server.js
  package.json

This uploads folder holds all user files.

Handling File Uploads with Multer

Express doesn't handle file uploads by default. You need middleware like Multer.

First, install Multer:

npm install multer

Here's how to set up basic file uploads:

import express from 'express';
import multer from 'multer';
import path from 'path';
import { fileURLToPath } from 'url';

const app = express();
const __dirname = path.dirname(fileURLToPath(import.meta.url));

// Configure storage
const storage = multer.diskStorage({
  destination: (req, file, cb) => {
    cb(null, 'uploads/');
  },
  filename: (req, file, cb) => {
    const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1E9);
    cb(null, file.fieldname + '-' + uniqueSuffix + path.extname(file.originalname));
  }
});

const upload = multer({ storage });

app.post('/upload', upload.single('file'), (req, res) => {
  if (!req.file) {
    return res.status(400).send('No file uploaded');
  }
  res.json({ message: 'File uploaded', filename: req.file.filename });
});

app.listen(3000, () => console.log('Server running'));

When a user uploads a file:

1. Multer intercepts the request

2. Saves the file to the uploads/ folder with a unique name

3. Adds file information to req.file

4. Your route handler processes the request

Serving Uploaded Files

Now users need to access these files. You'll serve them as static files.

Express has a built-in middleware for this:

import express from 'express';
import path from 'path';
import { fileURLToPath } from 'url';

const app = express();
const __dirname = path.dirname(fileURLToPath(import.meta.url));

// Serve files from uploads folder
app.use('/files', express.static(path.join(__dirname, 'uploads')));

app.listen(3000, () => console.log('Server running'));

Now files are accessible at http://localhost:3000/files/filename.jpg

If a file is saved as profile-1234567890.jpg in the uploads/ folder, it's accessible at:

http://localhost:3000/files/profile-1234567890.jpg

Complete Upload and Serve Example

Here's a complete example with upload and serving:

import express from 'express';
import multer from 'multer';
import path from 'path';
import { fileURLToPath } from 'url';

const app = express();
const __dirname = path.dirname(fileURLToPath(import.meta.url));

// Configure storage
const storage = multer.diskStorage({
  destination: (req, file, cb) => {
    cb(null, 'uploads/');
  },
  filename: (req, file, cb) => {
    const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1E9);
    cb(null, file.fieldname + '-' + uniqueSuffix + path.extname(file.originalname));
  }
});

const upload = multer({ storage });

// Serve uploaded files as static
app.use('/files', express.static(path.join(__dirname, 'uploads')));

app.post('/upload-profile', upload.single('profilePic'), (req, res) => {
  if (!req.file) {
    return res.status(400).json({ error: 'No file uploaded' });
  }
  
  const fileUrl = `/files/${req.file.filename}`;
  res.json({ 
    message: 'Profile picture uploaded',
    url: fileUrl 
  });
});

app.listen(3000, () => console.log('Server running'));

A user uploads a file → Multer saves it → Server returns the file URL → User can access it immediately.

Upload Process Visualization

Client                          Server                      Disk
  |                               |                          |
  |--- POST /upload (file) -----> |                          |
  |     (multipart/form-data)     |                          |
  |                               |-- Multer processes ------>|
  |                               |    saves file             |
  |                               |                          |
  |<-- 200 OK + filename ---------|                          |
  |     { url: '/files/...' }     |                          |
  |                               |                          |
  |-- GET /files/filename.jpg --> |                          |
  |                               |-- Read from disk ------> |
  |<-- 200 + file data -----------|<-- Return file data ------|

Security Considerations

Validate file types:

const upload = multer({
  storage,
  fileFilter: (req, file, cb) => {
    const allowedTypes = ['image/jpeg', 'image/png', 'image/gif'];
    if (allowedTypes.includes(file.mimetype)) {
      cb(null, true);
    } else {
      cb(new Error('Invalid file type'));
    }
  }
});

Limit file size:

const upload = multer({
  storage,
  limits: { fileSize: 5 * 1024 * 1024 } // 5MB
});

Never trust the original filename:

Always generate a new filename (like we did with timestamps and random numbers). If you use the original filename, malicious users could upload files with paths like ../../important.js to write files outside the uploads folder.

Storing Metadata

Usually, you'll want to store information about the uploaded file:

import express from 'express';
import multer from 'multer';
import path from 'path';
import { fileURLToPath } from 'url';

const app = express();
const __dirname = path.dirname(fileURLToPath(import.meta.url));

app.use(express.json());

const storage = multer.diskStorage({
  destination: (req, file, cb) => {
    cb(null, 'uploads/');
  },
  filename: (req, file, cb) => {
    const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1E9);
    cb(null, file.fieldname + '-' + uniqueSuffix + path.extname(file.originalname));
  }
});

const upload = multer({ storage });

app.use('/files', express.static(path.join(__dirname, 'uploads')));

app.post('/upload', upload.single('file'), (req, res) => {
  if (!req.file) {
    return res.status(400).json({ error: 'No file uploaded' });
  }
  
  // Store metadata about the file
  const fileData = {
    originalName: req.file.originalname,
    savedName: req.file.filename,
    size: req.file.size,
    mimetype: req.file.mimetype,
    uploadedAt: new Date(),
    url: `/files/${req.file.filename}`
  };
  
  // You'd normally save fileData to a database
  res.json(fileData);
});

app.listen(3000, () => console.log('Server running'));

Store this information in a database so you can track what was uploaded, when, and by whom.

Common Mistakes

Mistake 1: Using original filenames

Never save files with their original names. Attackers can upload files with special characters or path traversal sequences.

Mistake 2: Not validating file types

Don't just check the file extension. Someone can rename malware.exe to image.jpg. Always check the MIME type.

Mistake 3: Storing sensitive files in the web-accessible folder

Files served via express.static are publicly accessible. Don't store passwords, API keys, or sensitive data there.

Key Takeaways

• Multer middleware handles file uploads in Express

• Files are stored to disk in a designated folder

• Use express.static middleware to serve uploaded files

• Generate unique filenames to prevent security issues

• Validate file types and sizes

• Store file metadata in a database

• Never trust the original filename provided by users

Once you're comfortable with local storage, you can explore cloud storage solutions for better scalability and reliability.

URL Parameters: Part of the Route

URL parameters are placeholders in the route path. They're required and define the resource you're accessing.

Consider these examples:

/users/123          - get user with ID 123
/posts/456/comments - get comments for post 456
/products/789/reviews - get reviews for product 789

The numbers and identifiers are URL parameters. They identify which specific resource you want.

In Express, you define parameters with a colon:

import express from 'express';

const app = express();

app.get('/users/:id', (req, res) => {
  const userId = req.params.id;
  res.json({ message: `Getting user ${userId}` });
});

app.get('/posts/:postId/comments/:commentId', (req, res) => {
  const postId = req.params.postId;
  const commentId = req.params.commentId;
  res.json({ postId, commentId });
});

app.listen(3000);

When a request comes in, Express extracts the parameter values and places them in req.params.

Usage examples:

• GET /users/123 → req.params.id = "123"

• GET /posts/456/comments/789 → req.params.postId = "456", req.params.commentId = "789"

Query Strings: Optional Filters and Options

Query strings come after a question mark in the URL. They're optional and add filtering or modification options.

Consider these examples:

/users?role=admin           - filter users by role
/products?sort=price&limit=10 - sort by price, limit to 10 results
/search?q=node&lang=en      - search for "node" in English

In Express, query strings are available in req.query:

import express from 'express';

const app = express();

app.get('/users', (req, res) => {
  const role = req.query.role;
  const status = req.query.status;
  res.json({ message: `Getting users`, role, status });
});

app.get('/search', (req, res) => {
  const q = req.query.q;
  const limit = req.query.limit;
  res.json({ search: q, limit });
});

app.listen(3000);

Usage examples:

• GET /users?role=admin → req.query.role = "admin"

• GET /search?q=javascript&limit=20 → req.query.q = "javascript", req.query.limit = "20"

Parameters vs Query Strings: Key Differences

Real-World Examples

URL Parameters: Identify the exact resource you want

app.get('/users/:id', (req, res) => {
  // GET /users/123
  // Retrieve THE user with ID 123
});

app.get('/posts/:postId/comments/:commentId', (req, res) => {
  // GET /posts/456/comments/789
  // Get specific comment 789 in specific post 456
});

Query Strings: Filter or modify what you're retrieving

app.get('/users', (req, res) => {
  // GET /users?role=admin&status=active
  // Get all users, but filter by role and status
});

app.get('/posts', (req, res) => {
  // GET /posts?sort=date&limit=10&skip=20
  // Get posts, sorted by date, 10 per page, starting from position 20
});

Combining Both

You can use both parameters and query strings together:

import express from 'express';

const app = express();

app.get('/users/:id/posts', (req, res) => {
  const userId = req.params.id;
  const sort = req.query.sort;
  const limit = req.query.limit;
  
  res.json({
    message: `Getting posts for user ${userId}`,
    sort,
    limit
  });
});

app.listen(3000);

Examples:

• GET /users/123/posts → User 123's posts

• GET /users/123/posts?sort=date → User 123's posts sorted by date

• GET /users/123/posts?sort=date&limit=10 → User 123's 10 most recent posts

Multiple Query Parameters

When you have multiple query parameters, separate them with &:

app.get('/search', (req, res) => {
  const query = req.query.q;
  const lang = req.query.lang;
  const category = req.query.category;
  
  res.json({ query, lang, category });
});

Usage:

GET /search?q=javascript&lang=en&category=tutorial
→ query = "javascript", lang = "en", category = "tutorial"

Query Parameters with Arrays

You can pass multiple values for the same parameter:

app.get('/products', (req, res) => {
  const colors = req.query.color;
  res.json({ colors });
});

Usage:

GET /products?color=red&color=blue&color=green
→ colors = ["red", "blue", "green"]

Type Conversion

Query parameters always come as strings. If you need numbers, convert them:

import express from 'express';

const app = express();

app.get('/products', (req, res) => {
  const limit = parseInt(req.query.limit) || 10;
  const skip = parseInt(req.query.skip) || 0;
  
  res.json({ limit, skip });
});

app.listen(3000);

Without conversion, req.query.limit is the string "20", not the number 20.

When to Use Each

Use URL parameters when:

• Identifying a specific resource

• The value is required

• Following REST principles for resource identification

• Examples: user ID, post ID, product ID

Use query strings when:

• Filtering results

• Sorting or paginating

• The value is optional

• Adding modifiers or options

• Examples: role, category, sort order, page number

REST API Best Practices

A well-designed REST API uses both appropriately:

import express from 'express';

const app = express();

// Get all users (with optional filters)
app.get('/users', (req, res) => {
  const role = req.query.role;
  const status = req.query.status;
  // Retrieve users, optionally filtered by role and status
});

// Get specific user
app.get('/users/:id', (req, res) => {
  const userId = req.params.id;
  // Retrieve specific user by ID
});

// Get posts for a specific user (with optional sorting)
app.get('/users/:userId/posts', (req, res) => {
  const userId = req.params.userId;
  const sort = req.query.sort;
  // Retrieve posts for user, optionally sorted
});

// Get specific comment on specific post by specific user
app.get('/users/:userId/posts/:postId/comments/:commentId', (req, res) => {
  const { userId, postId, commentId } = req.params;
  // Retrieve specific comment
});

app.listen(3000);

Common Mistakes

Mistake 1: Using parameters when query strings make sense

// Wrong - parameters for filters
app.get('/users/:role/:status', (req, res) => {
  // URL becomes /users/admin/active
  // Hard to add more filters
});

// Better - query strings for filters
app.get('/users', (req, res) => {
  // URL is /users?role=admin&status=active
  // Easy to add/remove filters
});

Mistake 2: Forgetting to convert query parameters to numbers

app.get('/products', (req, res) => {
  const limit = req.query.limit; // This is a string!
  const results = db.getProducts().slice(0, limit);
  // limit as string might not slice correctly
});

Key Takeaways

• URL parameters identify a specific resource and go in the route path

• Query strings are optional filters and go after the question mark

• Parameters are required and part of the route definition

• Query strings are optional and make URLs flexible

• Access parameters via req.params and query strings via req.query

• Combine both for powerful, flexible APIs

• Use parameters for identification, query strings for filtering

Mastering both gives you the tools to build flexible, standard REST APIs that users can intuitively understand.

What Is Middleware?

Middleware is a function that has access to the request and response objects. It can modify them, perform checks, or stop the request.

Think of middleware as checkpoints in an airport:

• Security check (middleware validates the request)

• Baggage scan (middleware processes data)

• Gate (final destination/route handler)

Each checkpoint can allow you through to the next, or stop you.

In Express, middleware functions have this signature:

function middleware(req, res, next) {
  // Do something
  next(); // Pass to next middleware
}

The next() function passes control to the next middleware or route handler.

How Middleware Works

When a request arrives, Express processes it through middleware in order:

Request comes in
     |
     v
Middleware 1 (if next() called, continue)
     |
     v
Middleware 2 (if next() called, continue)
     |
     v
Route Handler (your actual route)
     |
     v
Response sent

Each middleware either calls next() to continue or sends a response to stop.

Using Express-Provided Middleware

Express provides built-in middleware for common tasks:

import express from 'express';

const app = express();

// Parse JSON requests
app.use(express.json());

// Parse URL-encoded form data
app.use(express.urlencoded({ extended: true }));

// Serve static files
app.use(express.static('public'));

app.post('/data', (req, res) => {
  // Thanks to express.json() middleware, req.body is parsed
  console.log(req.body);
  res.send('Data received');
});

app.listen(3000);

express.json() middleware automatically parses incoming JSON and populates req.body.

Creating Custom Middleware

Write your own middleware for custom logic:

import express from 'express';

const app = express();

// Custom logging middleware
function logger(req, res, next) {
  console.log(`\({req.method} \){req.url}`);
  next(); // Pass to next middleware
}

app.use(logger);

app.get('/', (req, res) => {
  res.send('Home page');
});

app.listen(3000);

Every request is logged, then passed to the route handler.

Output for GET /:

GET /

Middleware Execution Order

Middleware runs in the order you define it:

import express from 'express';

const app = express();

app.use((req, res, next) => {
  console.log('1: First middleware');
  next();
});

app.use((req, res, next) => {
  console.log('2: Second middleware');
  next();
});

app.get('/', (req, res) => {
  console.log('3: Route handler');
  res.send('Done');
});

app.listen(3000);

For a GET / request, output is:

1: First middleware
2: Second middleware
3: Route handler

Order matters. Middleware defined first runs first.

The next() Function

Calling next() passes control to the next function in the chain. Not calling it stops execution:

app.use((req, res, next) => {
  console.log('Middleware 1');
  next(); // Continue
});

app.use((req, res, next) => {
  console.log('Middleware 2');
  // Not calling next() - stops here
});

app.get('/', (req, res) => {
  console.log('Route'); // Never reached
  res.send('Hi');
});

This stops at "Middleware 2". The route handler is never called.

Types of Middleware

Application-Level Middleware

Runs for all routes or specific routes:

import express from 'express';

const app = express();

// Runs for ALL routes
app.use((req, res, next) => {
  console.log('Global middleware');
  next();
});

// Runs only for /admin routes
app.use('/admin', (req, res, next) => {
  console.log('Admin middleware');
  next();
});

app.get('/', (req, res) => res.send('Home'));
app.get('/admin/users', (req, res) => res.send('Admin page'));

app.listen(3000);

Router-Level Middleware

Middleware on a specific router:

import express from 'express';

const app = express();
const router = express.Router();

router.use((req, res, next) => {
  console.log('Router middleware');
  next();
});

router.get('/users', (req, res) => res.send('Users'));

app.use('/api', router);
app.listen(3000);

Built-In Middleware

Express provides standard middleware:

app.use(express.json());
app.use(express.static('public'));
app.use(express.urlencoded({ extended: true }));

Third-Party Middleware

Use packages from npm:

npm install cors

import cors from 'cors';

app.use(cors()); // Enable CORS

Real-World Middleware Examples

Authentication Middleware

function authenticateToken(req, res, next) {
  const token = req.headers.authorization?.split(' ')[1];

  if (!token) {
    return res.status(401).send('No token');
  }

  // Verify token (simplified)
  if (token === 'valid-token') {
    req.user = { id: 1 };
    next();
  } else {
    res.status(403).send('Invalid token');
  }
}

app.get('/protected', authenticateToken, (req, res) => {
  res.send(`Hello user ${req.user.id}`);
});

Error Handling Middleware

app.get('/data', (req, res, next) => {
  try {
    throw new Error('Something went wrong');
  } catch (error) {
    next(error); // Pass to error handler
  }
});

// Error handling middleware (must have 4 parameters)
app.use((err, req, res, next) => {
  console.error(err.message);
  res.status(500).send('Server error');
});

Request Timing Middleware

app.use((req, res, next) => {
  const start = Date.now();

  res.on('finish', () => {
    const duration = Date.now() - start;
    console.log(`\({req.method} \){req.url} - ${duration}ms`);
  });

  next();
});

Middleware with Parameters

Middleware factories return middleware functions:

function logMessages(format) {
  return (req, res, next) => {
    if (format === 'simple') {
      console.log(`\({req.method} \){req.url}`);
    } else if (format === 'detailed') {
      console.log(`\({req.method} \){req.url} - ${req.headers['user-agent']}`);
    }
    next();
  };
}

app.use(logMessages('simple'));
// or
app.use(logMessages('detailed'));

Complete Example with Multiple Middleware

import express from 'express';

const app = express();

// Built-in middleware
app.use(express.json());

// Custom logging middleware
app.use((req, res, next) => {
  console.log(`[\({new Date().toISOString()}] \){req.method} ${req.url}`);
  next();
});

// Authentication middleware
function authenticate(req, res, next) {
  const token = req.query.token;
  if (token === 'secret') {
    req.user = { id: 1, name: 'John' };
    next();
  } else {
    res.status(401).send('Unauthorized');
  }
}

// Request validation middleware
function validateRequest(req, res, next) {
  if (!req.body.email) {
    return res.status(400).send('Email required');
  }
  next();
}

// Public route
app.get('/home', (req, res) => {
  res.send('Welcome');
});

// Protected route
app.get('/profile', authenticate, (req, res) => {
  res.send(`Hello ${req.user.name}`);
});

// Route with validation
app.post('/register', validateRequest, (req, res) => {
  res.send(`Registered ${req.body.email}`);
});

// Error handling middleware (must be last)
app.use((err, req, res, next) => {
  console.error(err);
  res.status(500).json({ error: 'Server error' });
});

app.listen(3000, () => {
  console.log('Server running');
});

Common Mistakes

Mistake 1: Forgetting to call next()

// Wrong - middleware stops here
app.use((req, res, next) => {
  console.log('Middleware');
  // No next() call - route never executes
});

app.get('/', (req, res) => {
  res.send('Hello'); // Never reached
});

// Right
app.use((req, res, next) => {
  console.log('Middleware');
  next(); // Passes to next handler
});

Mistake 2: Wrong middleware order

// Wrong - middleware after route can't help
app.get('/', (req, res) => {
  res.send(req.body); // undefined - JSON not parsed yet
});

app.use(express.json()); // Too late!

// Right - middleware before routes
app.use(express.json());
app.get('/', (req, res) => {
  res.send(req.body); // Properly parsed
});

Mistake 3: Error handler must have 4 parameters

// Wrong - Express won't recognize as error handler
app.use((err, req, res) => {
  res.send('Error');
});

// Right - all 4 parameters required
app.use((err, req, res, next) => {
  res.send('Error');
});

Key Takeaways

• Middleware intercepts requests and can modify them or stop them

• Middleware runs in the order it's defined

• Call next() to pass to the next middleware

• Express provides built-in middleware like express.json()

• You can create custom middleware for any task

• Application-level middleware runs for all/specific routes

• Error handlers are middleware with 4 parameters

• Order matters: define middleware before routes that need it

Middleware is the backbone of Express applications. Master it, and you can build clean, modular, and powerful web applications.

What is Express?

Express is a lightweight web framework for Node.js. It makes building web applications easier by providing helpful features for routing, middleware, and responses.

Without Express, here's a basic Node.js server:

import http from 'http';

const server = http.createServer((req, res) => {
  if (req.url === '/' && req.method === 'GET') {
    res.statusCode = 200;
    res.setHeader('Content-Type', 'text/plain');
    res.end('Home page');
  } else if (req.url === '/about' && req.method === 'GET') {
    res.statusCode = 200;
    res.setHeader('Content-Type', 'text/plain');
    res.end('About page');
  } else {
    res.statusCode = 404;
    res.end('Not found');
  }
});

server.listen(3000);

This gets messy quickly. With multiple routes, you'd have many if-else statements.

With Express, the same thing is much simpler:

import express from 'express';

const app = express();

app.get('/', (req, res) => {
  res.send('Home page');
});

app.get('/about', (req, res) => {
  res.send('About page');
});

app.listen(3000);

Much cleaner. Express handles the complexity.

Setting Up Express

First, create a project and install Express:

npm init -y
npm install express

Create a file called server.js:

import express from 'express';

const app = express();

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

Run it:

node server.js

You have a running server. It doesn't do anything yet, but it's listening on port 3000.

Understanding Routes

A route is a combination of:

• HTTP method (GET, POST, PUT, DELETE, etc.)

• URL path (/home, /users, /posts/123, etc.)

• Handler function (what to do when this route is called)

The basic structure is:

app.METHOD(PATH, HANDLER);

For example:

app.get('/home', (req, res) => {
  res.send('This is the home page');
});

This means: "When someone sends a GET request to /home, execute this function."

GET Requests

GET requests fetch data. They're read-only and don't change anything.

import express from 'express';

const app = express();

app.get('/', (req, res) => {
  res.send('Welcome to the home page');
});

app.get('/about', (req, res) => {
  res.send('This is the about page');
});

app.get('/contact', (req, res) => {
  res.send('Contact us at info@example.com');
});

app.listen(3000, () => {
  console.log('Server running');
});

Now visit:

• http://localhost:3000/ → "Welcome to the home page"

• http://localhost:3000/about → "This is the about page"

• http://localhost:3000/contact → "Contact us at..."

POST Requests

POST requests send data to the server. They typically create new resources.

For this, you need to parse incoming data. Express provides middleware for this:

import express from 'express';

const app = express();

// Parse JSON data
app.use(express.json());

app.get('/', (req, res) => {
  res.send('GET request received');
});

app.post('/submit', (req, res) => {
  const { name, email } = req.body;
  res.send(`Thank you, \({name}. We'll email \){email}`);
});

app.listen(3000, () => {
  console.log('Server running');
});

When someone sends a POST request to /submit with JSON data, Express parses it and stores it in req.body.

To test this, you'd need a tool like Postman or curl:

curl -X POST http://localhost:3000/submit \
  -H "Content-Type: application/json" \
  -d '{"name":"John","email":"john@example.com"}'

Response: "Thank you, John. We'll email john@example.com"

URL Parameters

Routes can have dynamic parts. Parameters start with a colon:

import express from 'express';

const app = express();

app.get('/users/:id', (req, res) => {
  const userId = req.params.id;
  res.send(`Getting user ${userId}`);
});

app.get('/posts/:postId/comments/:commentId', (req, res) => {
  const { postId, commentId } = req.params;
  res.send(`Comment \({commentId} on post \){postId}`);
});

app.listen(3000);

Examples:

• GET /users/123 → "Getting user 123"

• GET /posts/456/comments/789 → "Comment 789 on post 456"

Query Parameters

Query parameters come after a question mark and are optional:

import express from 'express';

const app = express();

app.get('/search', (req, res) => {
  const query = req.query.q;
  const limit = req.query.limit;
  res.send(`Searching for "\({query}", limit \){limit}`);
});

app.listen(3000);

Examples:

• GET /search?q=javascript → "Searching for 'javascript', limit undefined"

• GET /search?q=node&limit=10 → "Searching for 'node', limit 10"

Response Methods

Express provides several ways to send responses:

import express from 'express';

const app = express();

// Send plain text
app.get('/text', (req, res) => {
  res.send('This is plain text');
});

// Send JSON
app.get('/json', (req, res) => {
  res.json({ message: 'This is JSON', status: 'success' });
});

// Send HTML
app.get('/html', (req, res) => {
  res.send('<h1>This is HTML</h1>');
});

// Send with status code
app.get('/error', (req, res) => {
  res.status(404).send('Not found');
});

// Redirect
app.get('/old-path', (req, res) => {
  res.redirect('/new-path');
});

app.listen(3000);

Handling All HTTP Methods

Express supports all standard HTTP methods:

import express from 'express';

const app = express();

app.use(express.json());

app.get('/users', (req, res) => {
  res.json({ message: 'Get all users' });
});

app.post('/users', (req, res) => {
  res.json({ message: 'Create new user' });
});

app.put('/users/:id', (req, res) => {
  res.json({ message: `Update user ${req.params.id}` });
});

app.delete('/users/:id', (req, res) => {
  res.json({ message: `Delete user ${req.params.id}` });
});

app.listen(3000);

Handling 404 Errors

When a route doesn't exist, Express returns a 404 error by default. You can customize this:

import express from 'express';

const app = express();

app.get('/', (req, res) => {
  res.send('Home');
});

// Catch all unmatched routes
app.use((req, res) => {
  res.status(404).send('Page not found');
});

app.listen(3000);

The order matters. This "catch-all" route must be last, otherwise it will intercept all requests.

A Complete Example

Let's build a simple blog API:

import express from 'express';

const app = express();
app.use(express.json());

// Sample data
let posts = [
  { id: 1, title: 'First Post', content: 'Hello world' },
  { id: 2, title: 'Second Post', content: 'Another post' }
];

// GET all posts
app.get('/posts', (req, res) => {
  res.json(posts);
});

// GET single post
app.get('/posts/:id', (req, res) => {
  const post = posts.find(p => p.id === parseInt(req.params.id));
  if (!post) {
    return res.status(404).send('Post not found');
  }
  res.json(post);
});

// CREATE new post
app.post('/posts', (req, res) => {
  const newPost = {
    id: posts.length + 1,
    title: req.body.title,
    content: req.body.content
  };
  posts.push(newPost);
  res.status(201).json(newPost);
});

// UPDATE post
app.put('/posts/:id', (req, res) => {
  const post = posts.find(p => p.id === parseInt(req.params.id));
  if (!post) {
    return res.status(404).send('Post not found');
  }
  post.title = req.body.title || post.title;
  post.content = req.body.content || post.content;
  res.json(post);
});

// DELETE post
app.delete('/posts/:id', (req, res) => {
  const index = posts.findIndex(p => p.id === parseInt(req.params.id));
  if (index === -1) {
    return res.status(404).send('Post not found');
  }
  const deleted = posts.splice(index, 1);
  res.json(deleted);
});

app.listen(3000, () => {
  console.log('Blog API running on port 3000');
});

This simple API lets you create, read, update, and delete posts.

Common Mistakes

Mistake 1: Forgetting middleware

// Wrong - won't parse JSON
app.post('/data', (req, res) => {
  console.log(req.body); // undefined
});

// Correct
app.use(express.json());
app.post('/data', (req, res) => {
  console.log(req.body); // has data
});

Mistake 2: Forgetting to return after sending response

app.get('/users/:id', (req, res) => {
  if (!id) {
    res.status(400).send('Invalid ID');
    // BUG: continues executing below
  }
  res.send('User data');
});

// Better
app.get('/users/:id', (req, res) => {
  if (!id) {
    return res.status(400).send('Invalid ID');
  }
  res.send('User data');
});

Key Takeaways

• Express simplifies building web servers with Node.js

• Routes combine HTTP method, path, and handler function

• GET requests fetch data, POST requests send data

• URL parameters (:id) capture dynamic values

• Query parameters (?key=value) pass optional filters

• Middleware processes requests before they reach handlers

• Always return after sending a response

• Use appropriate HTTP status codes

Express makes building web applications enjoyable. These fundamentals are the foundation for all Express applications.

What Makes Node.js Fast?

There are two reasons Node.js excels at web applications: non-blocking I/O and an event-driven architecture.

Non-blocking I/O means your application doesn't freeze while waiting for databases or file systems. Operations like database queries are delegated, and your code continues.

Event-driven means your application responds to events. A database completes? Event. A file loads? Event. Request arrives? Event. Your code reacts to these events.

Together, these features make Node.js incredibly efficient.

The Blocking Problem

Traditional servers block while waiting for operations:

// Blocking server (pseudo-code, not Node.js)
request1 arrives
  database query takes 2 seconds
  (server frozen, can't handle other requests)
response sent to request1

request2 can now be handled
  database query takes 2 seconds
  (server frozen)
response sent to request2

With 100 requests each waiting 2 seconds, the total time is 200 seconds. Users wait a long time.

Node.js: Non-Blocking

Node.js handles the same scenario differently:

request1 arrives
  database query delegated
  (server free immediately)

request2 arrives
  database query delegated
  (server free immediately)

database completes for request1
  response sent

database completes for request2
  response sent

Total time is 2 seconds. Users get responses quickly.

Event Loop: The Heart of Node.js Performance

The event loop is what makes this possible. It continuously checks for completed operations and executes their callbacks:

Main Thread (JavaScript)
     |
Callbacks Queue <- Operations complete (databases, files, timers)
     |
Event Loop (running continuously)
  1. Is there a callback ready?
  2. Execute it
  3. Go back to step 1

Here's a concrete example:

import http from 'http';
import { readFile } from 'fs';

http.createServer((req, res) => {
  // Delegate file read
  readFile('data.txt', (err, data) => {
    res.end(data);
  });
  // Main thread immediately available for next request
}).listen(3000);

When the file is read, the callback executes and sends the response. The main thread isn't blocked.

Comparison: Blocking vs Non-Blocking

Imagine two servers, one blocking, one non-blocking, handling three requests that each take 1 second:

Blocking Server:

Time 0: Request 1 arrives, processing starts
Time 1: Request 1 done, Response 1 sent
Time 1: Request 2 arrives, processing starts
Time 2: Request 2 done, Response 2 sent
Time 2: Request 3 arrives, processing starts
Time 3: Request 3 done, Response 3 sent

Total time: 3 seconds

Non-Blocking (Node.js):

Time 0: Request 1 arrives, work delegated
Time 0: Request 2 arrives, work delegated
Time 0: Request 3 arrives, work delegated
Time 1: All three operations complete, responses sent

Total time: 1 second

Node.js is 3x faster for concurrent requests.

Where Node.js Shines

Database Queries:

// While database is querying, Node.js handles other requests
db.query('SELECT * FROM users', (err, results) => {
  res.json(results);
});

File Operations:

// While file is being read, handle other requests
fs.readFile('large-file.txt', (err, data) => {
  res.send(data);
});

API Calls:

// While waiting for external API, handle other requests
fetch('https://api.example.com/data')
  .then(res => res.json())
  .then(data => sendResponse(data));

Most web applications spend most time waiting for these operations. Node.js excels because it doesn't block during waits.

Real-World Performance: Restaurant Analogy

Think of a web server as a restaurant:

Blocking server: The only waiter must take an order, go to the kitchen, wait for the food to cook, serve it, before taking another order. Customer 2 waits while Customer 1's food cooks.

Node.js server: The waiter takes orders from multiple customers, gives them all to the kitchen, and serves them as they're ready. While the kitchen cooks, the waiter takes more orders.

The kitchen is background workers (databases, file systems). The waiter is the Node.js thread.

Scalability Without Massive Infrastructure

Because Node.js doesn't create a thread per request, it uses minimal resources:

• A traditional server with 10,000 concurrent users might need 10,000 threads

• Node.js handles 10,000 concurrent connections with one thread plus a thread pool

Memory usage is drastically lower. You don't need an expensive server farm.

When Node.js Isn't the Best Choice

Node.js is not ideal for CPU-intensive tasks:

// Bad for Node.js - heavy computation blocks the thread
app.get('/calculate', (req, res) => {
  let result = 0;
  for (let i = 0; i < 1_000_000_000; i++) {
    result += i;
  }
  res.send(result);
});

While calculating, the thread is blocked, and other requests wait.

For CPU-intensive tasks, use worker threads or other languages.

But for typical web applications where time is spent on I/O, Node.js is exceptional.

Real-World Usage: Who Uses Node.js?

Netflix: Chose Node.js for its ability to handle millions of concurrent users streaming video.

Uber: Real-time ride matching requires handling many concurrent connections. Node.js handles this perfectly.

LinkedIn: Uses Node.js for features requiring real-time updates.

Airbnb: Uses Node.js in its infrastructure for handling search and booking requests.

These companies didn't choose Node.js randomly. They chose it because it performs well at scale.

Performance Metrics

Here's what typical Node.js performance looks like:

• Throughput: Handles thousands of requests per second on modest hardware

• Latency: Response times measured in milliseconds

• Memory: Lower memory footprint than traditional threaded servers

• Scalability: Scales horizontally by running multiple Node.js processes

Optimization Tips

Even with Node.js, good practices matter:

Use async/await:

// Good - non-blocking
app.get('/data', async (req, res) => {
  const data = await db.query('SELECT * FROM users');
  res.json(data);
});

Avoid synchronous operations:

// Bad - blocks thread
const data = fs.readFileSync('large-file.txt');

// Good - non-blocking
fs.readFile('large-file.txt', (err, data) => {
  // Handle data
});

Use caching:

// Cache database results to avoid repeated queries
const cache = {};
app.get('/users', (req, res) => {
  if (cache.users) {
    return res.json(cache.users);
  }
  db.query('SELECT * FROM users', (err, results) => {
    cache.users = results;
    res.json(results);
  });
});

Load balancing: Run multiple Node.js processes across multiple CPU cores:

import cluster from 'cluster';
import os from 'os';
import app from './app.js';

if (cluster.isPrimary) {
  const numCPUs = os.cpus().length;
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }
} else {
  app.listen(3000);
}

Key Takeaways

• Node.js is fast because it's non-blocking and event-driven

• While waiting for I/O, Node.js handles other requests

• The event loop continuously checks for completed operations

• Node.js handles thousands of concurrent connections efficiently

• Traditional servers would need thousands of threads; Node.js uses one

• Node.js excels for I/O-heavy applications (databases, files, APIs)

• Node.js is not ideal for CPU-intensive tasks

• Major companies like Netflix and Uber use Node.js at massive scale

Node.js isn't fast just because it's JavaScript. It's fast because of its fundamentally different approach to concurrency. Understand non-blocking I/O and the event loop, and you understand why Node.js is perfect for modern web applications.

Linux follows a brilliant philosophical rule: "Everything is a file." Your hard drive is a file. Your keyboard translates to a file. The running processes taking up your RAM are represented as files. Network sockets are treated as files. This sounds like an abstract academic concept until you start exploring the directories and see how it works in practice.

By exploring the system directories, I stopped viewing Linux as a black box of random commands. Instead, I started seeing it as a beautifully organized machine where every configuration, process, and hardware component has a specific address. Here are nine fascinating discoveries from digging deep into the Linux filesystem.

1. The Phantom Folder: /proc

Normally, we think of files as data saved permanently on a physical hard drive spinning in your computer. But when you navigate to /proc and check its size, you will notice something strange. It takes up exactly zero bytes on your disk.

What it does: The /proc directory is a virtual filesystem. It does not exist on your hard drive at all. It is generated continuously in your computer's RAM by the Linux kernel.

Why it exists: Operating systems need a way for users and monitoring tools to check system health, memory usage, and CPU details. Instead of writing complex API tools to fetch this data, Linux just exposes it as text files.

The problem it solves: It bridges the gap between kernel memory and user space. Without /proc, you would need special low-level programming skills just to check your RAM usage.

The insight: If you type cat /proc/cpuinfo, you are not reading a saved document. You are actively querying the kernel for your processor's live hardware specs. Every running program on your computer gets its own numbered folder inside /proc. Those folders hold text files that describe the exact memory usage and execution state of that specific application.

2. The Password Decoupling: /etc/passwd vs /etc/shadow

User management feels like it should require a complex, encrypted database engine running in the background. In Linux, user management is handled entirely by a couple of plain text files.

What it does: The /etc/passwd file lists every user and system account on the machine. The /etc/shadow file stores the actual hashed passwords.

Why it exists: Applications need to know which users exist on a system to assign file permissions and ownership. They need a fast, simple way to look up user IDs.

The problem it solves: Originally, early Unix systems stored hashed passwords directly inside /etc/passwd. The problem was that many basic programs need to read /etc/passwd to map user IDs to actual usernames. Since the file had to be readable by everyone, attackers could simply copy the text file and run brute-force password cracking tools on the hashes.

The insight: To fix this massive security flaw without breaking existing software, engineers split the system in two. They left the usernames in the world-readable /etc/passwd file. Then they moved the password hashes into /etc/shadow. Only the root administrator has permission to read the shadow file. This simple structural split secured the entire operating system while maintaining backward compatibility.

3. The Internet Translators: /etc/resolv.conf and /etc/hosts

When you type a website name into your browser, your computer has no idea where that server actually lives. It needs to ask a Domain Name System (DNS) server for the specific IP address.

What it does: The /etc/resolv.conf file is a text document that tells your computer exactly which DNS servers to ask for directions. Meanwhile, /etc/hosts provides manual, local overrides.

Why it exists: Network settings change frequently depending on your location. By keeping the DNS configuration in predictably located text files, networking scripts and VPN clients can quickly update your routing preferences.

The problem it solves: It standardizes how network name resolution is configured across almost all Unix-like systems. Before the system reaches out to the open internet, it checks /etc/hosts to see if you have hardcoded a specific IP address for a domain.

The insight: Your machine's ability to browse the internet relies entirely on /etc/resolv.conf. If you delete it or put the wrong IP address inside, your computer will stay connected to the Wi-Fi network but will completely lose the ability to load web pages by their domain names. Furthermore, web developers often edit /etc/hosts to point legitimate domains to their local testing servers during development.

4. The Digital Black Hole: /dev/null

If you look inside the /dev directory, you will find files representing your mouse, your hard drives, and your camera. But you will also find a device file that goes nowhere.

What it does: The /dev/null file is a special device file that instantly discards any data written to it.

Why it exists: Data constantly moves through a Linux system. Sometimes you only care if a program ran successfully, and you do not care about the diagnostic text it spits out.

The problem it solves: When you run automated tasks or background scripts, they often generate massive amounts of terminal output or warning messages. If you do not want to see these messages and do not want them taking up space in a log file, you need a safe way to throw them away.

The insight: Because "everything is a file" in Linux, engineers created a file that acts as a trash can. When developers append > /dev/null to a backup script command, they are redirecting the noisy output into this endless black hole. It accepts infinite data and never gets full.

5. The Blueprint of the Hard Drives: /etc/fstab

Booting up a computer is a fragile process. The system needs to know exactly which hard drives to connect and where to put them in the filesystem hierarchy.

What it does: The File System Table, located at /etc/fstab, is the master map for your storage drives. It tells the Linux kernel exactly which partitions to mount and what rules to apply to them during startup.

Why it exists: Linux allows you to mount a secondary hard drive into any empty folder you want. You could mount a massive storage drive directly to /var/www/html to store web server files.

The problem it solves: The system needs a persistent record of these random hardware locations so it can rebuild the folder structure exactly the same way every time you restart.

The insight: This file is incredibly powerful but equally dangerous. A simple typo in /etc/fstab can completely break the boot sequence. If the system cannot read the instruction manual for the hard drives, it drops your server into a locked-down recovery mode because it physically cannot piece together the filesystem.

6. The Bouncer's Notepad: /var/log/auth.log

Servers attached to the internet are constantly under attack. Bots scan the web trying to guess passwords and force their way into remote machines.

What it does: The /var/log/auth.log file (which is sometimes called secure on certain distributions) acts as a relentless journal tracking every single authentication attempt on the system.

Why it exists: You cannot improve security if you do not know you are being attacked. System logs provide visibility into exactly who is trying to access the machine.

The problem it solves: Administrators need a way to audit security. If someone is trying to guess passwords or if an employee successfully logs in, the system requires an unalterable history of that event for forensic analysis.

The insight: Reading this file on a live public server is eye-opening. You will see hundreds of automated attempts from random IP addresses trying to log in as "root" or "admin". Watching the authentication log populate in real time proves exactly why strong passwords and SSH keys are mandatory for remote servers.

7. The Puppet Master of Services: /etc/systemd

Applications like web servers and databases need to continually run in the background. They also need to automatically start back up if the server reboots.

What it does: The /etc/systemd directory stores the configuration files that dictate how background services start, stop, and behave.

Why it exists: A server might run fifty different background applications simultaneously. The operating system needs a standardized way to manage dependencies, like making sure the networking service starts before the web server tries to connect to the internet.

The problem it solves: Before systemd, starting services required messy, non-standard bash scripts. Systemd introduced a clean, uniform configuration format (called unit files) that makes service management predictable.

The insight: By reading a service file inside /etc/systemd/system, you can see exactly how an application launches. You can see which user account it runs under and what environment variables it requires. This directory is the central nervous system for keeping your server applications running smoothly.

8. The Amnesiac Folders: /tmp and /var/tmp

Programs constantly need to create temporary files. A video editor needs a place to store cached clips, and a web server needs a place to hold uploaded images before moving them to permanent storage.

What it does: The /tmp directory is a global scratchpad available to any application or user. The /var/tmp directory serves a similar purpose but with a crucial difference in persistence.

Why it exists: If applications threw temporary files all over your home directory, your disk would fill up with garbage in a week. Having dedicated temporary folders keeps the rest of the filesystem clean.

The problem it solves: It provides a safe sandbox where applications write temporary data without worrying about cleaning it up perfectly.

The insight: The Linux system usually wipes the entire /tmp directory clean every time you reboot the computer. It is a completely volatile storage area. However, files stored in /var/tmp are designed to survive a reboot. Understanding this difference is critical when writing backend scripts that process temporary data.

9. The Infinity Generator: /dev/urandom

Cryptographic security relies on random numbers. When your server generates an SSH key or an SSL certificate, it needs a source of pure unpredictability.

What it does: The /dev/urandom file is a special device file that outputs an endless stream of random characters.

Why it exists: Computers are deterministic machines. They follow instructions exactly. Because of this, generating actual randomness is incredibly difficult for a CPU.

The problem it solves: Linux gathers "environmental noise" from device drivers, keyboard timings, and mouse movements to generate a pool of randomness. It then exposes this randomness through /dev/urandom so any application can securely generate encryption keys.

The insight: You can actually read this file directly by running cat /dev/urandom, which will flood your terminal screen with gibberish. It is amazing to realize that complex cryptographic applications rely on reading a simple stream of characters from this exact device file.

Final Thoughts

The Linux filesystem is essentially the system's brain exposed as readable text. When you run a command, it is usually just a fancy wrapper that reads from or writes to one of these hidden configuration files.

By understanding where the configurations live and how the virtual filesystems operate, you stop being someone who just memorizes commands. You start becoming a developer who understands how the machine actually breathes at a core architectural level.

Why Node.js Needs Asynchronous Code

Node.js runs on a single thread. If you tried to handle everything synchronously, your entire server would block while waiting for slow operations like reading files, querying databases, or making HTTP requests.

Think of it like a restaurant. If the waiter takes an order and then stands still waiting for the chef to finish cooking before serving another customer, he wastes time. But if the waiter takes an order, moves to the next customer, and comes back when the food is ready, he serves everyone efficiently.

Node.js works the same way. Asynchronous code lets your server accept multiple requests without blocking.

Callbacks: The Original Async Solution

A callback is a function you pass to another function. It gets executed when an operation finishes.

Here's a simple example of reading a file with a callback:

import fs from 'fs';

fs.readFile('data.txt', 'utf8', (error, data) => {
  if (error) {
    console.log('Error reading file:', error);
  } else {
    console.log('File contents:', data);
  }
});

console.log('Reading file...');

When readFile starts, it doesn't wait. Instead, it sets up the callback and moves on to the next line. Once the file loads, the callback executes with either the error or the data.

The output shows this clearly:

Reading file...
File contents: [content of data.txt]

Notice that "Reading file..." prints first, even though it comes after readFile in the code. That's asynchronous execution.

The Problem: Callback Hell

Callbacks work fine for a single operation. But what if you need to do multiple things in sequence? You need to read one file, then use its contents to read another file, then process that data.

import fs from 'fs';

fs.readFile('users.txt', 'utf8', (error1, users) => {
  if (error1) {
    console.log('Error:', error1);
  } else {
    fs.readFile('posts.txt', 'utf8', (error2, posts) => {
      if (error2) {
        console.log('Error:', error2);
      } else {
        fs.readFile('comments.txt', 'utf8', (error3, comments) => {
          if (error3) {
            console.log('Error:', error3);
          } else {
            console.log('All files loaded:', users, posts, comments);
          }
        });
      }
    });
  }
});

This deeply nested structure is called "callback hell" or the "pyramid of doom." It's hard to read, error-prone, and difficult to maintain. Imagine if you needed five or ten operations. The code would become unreadable.

Promises: A Better Way

Promises were introduced to solve callback hell. A promise is an object that represents a value that might be available now, later, or never.

A promise has three states:

1. Pending: The operation hasn't finished yet.

2. Fulfilled: The operation completed successfully.

3. Rejected: The operation failed.

Here's how you create a promise:

const promise = new Promise((resolve, reject) => {
  // Do something async
  if (success) {
    resolve(value); // fulfilled
  } else {
    reject(error); // rejected
  }
});

The callback receives two functions: resolve and reject. You call resolve when the operation succeeds and reject when it fails.

Using Promises with .then()

Once you have a promise, you can attach handlers using .then():

import fs from 'fs/promises';

fs.readFile('data.txt', 'utf8')
  .then(data => {
    console.log('File contents:', data);
  })
  .catch(error => {
    console.log('Error:', error);
  });

The .then() method runs when the promise is fulfilled, and .catch() runs if it's rejected.

Chaining Promises

The real power of promises comes from chaining them. Each .then() returns a new promise, so you can chain multiple operations:

import fs from 'fs/promises';

fs.readFile('users.txt', 'utf8')
  .then(users => {
    console.log('Users loaded');
    return fs.readFile('posts.txt', 'utf8');
  })
  .then(posts => {
    console.log('Posts loaded');
    return fs.readFile('comments.txt', 'utf8');
  })
  .then(comments => {
    console.log('Comments loaded');
    console.log('All files loaded successfully');
  })
  .catch(error => {
    console.log('Error:', error);
  });

This is much cleaner than nested callbacks. Each step is at the same indentation level, making it easy to follow the flow.

Promise Lifecycle Visualization

Here's how a promise moves through its states:

Promise Created (Pending)
         |
    -----+-----
   |          |
Resolved    Rejected
(Fulfilled)  (Error)
   |          |
.then()     .catch()

Once a promise is settled (either fulfilled or rejected), it doesn't change. You can attach multiple .then() handlers, and they all receive the same result.

Error Handling with Promises

Promises make error handling cleaner. A single .catch() handles errors from any step in the chain:

import fs from 'fs/promises';

fs.readFile('file1.txt', 'utf8')
  .then(data1 => fs.readFile('file2.txt', 'utf8'))
  .then(data2 => fs.readFile('file3.txt', 'utf8'))
  .then(data3 => console.log('All files loaded'))
  .catch(error => console.log('Error in any step:', error));

If any .then() throws an error or rejects, the .catch() will handle it. You don't need to check for errors at each step.

Common Mistakes

Mistake 1: Forgetting to return promises in chains

// Wrong
fs.readFile('file1.txt', 'utf8')
  .then(data1 => {
    fs.readFile('file2.txt', 'utf8'); // Missing return
  })
  .then(data2 => {
    // data2 will be undefined
  });

// Correct
fs.readFile('file1.txt', 'utf8')
  .then(data1 => {
    return fs.readFile('file2.txt', 'utf8');
  })
  .then(data2 => {
    // data2 has the file contents
  });

Mistake 2: Not catching rejected promises

// Can leave unhandled rejections
fs.readFile('nonexistent.txt', 'utf8')
  .then(data => console.log(data));

// Better
fs.readFile('nonexistent.txt', 'utf8')
  .then(data => console.log(data))
  .catch(error => console.log(error));

Key Takeaways

• Node.js is single-threaded, so asynchronous code is essential to avoid blocking.

• Callbacks were the original async solution but lead to callback hell with nested operations.

• Promises provide a cleaner way to handle async operations with .then() and .catch().

• Promise chains let you handle multiple sequential operations readably.

• A single .catch() handles errors from any step in the chain.

Understanding callbacks and promises is fundamental to working with Node.js. Once you're comfortable with these, async/await (which we'll cover separately) makes async code look almost like synchronous code while keeping the benefits of non-blocking execution.

What Is Blocking Code?

Blocking code stops execution until an operation completes.

const fs = require('fs');

console.log('Starting');
const data = fs.readFileSync('file.txt'); // Waits here
console.log('File read');
console.log(data);

While readFileSync reads the file, nothing else happens. Your code is frozen. If this is a server handling requests, every other request waits.

Execution timeline:

0ms: Start
0ms: Call readFileSync
100ms: File read, execution continues
100ms: Log file content

The server is blocked for 100ms. If you have 100 simultaneous requests, they queue up for 100ms each. Total wait time: 10,000ms (10 seconds).

What Is Non-Blocking Code?

Non-blocking code delegates work and continues immediately:

import fs from 'fs';

console.log('Starting');
fs.readFile('file.txt', (err, data) => {
  console.log('File read');
  console.log(data);
});
console.log('Continuing');

Output:

Starting
Continuing
File read
[file content]

The file read happens in the background. Your code continues immediately.

Execution timeline:

0ms: Start
0ms: Delegate file read
0ms: Log "Continuing"
100ms: File read completes, callback executes

The server never blocks. It can handle other requests while waiting.

Real-World Impact

Let's simulate a server handling three requests, each requiring a 1-second file read:

Blocking Code:

app.get('/data', (req, res) => {
  const data = fs.readFileSync('file.txt'); // Blocks for 1 second
  res.send(data);
});

Timeline:

0s: Request 1 arrives, starts reading
1s: Request 1 done, Response 1 sent
1s: Request 2 arrives (was waiting), starts reading
2s: Request 2 done, Response 2 sent
2s: Request 3 arrives (was waiting), starts reading
3s: Request 3 done, Response 3 sent

Total time for all users: 3 seconds. Avg user wait: 2 seconds.

Non-Blocking Code:

app.get('/data', (req, res) => {
  fs.readFile('file.txt', (err, data) => {
    res.send(data);
  });
});

Timeline:

0s: Request 1 arrives, delegates read, returns immediately
0s: Request 2 arrives, delegates read, returns immediately
0s: Request 3 arrives, delegates read, returns immediately
1s: All reads complete, all responses sent

Total time for all users: 1 second. Avg user wait: ~1 second.

Non-blocking is 3x faster with just 3 requests. With 100 requests, the difference is massive.

Blocking Operations in Node.js

Common operations that have synchronous (blocking) versions:

import fs from 'fs';

// Blocking
fs.readFileSync('file.txt');
fs.writeFileSync('file.txt', 'data');

// Non-blocking alternatives
fs.readFile('file.txt', (err, data) => {});
fs.writeFile('file.txt', 'data', (err) => {});

Database operations:

// Blocking (bad)
const result = db.querySync('SELECT * FROM users');

// Non-blocking (good)
db.query('SELECT * FROM users', (err, result) => {});

HTTP requests:

// Blocking (bad - if such a function existed)
const response = http.getSync('https://api.example.com/data');

// Non-blocking (good)
fetch('https://api.example.com/data')
  .then(res => res.json())
  .then(data => console.log(data));

Why Does Blocking Happen?

Some operations in Node.js are inherently slow:

• Reading from disk (slower than RAM)

• Network requests (very slow)

• Database queries (slow)

• Complex calculations (time-consuming)

Node.js can't speed these up. But it can handle them without blocking the thread by delegating to background workers.

The Event Loop Revisited

Understanding the event loop explains the difference:

import fs from 'fs';

console.log('1');
fs.readFile('file.txt', () => {
  console.log('2');
});
console.log('3');

Output:

1
3
2

Here's what happens:

1. JavaScript starts
   - Logs "1"
   - Delegates file read (tells worker thread)
   - Logs "3"
   - No more code

2. Event loop checks: Is anything ready?
   - File read not done yet, nothing to do

3. Event loop checks: Is anything ready?
   - File is ready! Execute callback
   - Logs "2"

The callback waits in a queue until the main thread is free.

Async/Await: Cleaner Syntax

While callbacks are non-blocking, async/await is cleaner:

import fs from 'fs/promises';

// Using callbacks (non-blocking)
fs.readFile('file.txt', (err, data) => {
  console.log(data);
});

// Using async/await (still non-blocking!)
const data = await fs.readFile('file.txt');
console.log(data);

Async/await looks like synchronous code but it's non-blocking. When you await a slow operation, the function pauses, but the thread continues handling other requests.

Practical Examples

Bad: Synchronous (blocking)

import express from 'express';
import fs from 'fs';

const app = express();

app.get('/read-file', (req, res) => {
  const data = fs.readFileSync('large-file.txt'); // Blocks entire server
  res.send(data);
});

app.listen(3000);

Good: Asynchronous (non-blocking)

import express from 'express';
import fs from 'fs/promises';

const app = express();

app.get('/read-file', async (req, res) => {
  try {
    const data = await fs.readFile('large-file.txt');
    res.send(data);
  } catch (error) {
    res.status(500).send('Error reading file');
  }
});

app.listen(3000);

Bad: Database operations (blocking)

app.get('/users', (req, res) => {
  const users = db.querySync('SELECT * FROM users'); // Blocks server
  res.json(users);
});

Good: Database operations (non-blocking)

app.get('/users', async (req, res) => {
  const users = await db.query('SELECT * FROM users');
  res.json(users);
});

Mixing Blocking and Non-Blocking

If even one route is blocking, it can impact others:

import express from 'express';
import fs from 'fs';
import fs_async from 'fs/promises';

const app = express();

// This route blocks the entire server
app.get('/slow', (req, res) => {
  const data = fs.readFileSync('huge-file.txt'); // BLOCKS
  res.send(data);
});

// This route is fast but blocked by /slow
app.get('/fast', (req, res) => {
  res.send('Fast response');
});

// If someone calls /slow, requests to /fast must wait!

One blocking operation can bring down your entire server.

CPU-Intensive Code

Even pure JavaScript computations can block:

// Blocks the thread for 5 seconds
function expensiveCalculation() {
  let result = 0;
  for (let i = 0; i < 1_000_000_000; i++) {
    result += Math.sqrt(i);
  }
  return result;
}

app.get('/calculate', (req, res) => {
  const result = expensiveCalculation(); // Blocks thread
  res.json({ result });
});

For CPU-intensive work, use worker threads:

import { Worker } from 'worker_threads';
import path from 'path';

app.get('/calculate', (req, res) => {
  const worker = new Worker('./worker.js');
  worker.on('message', (result) => {
    res.json({ result });
  });
});

Common Mistakes

Mistake 1: Using readFileSync in a server

// Wrong - blocks entire server
app.get('/data', (req, res) => {
  const data = fs.readFileSync('file.txt');
  res.send(data);
});

// Right - non-blocking
app.get('/data', async (req, res) => {
  const data = await fs.readFile('file.txt');
  res.send(data);
});

Mistake 2: Not awaiting async operations

// Wrong - doesn't wait for query
app.get('/users', async (req, res) => {
  const users = db.query('SELECT * FROM users');
  res.json(users); // users is undefined
});

// Right - waits for query
app.get('/users', async (req, res) => {
  const users = await db.query('SELECT * FROM users');
  res.json(users);
});

Mistake 3: Blocking in middleware

// Wrong - blocking middleware
app.use((req, res, next) => {
  const user = db.querySync('SELECT * FROM users WHERE id=1');
  req.user = user;
  next();
});

// Right - non-blocking middleware
app.use(async (req, res, next) => {
  req.user = await db.query('SELECT * FROM users WHERE id=1');
  next();
});

Key Takeaways

• Blocking code stops execution until operations complete

• Non-blocking code delegates work and continues immediately

• In a server, one blocking operation can block all other requests

• Node.js provides non-blocking alternatives to synchronous functions

• Use async/await for cleaner non-blocking code

• Avoid .Sync methods (readFileSync, etc.) in servers

• Even one blocking route can cripple server performance

• CPU-intensive tasks should use worker threads

Embracing non-blocking code is what separates Node.js code that barely works from code that scales massively. Master this concept, and you've mastered Node.js.

Single-Threaded: What It Means

Node.js runs your JavaScript code on a single thread. There's only one thread executing your code at any given moment.

Contrast this with languages like Java or Python, where you might create a new thread for each request. With Node.js, you can't do that. You get one thread, and that's it.

If you tried to handle requests synchronously and sequentially, your server would be painfully slow. The first request would block all others.

Concurrency vs Parallelism

This is critical to understand:

Parallelism means doing multiple things at the exact same time. You need multiple processors or cores.

Concurrency means managing multiple tasks without necessarily doing them at the same time. You interleave tasks.

Node.js achieves concurrency, not parallelism, through its single thread.

Think of a restaurant again. One waiter (single thread) can handle many customers (requests) concurrently by:

1. Taking customer A's order

2. Passing it to the kitchen (delegating work)

3. Taking customer B's order

4. Checking if customer A's food is ready

5. Serving customer A

6. Taking customer C's order

7. Checking if customer B's food is ready

8. Serving customer B

The waiter isn't cooking (just like Node.js doesn't perform database queries itself). The waiter is coordinating and serving, while the kitchen does the actual work.

The Event Loop and Worker Threads

When you perform slow operations like reading files or querying databases, Node.js doesn't have your thread wait. Instead, it delegates the work to background workers.

Here's what happens:

import fs from 'fs';

console.log('Starting');

fs.readFile('large-file.txt', 'utf8', (err, data) => {
  console.log('File read complete');
});

console.log('Continuing');

Execution flow:

1. "Starting" is logged

2. readFile is called, work is delegated to a background worker

3. "Continuing" is logged immediately (no wait!)

4. Background worker reads the file

5. Once complete, the callback is queued

6. Event loop picks up the callback and executes it

7. "File read complete" is logged

Output:

Starting
Continuing
File read complete

Your thread never blocks. It quickly delegates work and moves on to handle other things.

How Node.js Handles Multiple Requests

Here's a more realistic server example:

import express from 'express';
import fs from 'fs';

const app = express();

app.get('/read-file', (req, res) => {
  fs.readFile('data.txt', 'utf8', (err, data) => {
    if (err) {
      res.status(500).send('Error reading file');
    } else {
      res.send(data);
    }
  });
});

app.get('/db-query', (req, res) => {
  // Simulating a database query that takes 1 second
  setTimeout(() => {
    res.send('Query complete');
  }, 1000);
});

app.listen(3000, () => console.log('Server running'));

Imagine two requests arrive at almost the same time:

1. Request 1 comes in → Server starts reading a file → Work delegated to background thread

2. Request 2 comes in → Server performs a database query → Work delegated to background thread

3. Node.js thread is free and waiting for events

4. File read completes → Callback executed → Response sent to client 1

5. Database query completes → Callback executed → Response sent to client 2

Both operations happened concurrently, but your JavaScript code only ran on one thread. The thread quickly delegates work and moves on.

Event Loop Visualization

The event loop continuously checks if there's work to do:

Main Thread (JavaScript execution)
         |
    -----+-----
   |          |
Sync Code  Callbacks
   |          |
   |    Event Loop checks:
   |    1. Is there a completed operation?
   |    2. Execute its callback
   |    3. Go back to step 1

Here's a concrete example:

console.log('1: Start');

setTimeout(() => {
  console.log('2: Timer complete');
}, 100);

console.log('3: Still on main thread');

Output:

1: Start
3: Still on main thread
2: Timer complete

Even though the timer was set first, the synchronous code runs first. The callback waits until the main thread is free.

Why This Scales Well

This design is powerful because:

1. No thread overhead: Creating a thread for each request is expensive. Node.js uses a single thread plus a pool of background workers.

2. Efficient resource usage: A single thread uses far less memory than hundreds of threads.

3. Avoids context switching: The operating system doesn't have to switch between many threads.

4. Non-blocking by default: Slow operations don't block other requests.

A server might handle 10,000 concurrent connections with a single thread because most of that time is spent waiting for databases, files, or network responses—none of which block the thread.

The Blocking Problem

What happens if you ignore this and write blocking code?

import express from 'express';
import fs from 'fs';

const app = express();

app.get('/slow-sync', (req, res) => {
  // This blocks the entire server!
  const data = fs.readFileSync('large-file.txt', 'utf8');
  res.send(data);
});

app.listen(3000);

If a request to /slow-sync takes 2 seconds, every other request waits 2 seconds. The single thread is occupied and can't handle other requests.

With 100 simultaneous requests, they queue up and wait for the thread. This destroys performance.

Worker Threads for CPU-Intensive Work

For CPU-intensive operations (like complex calculations), Node.js has worker threads. You can offload heavy computations to prevent blocking:

import express from 'express';
import { Worker } from 'worker_threads';
import path from 'path';
import { fileURLToPath } from 'url';

const app = express();
const __dirname = path.dirname(fileURLToPath(import.meta.url));

app.get('/cpu-intensive', (req, res) => {
  // Delegate to a worker thread
  const worker = new Worker(path.join(__dirname, 'worker.js'));
  
  worker.on('message', (result) => {
    res.json({ result });
  });
  
  worker.postMessage({ data: 'process this' });
});

app.listen(3000);

This keeps the main thread responsive while a worker does the heavy computation.

Key Takeaways

• Node.js runs JavaScript on a single thread, achieving concurrency, not parallelism

• Slow operations like I/O are delegated to background workers

• While workers are busy, the main thread handles other requests

• The event loop coordinates everything

• This model scales well and uses resources efficiently

• Blocking code (synchronous operations) kills performance

• For CPU-intensive tasks, use worker threads

• The single-threaded model is a feature, not a limitation

Understanding this is key to writing efficient Node.js applications. Don't block the thread, let it coordinate work, and your server will handle massive concurrent load.

Why Node.js Needs an Event Loop

Node.js runs on a single thread. There's one thread executing your JavaScript code. But a single thread would be useless if it blocked on every slow operation.

The event loop is the solution. It lets you execute code non-blocking. While waiting for operations to complete, the event loop checks what's ready and executes callbacks.

The Basic Concept

Imagine a task manager:

1. You give the manager tasks

2. The manager executes tasks one by one

3. For tasks that take time (like filing documents), the manager delegates to workers

4. Once workers finish, the manager executes the callback

5. The manager never sits idle waiting

This is the event loop.

How the Event Loop Works

When you run Node.js:

console.log('Start');

setTimeout(() => {
  console.log('Timeout');
}, 100);

console.log('End');

Output:

Start
End
Timeout

Here's what happens behind the scenes:

1. Main JavaScript code executes
   - Logs "Start"
   - setTimeout schedules callback (doesn't execute now)
   - Logs "End"
   - Main code complete

2. Event loop checks: Is anything ready?
   - 100ms haven't passed, nothing ready
   
3. 100ms passes

4. Event loop checks: Is anything ready?
   - Timeout callback is ready! Execute it
   - Logs "Timeout"

5. No more callbacks, event loop waits

The event loop is constantly checking: "Is there anything I need to do?"

Call Stack and Callback Queue

The event loop manages two things:

Call Stack: Where your code executes

Callback Queue: Where callbacks wait to execute

Your Code
   |
   v
Call Stack (currently executing)
   |
   v (if done)
Event Loop (checks: anything in queue?)
   |
   v
Callback Queue (waiting callbacks)

When the call stack is empty, the event loop picks a callback from the queue and executes it.

Visualizing the Event Loop

Here's a more detailed flow:

console.log('1');

setTimeout(() => {
  console.log('2');
}, 0);

console.log('3');

Timeline:

Time 0ms:
- Call Stack: [console.log('1')]
- Execute: Logs '1'
- Call Stack is empty

Time 0ms:
- Call Stack: [setTimeout callback scheduled]
- Callback added to queue
- Call Stack is empty

Time 0ms:
- Call Stack: [console.log('3')]
- Execute: Logs '3'
- Call Stack is empty

Time 0ms (main code done):
- Event Loop checks queue
- Callback queue has the setTimeout callback
- Move callback to call stack
- Execute: Logs '2'
- Call Stack is empty

Done

Output:

1
3
2

Even though setTimeout had 0ms delay, it doesn't execute immediately. It's always after the main code finishes.

Phases of the Event Loop

The event loop has several phases. Each phase handles different types of operations:

┌───────────────────────────┐
│      Event Loop Phases    │
├───────────────────────────┤
│   1. Timers               │ (setTimeout, setInterval)
│   2. Pending Callbacks    │ (OS operations)
│   3. Idle, Prepare        │ (Internal)
│   4. Poll                 │ (I/O operations)
│   5. Check                │ (setImmediate)
│   6. Close Callbacks      │ (Socket close)
└───────────────────────────┘

The event loop cycles through these phases repeatedly.

File I/O and the Event Loop

File operations demonstrate the event loop perfectly:

import fs from 'fs';

console.log('Start');

fs.readFile('file.txt', (err, data) => {
  console.log('File read');
});

console.log('End');

Output:

Start
End
File read

Timeline:

1. Main code starts
2. Logs "Start"
3. fs.readFile called - work delegated to file system worker
4. Logs "End"
5. Main code done

6. Event loop checks: Is file read done?
7. No, not yet

8. ...time passes...

9. Event loop checks: Is file read done?
10. Yes! Add callback to queue

11. Event loop executes callback from queue
12. Logs "File read"

Your code never waits. The file is read in the background while your code continues.

setTimeout vs setImmediate

Both defer execution, but they're in different phases:

setImmediate(() => console.log('Immediate'));
setTimeout(() => console.log('Timeout'), 0);

Output (usually):

Timeout
Immediate

setTimeout executes in the Timers phase, setImmediate in the Check phase. The event loop visits Timers first.

Microtasks vs Macrotasks

There's a subtle complexity: microtasks and macrotasks.

Microtasks (execute immediately after each operation):

• Promises (.then, .catch, .finally)

• process.nextTick()

Macrotasks (queued in phases):

• setTimeout

• setInterval

• setImmediate

• I/O operations

Here's the key: After each macrotask, the event loop executes ALL microtasks before moving to the next macrotask.

console.log('Start');

setTimeout(() => {
  console.log('Timeout');
}, 0);

Promise.resolve()
  .then(() => console.log('Promise 1'))
  .then(() => console.log('Promise 2'));

console.log('End');

Output:

Start
End
Promise 1
Promise 2
Timeout

Timeline:

1. Main code: Logs "Start"
2. Main code: setTimeout scheduled (to Macrotask queue)
3. Main code: Promises created and scheduled (to Microtask queue)
4. Main code: Logs "End"
5. Main code done

6. Event loop checks: Any microtasks?
7. Yes! Execute Promise .then
8. Logs "Promise 1"

9. Microtask queue still has one
10. Execute it
11. Logs "Promise 2"

12. No more microtasks
13. Event loop checks: Any macrotasks?
14. Yes! setTimeout callback
15. Execute it
16. Logs "Timeout"

Promises always execute before setTimeout, even with 0ms delay!

Practical Example

Here's a realistic scenario:

import fs from 'fs/promises';

console.log('1: Start');

setTimeout(() => {
  console.log('2: setTimeout');
}, 0);

fs.readFile('file.txt', 'utf8')
  .then(data => {
    console.log('3: File read (Promise)');
  });

Promise.resolve()
  .then(() => console.log('4: Promise'));

console.log('5: End');

Output:

1: Start
5: End
4: Promise
3: File read (Promise)
2: setTimeout

Explanation:

1. Synchronous code runs first (1, 5)

2. Microtasks run (4)

3. File read completes and resolves (3) - still a microtask

4. Macrotasks run (2)

Common Mistakes

Mistake 1: Assuming setTimeout runs immediately

setTimeout(() => {
  console.log('runs second');
}, 0);

console.log('runs first');

Even with 0ms, setTimeout callback doesn't run immediately. It waits until the main code finishes.

Mistake 2: Long-running operations block the event loop

// Bad - blocks event loop for 5 seconds
function expensive() {
  for (let i = 0; i < 1_000_000_000; i++) {
    Math.sqrt(i);
  }
}

setTimeout(() => {
  expensive(); // Blocks entire event loop
}, 100);

// While expensive() runs, no other callbacks execute

Mistake 3: Thinking setImmediate is faster

setImmediate(() => console.log('1'));
setTimeout(() => console.log('2'), 0);

setImmediate doesn't necessarily run first. It depends on whether the current phase is the Check phase.

Debugging the Event Loop

You can visualize event loop behavior:

const start = Date.now();

setTimeout(() => {
  console.log(`Timer: ${Date.now() - start}ms`);
}, 100);

Promise.resolve()
  .then(() => console.log(`Promise 1: ${Date.now() - start}ms`))
  .then(() => console.log(`Promise 2: ${Date.now() - start}ms`));

console.log(`Main: ${Date.now() - start}ms`);

Output:

Main: 0ms
Promise 1: 0ms
Promise 2: 0ms
Timer: 102ms

The promises run immediately (microtasks), the timer waits for its delay.

Key Takeaways

• The event loop continuously checks what work is ready to do

• Your JavaScript code runs on the main thread, blocking the event loop

• I/O operations run on background workers, not blocking the event loop

• Callbacks wait in queues until the event loop picks them up

• Microtasks (Promises) always run before macrotasks (timers, I/O)

• Even setTimeout(..., 0) doesn't run immediately

• Long-running code blocks the entire event loop

• Understanding the event loop is key to writing efficient Node.js

The event loop isn't magic. It's a simple idea: check what's ready, execute it, repeat. Master this concept, and you'll write Node.js code that scales and performs well.

Step 1: Install Node.js

Visit nodejs.org and download the LTS (Long Term Support) version. This is the stable, recommended version for most users.

The installer includes both Node.js and npm (Node Package Manager), which you'll need for managing code libraries.

Run the installer and follow the default options. Once complete, open a terminal and verify the installation:

node --version
npm --version

You should see version numbers:

v18.16.0
9.6.7

If you see version numbers, you're good. If you get "command not found," try restarting your terminal or computer.

Step 2: Create a Project Folder

Open your terminal and create a folder for your project:

mkdir my-first-app
cd my-first-app

Navigate into this folder. Everything you create will live here.

Step 3: Initialize npm

Initialize npm to create a package.json file:

npm init -y

The -y flag skips questions and creates a default package.json. This file tracks your project's metadata and dependencies.

You'll see a new package.json file in your folder.

Step 4: Create Your First Script

Create a file called hello.js:

touch hello.js

Open it in your editor and write:

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

This is the simplest possible Node.js program. It just prints a message.

Step 5: Run Your Script

In your terminal, run:

node hello.js

You should see:

Hello, Node.js!

Congratulations! You've run your first Node.js script.

Step 6: Understand the Node REPL

The REPL (Read-Eval-Print Loop) is an interactive JavaScript environment. It's useful for experimenting.

Type node in your terminal with no filename:

node

You'll see a > prompt:

>

Now you can type JavaScript and execute it immediately:

> console.log('Testing')
Testing
undefined
> 2 + 2
4
> const greeting = 'Hello'
undefined
> greeting
'Hello'

To exit the REPL, press Ctrl+C twice or type .exit and press Enter.

The REPL is great for testing small pieces of code before adding them to your scripts.

Step 7: Work with Files

Node.js comes with the fs module for reading and writing files. Let's create a data file and read it.

Create a file called data.txt:

echo "This is some data" > data.txt

Now create a script called read-file.js:

import fs from 'fs';

fs.readFile('data.txt', 'utf8', (err, data) => {
  if (err) {
    console.log('Error reading file:', err);
  } else {
    console.log('File contents:', data);
  }
});

Run it:

node read-file.js

Output:

File contents: This is some data

You're reading a file asynchronously. Node.js reads the file without blocking, and calls the callback when done.

Step 8: Create a Simple Web Server

Now let's create a basic HTTP server:

Create a file called server.js:

import http from 'http';

const hostname = 'localhost';
const port = 3000;

const server = http.createServer((req, res) => {
  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/plain');
  res.end('Hello from Node.js server!');
});

server.listen(port, hostname, () => {
  console.log(`Server running at http://\({hostname}:\){port}/`);
});

Run it:

node server.js

You'll see:

Server running at http://localhost:3000/

Open your browser and visit http://localhost:3000/. You'll see your message!

To stop the server, press Ctrl+C in the terminal.

Project Structure Overview

Your project folder now looks like:

my-first-app/
  package.json
  hello.js
  data.txt
  read-file.js
  server.js

Each file is a standalone script you can run with node filename.js.

Understanding package.json

Your package.json looks something like:

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

Key fields:

• name: Your project's name
• version: Version number
• type: Set to "module" for ES imports
• main: Entry point file
• scripts: Commands you can run with npm run
• dependencies: Packages your project needs (currently empty)

Installing Packages

Node.js has an enormous ecosystem of packages. Install them with npm.

For example, install Express (a popular web framework):

npm install express

This downloads Express and saves it in a node_modules/ folder. It also updates package.json:

{
  "dependencies": {
    "express": "^4.18.2"
  }
}

Now you can use Express in your code:

import express from 'express';

const app = express();
app.get('/', (req, res) => {
  res.send('Hello with Express!');
});
app.listen(3000);

Common npm Commands

# Install a package
npm install package-name

# Install packages listed in package.json
npm install

# Run a script from package.json
npm run script-name

# List installed packages
npm list

# Update packages
npm update

Tips for Success

Use meaningful file names: server.js, utils.js, models.js tell you what each file does.

Keep it organized: As projects grow, organize files into folders like src/, models/, routes/.

Comment your code: Explain why you're doing things, not just what you're doing.

Use the REPL for learning: Test small snippets before adding them to files.

Check documentation: When stuck, Google it or check the official Node.js docs at nodejs.org.

What's Next?

You've learned:

• How to install and run Node.js
• How to create and run scripts
• How to use the REPL
• How to read files
• How to create a basic HTTP server
• How to manage packages with npm

From here, you can explore:

• Express.js for building web applications
• Connecting to databases
• Building REST APIs
• Understanding async code deeper

Key Takeaways

• Install Node.js from nodejs.org
• Create scripts in .js files
• Run scripts with node filename.js
• Use the REPL for experimentation
• package.json manages your project and dependencies
• npm installs and manages packages
• Node.js has built-in modules like fs and http

You now have a solid foundation. Practice creating small scripts, experimenting in the REPL, and building simple servers. The more you practice, the more comfortable Node.js becomes.

Before Node.js: JavaScript Was Browser-Only

JavaScript started in 1995 as a language for browsers. Its job was to add interactivity to web pages: validating forms, showing/hiding elements, animating things.

It worked great for that. But it had a limitation: it only ran in browsers. If you wanted to build a server, you used PHP, Python, Java, or other languages.

This meant developers had to learn two languages:

• JavaScript for the frontend

• Another language for the backend

Node.js: JavaScript on the Server

In 2009, Ryan Dahl created Node.js. It brought JavaScript runtime to servers.

Now developers could write both frontend and backend in JavaScript. One language, multiple environments.

// Frontend (browser)
document.getElementById('button').addEventListener('click', () => {
  console.log('Button clicked');
});

// Backend (Node.js)
import express from 'express';
const app = express();
app.get('/api/data', (req, res) => {
  res.json({ message: 'Data from server' });
});

Same language, different contexts.

What Exactly Is Node.js?

Node.js is a JavaScript runtime. A runtime is an environment where code executes.

A programming language is one thing. A runtime is the environment that understands and runs that language.

Think of it like this:

• Language: JavaScript (the syntax and rules)

• Runtime: Browser (for frontend), Node.js (for backend)

Node.js uses the V8 engine, the same JavaScript engine that powers Google Chrome. V8 compiles JavaScript to machine code, making it fast.

Why JavaScript, Though?

Developers already knew JavaScript. Instead of learning a new language for the server, they could use JavaScript everywhere.

Also, JavaScript is event-driven and asynchronous by design. This fits perfectly with server applications that handle many concurrent requests.

Node.js Architecture: High Level

When you run a Node.js application, here's what happens:

Your JavaScript Code
        |
        v
Node.js Runtime
  (V8 Engine + APIs)
        |
        v
Operating System
  (File system, networking, etc.)
        |
        v
Hardware

V8 compiles your JavaScript to machine code. The Node.js runtime provides APIs like fs (file system) and http (networking) that your code can use.

Node.js vs Browser JavaScript

Both run JavaScript, but differently:

In a browser, you manipulate the DOM. In Node.js, you work with the file system and network.

Real-World Use Cases

Building APIs and Web Servers:

import express from 'express';
const app = express();
app.get('/api/users', (req, res) => res.json({ users: [] }));
app.listen(3000);

Command-line Tools:

# Tools like npm, webpack, eslint are built with Node.js
npm install
webpack build
eslint --fix

Real-time Applications: Node.js handles concurrent connections well, perfect for chat apps, collaborative tools, live updates.

Scripting and Automation: Automate tasks, process files, generate reports.

Building single-page applications: Tools like webpack, Vite, and Next.js use Node.js.

The Event-Driven Architecture

Node.js is event-driven. Instead of threads doing work, events trigger handlers.

import fs from 'fs';

console.log('Starting...');

fs.readFile('data.txt', (err, data) => {
  console.log('File read complete');
});

console.log('Continuing...');

Output:

Starting...
Continuing...
File read complete

The file read doesn't block. While waiting, Node.js handles other things. When the file is ready, an event fires, triggering the callback.

This is why Node.js handles many concurrent requests efficiently. Most time is spent waiting for databases, files, or network responses. Node.js doesn't waste processor time on waiting.

Companies Using Node.js

Node.js powers major applications:

• Netflix: Node.js for UI and streaming

• Uber: Real-time ride matching

• LinkedIn: Real-time updates

• Walmart: API backend

• Airbnb: Backend services

These companies chose Node.js because it's fast, scalable, and lets them reuse developers across frontend and backend.

Node.js Ecosystem: npm

npm (Node Package Manager) is a package repository. Hundreds of thousands of packages are available, from HTTP frameworks to image processing.

Install packages easily:

npm install express
npm install lodash
npm install axios

This ecosystem is massive and active. Most problems you encounter, someone's already solved with a package.

Performance Considerations

Node.js is fast for I/O-bound tasks (database queries, file reads, HTTP requests). Most web applications are I/O-bound.

It's less ideal for CPU-intensive tasks (image processing, complex calculations). For those, you'd use worker threads or other languages.

But for typical web applications and APIs, Node.js performance is excellent.

Getting Started

To start with Node.js:

1. Install from nodejs.org

2. Create a file: hello.js

3. Write code: console.log('Hello')

4. Run: node hello.js

That's it. You're running JavaScript on your server.

Node.js vs Other Backend Languages

Each language has tradeoffs. Node.js excels at I/O-heavy applications where you want full JavaScript from frontend to backend.

Key Takeaways

• Node.js is a JavaScript runtime that lets you run JavaScript on servers

• It uses the V8 engine, the same engine that powers Chrome

• It's event-driven and asynchronous, perfect for handling many concurrent requests

• The npm ecosystem is massive with hundreds of thousands of packages

• Many major companies use Node.js for their backend infrastructure

• It's ideal for I/O-bound applications like web APIs and real-time apps

• Learning Node.js lets you build full-stack applications in JavaScript

Node.js democratized backend development. You no longer need to learn multiple languages. JavaScript everywhere has become reality.

If you know JavaScript, you can build servers. That's the power of Node.js.