DEV Community: SATYA SOOTAR

Sessions vs JWT vs Cookies: Understanding Authentication Approaches

SATYA SOOTAR — Sun, 10 May 2026 14:15:37 +0000

Hello readers 👋, welcome to the 15th blog in our Node.js series!

In our previous posts, we built a REST API, learned how to protect routes with JWT, and explored middleware and file uploads. Authentication has come up several times, but today we’re going to take a step back and look at the bigger picture. We’ll compare three pillars of authentication in web applications: sessions, JSON Web Tokens (JWT), and cookies.

If you’ve ever been confused about when to use a session-based login, when to reach for a JWT, or where cookies fit into all this, this post will clear things up. We’ll keep it practical, avoid deep security rabbit holes, and end with a decision framework you can apply to your next project.

Let’s get started.

What are cookies?

Cookies are small pieces of data stored on the client (browser) by the server via the Set-Cookie header. They are automatically sent back to the server with every subsequent request to the same domain. That’s their superpower: they travel with every request without the client having to do anything extra.

A cookie looks something like this:

Set-Cookie: sessionId=abc123; HttpOnly; Secure; SameSite=Strict

The browser then dutifully sends Cookie: sessionId=abc123 with each request.

Cookies alone are not an authentication method; they are a transport mechanism. They can carry a session ID, a JWT, or just a simple preference. But because sessions almost always rely on cookies, the two are often mentioned together.

Key properties you can set on cookies:

HttpOnly – the cookie cannot be accessed via JavaScript (document.cookie), which helps prevent XSS attacks.
Secure – the cookie is only sent over HTTPS.
SameSite – controls whether the cookie is sent on cross‑site requests, mitigating CSRF.

In a traditional session‑based authentication, the server sets a cookie containing a unique session ID, and all further requests carry that cookie to identify the user.

What are sessions?

Session‑based authentication is the classic approach. After the user logs in with valid credentials, the server creates a session – a record in a database, in‑memory store, or cache (like Redis) that contains the user’s identity and any other relevant data. The server then sends back a cookie holding only the session ID.

Every subsequent request comes with that cookie. The server reads the session ID, looks up the session data (often from a store), and knows who the user is without them sending the password again.

Let’s see a simplified Express example using express-session:

const session = require('express-session');

app.use(session({
  secret: 'your-secret-key',
  resave: false,
  saveUninitialized: true,
  cookie: { secure: true, httpOnly: true, maxAge: 3600000 } // 1 hour
}));

app.post('/login', (req, res) => {
  // authenticate user
  req.session.userId = user.id; // stored on server
  res.send('Logged in');
});

app.get('/dashboard', (req, res) => {
  if (!req.session.userId) return res.status(401).send('Unauthorized');
  // fetch user data using session.userId
  res.send(`Hello user ${req.session.userId}`);
});

Sessions are stateful: the server must maintain a session store (memory, database, Redis). When you scale to multiple server instances, the session store must be shared, which adds complexity.

What are JWT tokens?

JSON Web Tokens (JWT) are a stateless authentication method. After a successful login, the server generates a token containing a payload (like the user’s ID and role) and signs it with a secret key. The token is sent to the client, which stores it. For each subsequent request, the client sends the token, usually in the Authorization header as a Bearer token, or sometimes in an HttpOnly cookie. The server verifies the signature, extracts the payload, and trusts that the user is who the token claims.

We’ve already implemented JWT authentication in an earlier blog. Here’s a quick recap:

const jwt = require('jsonwebtoken');

app.post('/login', (req, res) => {
  // authenticate user
  const token = jwt.sign({ userId: user.id }, 'secret', { expiresIn: '1h' });
  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');
    req.user = decoded;
    res.send(`Profile of user ${req.user.userId}`);
  } catch (err) {
    res.status(403).send('Invalid token');
  }
});

Because JWT contains all the info needed (in the payload), the server doesn’t need to look up a session. That’s the stateless magic.

Stateful vs stateless authentication

This is the key distinction.

Stateful (sessions): The server keeps track of authenticated users. Each request requires a session lookup. This works great for traditional multi‑page apps because scaling requires a shared session store. Logout is easy: just destroy the session on the server.
Stateless (JWT): The server doesn’t store anything. It trusts the token after verifying the signature. This makes horizontal scaling a breeze. Logout is trickier: since the server doesn’t remember the token, you can’t invalidate it without a blacklist (bringing back some state). Usually, you set short expiration and rely on the client removing the token.

Think of sessions as a coat-check ticket: you give the clerk your coat, get a ticket, and later hand the ticket back to retrieve your coat. The clerk (server) remembers you. JWT is like a digital passport: the passport says who you are, and the border official (server) verifies its authenticity without calling home. Both have their place.

Sessions vs JWT: detailed comparison

Feature	Session‑based	JWT
State	Stateful (server stores session data)	Stateless (server only verifies token)
Storage	Session ID stored in a cookie; session data stored server‑side (memory, DB, Redis)	Token stored client‑side: browser (localStorage, sessionStorage) or HttpOnly cookie; no server‑side storage
Scalability	Requires shared session store across instances (e.g., Redis)	Easy to scale horizontally; no server‑side data sharing needed
Logout	Server deletes session – immediate effect	No server‑side record; token can’t be invalidated instantly unless a blacklist is used. Short expiry & client removal are typical
Security typical risks	Session hijacking (if cookie stolen), CSRF (mitigated with SameSite, tokens)	Token theft (if stored in non‑HttpOnly cookie or localStorage), XSS (if accessible via JS), token size
Payload visibility	Server‑side, opaque to client	Payload is Base64‑encoded (not encrypted); everyone can read it, but signature ensures integrity. Never put secrets in payload
Typical use case	Traditional server‑rendered web apps, multi‑page apps, apps with centralized user management	APIs, single‑page applications (SPAs), mobile apps, microservices, third‑party integrations

Note that you can store a JWT inside an HttpOnly cookie, blending some benefits: you get automatic cookie sending (no need to attach header manually) and protection from XSS, while still being stateless. The choice of where to store the token is separate from the choice of session vs JWT.

When to use each method

Use sessions when:

You have a traditional server‑rendered application (EJS, Pug, etc.).
You need fine‑grained control over active session invalidation (e.g., force logout, revoke access instantly).
You’re comfortable managing a session store (or don’t mind the overhead for a simple app).
You want to keep sensitive data on the server.

Use JWT when:

You are building a REST API that serves multiple frontends (web, mobile, desktop).
You want to scale horizontally without worrying about a shared data store.
You need to pass authorization across multiple independent services (microservices).
Your client is a SPA where the frontend handles presentation and stores the token (e.g., in memory or localStorage, though HttpOnly cookie is safer).

A hybrid approach: store a short‑lived JWT inside an HttpOnly, Secure, SameSite cookie. That way you get automatic cookie handling, XSS protection, and still remain stateless on the server. This is increasingly popular in modern frameworks.

Conclusion

Sessions, cookies, and JWT aren’t mutually exclusive; they’re pieces of the authentication puzzle. Cookies transport data (session IDs or JWTs) seamlessly. Sessions give you server‑side control at the cost of state. JWT gives you stateless scalability at the cost of instant invalidation. Choosing between them depends on your application architecture, scalability needs, and security priorities.

To recap:

Cookies are a transport mechanism, automatically sent with every request, and can be secured with HttpOnly, Secure, and SameSite flags.
Sessions store user state on the server and use a cookie holding a session ID. They are stateful and great for traditional web apps.
JWT embeds user information in a signed token; the server doesn’t need a lookup. They are stateless and ideal for APIs, SPAs, and microservices.
The decision often hinges on stateful vs stateless needs and where you want to store sensitive data.

In the next post, we’ll start connecting Express to databases; building a full‑stack authentication flow with registration and login that persists real data. See you then!

Hope you found this helpful! If you spot any mistakes or have suggestions, let me know. You can find me on LinkedIn and X, where I post more about web development.

URL Parameters vs Query Strings in Express.js

SATYA SOOTAR — Sun, 10 May 2026 14:09:37 +0000

Hello readers 👋, welcome to the 14th blog in our Node.js series!

In the last few posts, we built a complete file upload and serving system using Multer and Express. We learned how to accept files, store them safely, and serve them back via static URLs. Today, we're going to shift focus to something more subtle but equally important: how to extract information from the URL itself. Specifically, we'll talk about URL parameters and query strings in Express.js.

You see these every day: URLs like /users/42 or /search?q=express&sort=asc. Knowing when to use a parameter (the 42) versus a query string (the ?q=express) makes your API design cleaner and more intuitive. Let's break it all down with clear examples.

Let's get started.

What URL parameters are

URL parameters (also called route parameters) are segments of the URL path that act as placeholders. They are part of the path itself and are typically used to identify a specific resource. In Express, you define them with a colon (:) prefix in the route path, and Express captures their values into req.params.

Think of <name> as a placeholder for something like an ID, a username, or a category. The actual value appears in the URL after the previous segment.

Here's a basic route that uses a parameter:

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

app.get('/users/:userId', (req, res) => {
  const userId = req.params.userId;
  res.send(`User profile for ID: ${userId}`);
});

If you visit http://localhost:3000/users/123, req.params.userId will be "123". Notice that the parameter is part of the path. It's not optional; the route wouldn't match /users/ alone (without an ID).

You can have multiple parameters in a single route:

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

The values are always strings, so you may need to parse them into numbers if needed (parseInt). Express doesn't do any type conversion automatically.

What query strings (query parameters) are

Query strings are key-value pairs that come after a question mark (?) in a URL. They are used to send additional data that is often optional, like filters, sorting options, pagination, or search terms. They are not part of the route path itself. In Express, you access them via req.query.

For example, a search URL might look like this:

/search?q=express&page=2&limit=10

Here, q, page, and limit are query parameters. Express parses them and makes them available in req.query as an object.

Example route:

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

A request to /search?q=node&page=3 gives:

{ "query": "node", "page": "3", "limit": 10 }

Query strings are extremely flexible because they don't affect route matching directly; any number of them can be added to a URL without breaking the route pattern.

Differences between URL parameters and query strings

The core difference lies in their purpose and placement.

Aspect	URL Parameters (Route params)	Query Strings
Appearance in URL	Part of the path: `/users/42`	After `?` in the URL: `/users?role=admin`
Purpose	Identify a specific resource (required)	Provide additional instructions or filters (optional)
Route matching	Must be defined in route path with `:param`	Does not affect which route is matched
Express access	`req.params` (object)	`req.query` (object)
Typical use cases	Entity ID, username, category, blog post slug	Search, pagination, sorting, filtering, API keys
Order in URL	Fixed position in the path	Unordered, can be combined arbitrarily
Optionality	Usually required for the resource to make sense	Often optional with defaults

A good mental model: parameters point to a specific "noun" (the resource); query strings describe "how" or "what to do" with that resource, like filtering or sorting.

Accessing params in Express

As shown earlier, you define placeholders in the route string using :paramName. Then inside the handler, you read req.params. All values are strings.

If you need to make a parameter optional and still match the base route, you can use a ? after the parameter name (like :userId?), but then you'd need to handle the case where it's undefined. Alternatively, define two routes: one with and one without the parameter.

Here's an example of an optional parameter:

app.get('/articles/:year?/:month?', (req, res) => {
  const { year, month } = req.params;
  res.send(`Articles ${year ? 'for ' + year : ''} ${month ? '/' + month : ''}`);
});

But be careful, req.params will contain strings for whatever segments exist.

Accessing query strings in Express

Query strings don't need to be declared. Any key=value pair after the ? will appear in req.query. If a key appears multiple times (e.g., ?tag=js&tag=node), Express by default gives you an array (only if you use a certain parsing library; the built-in qs library parses arrays with repeated keys). So req.query.tag might be ['js', 'node'].

Example with arrays:

app.get('/items', (req, res) => {
  const tags = req.query.tags;
  // tags could be a string or an array if multiple
  const tagsArray = Array.isArray(tags) ? tags : [tags].filter(Boolean);
  res.json({ tags: tagsArray });
});

When to use params vs query: practical examples

User profile ID (use params)

You want to get a specific user by ID. The ID is the identifier of the resource, so it belongs in the path.

app.get('/users/:id', (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  if (!user) return res.status(404).json({ error: 'User not found' });
  res.json(user);
});

This makes the URL clean: /users/5. Without the ID, the route doesn't make sense. So a parameter is the right choice.

Search filters (use query strings)

You want to filter a list of products by category, price range, and sort order. None of these are "the resource identifier". They are optional, descriptive modifiers. So they go in the query string.

app.get('/products', (req, res) => {
  const { category, minPrice, sort } = req.query;
  let results = [...products];
  if (category) results = results.filter(p => p.category === category);
  if (minPrice) results = results.filter(p => p.price >= Number(minPrice));
  if (sort === 'asc') results.sort((a, b) => a.price - b.price);
  else if (sort === 'desc') results.sort((a, b) => b.price - a.price);
  res.json(results);
});

A request URL like /products?category=electronics&minPrice=100&sort=asc clearly communicates that we're viewing the products collection but with specific filters.

Mixed usage

Often, you'll combine both. For example, fetching comments for a specific post, with pagination:

GET /posts/:postId/comments?page=2&limit=10

Here, :postId identifies the post (required), while page and limit control how many comments are returned (optional with defaults).

Visualizing the URL structure

Every URL can be broken down into parts. Let's disassemble an example:

https://api.example.com/users/42?include=posts&limit=5

Protocol & domain: https://api.example.com
Path: /users/42
- Segment users (static)
- Segment 42 (dynamic, captured by :userId)
Query string: ?include=posts&limit=5
- include=posts
- limit=5

Express routes match against the path (ignoring the query string). So you'd define:

app.get('/users/:userId', (req, res) => { ... });

And then inside, req.params.userId gives "42", req.query.include gives "posts", and req.query.limit gives "5".

This separation allows the same route to respond differently based on what the client asks for, without defining countless different URL patterns.

Conclusion

Understanding URL parameters versus query strings is essential for designing clean, predictable REST APIs. URL parameters are used to identify a specific resource (like a user or a post) and appear as dynamic segments in the path. Query strings are used to modify the request, provide filters, pagination, or any optional data, and appear after the ? in the URL. Express makes both accessible with req.params and req.query.

Let's quickly recap:

URL parameters (:param) are parts of the path used for required resource identifiers. Accessed via req.params.
Query strings (?key=value) are optional key‑value pairs used for filtering, sorting, searching, and other modifiers. Accessed via req.query.
Route matching ignores query strings, so they are flexible and don't affect which handler runs.
Use parameters when the URL would be incomplete without that piece of data; use query strings for everything else that's optional or descriptive.
In Express, both are available as simple JavaScript objects, making it easy to extract and use them.

Armed with this understanding, your routes will become more intuitive and your APIs more predictable. See you in the next post!

Hope you found this helpful! If you spot any mistakes or have suggestions, let me know. You can find me on LinkedIn and X, where I post more about web development.

Storing Uploaded Files and Serving Them in Express

SATYA SOOTAR — Sun, 10 May 2026 14:05:18 +0000

Hello readers 👋, welcome to the 13th blog in our Node.js series!

In the last post, we learned how Multer helps us accept file uploads in Express, whether single files or multiple files. We configured a disk storage engine and saw how req.file and req.files give us all the details about what arrived. But one question remained unanswered: where do the uploaded files actually live, and how do clients get them back?

Today we're going to close that loop. We'll talk about storage choices, how to serve uploaded files so they're accessible via a URL, and crucial security practices that keep your application safe. By the end, you'll have a complete picture of the upload‑serve lifecycle.

Let's jump in.

Where uploaded files are stored

When Multer saves a file on the server, it places it into a folder that you specify via the destination callback. In our previous example, we used an uploads folder at the root of our project. After a few uploads, the folder might look something like this:

project/
├── uploads/
│   ├── avatar-1680000000-123456789.png
│   ├── avatar-1680000010-987654321.jpg
│   └── cover-1680000020-456789123.jpeg
├── server.js
└── package.json

The actual filenames are generated by the filename callback (often using a timestamp and a random number to avoid collisions). The original name is still available inside req.file.originalname, but on disk we keep a sanitized, unique name.

Local storage vs external storage concept

In development and small applications, storing files on the local filesystem is perfectly fine. It's simple and needs no extra setup. But as your application grows, you'll often hear about external storage services like Amazon S3, Google Cloud Storage, or Cloudinary. These services store files separately from your Node.js server, which brings several benefits:

Your server's disk space isn't used by user files.
The files can be served to clients directly from a CDN, reducing load on your application server.
Scaling becomes easier because the storage layer is independent.

For this post, we'll focus entirely on local storage because that's where most people start. We'll mention how to serve those local files directly to clients. Later, when you move to cloud storage, the ideas of URLs and security transfer easily.

Serving static files in Express

After a file is uploaded and stored on disk, you typically want to make it accessible through a URL so that a client (browser, mobile app) can download or display it. Express provides a built‑in middleware called express.static exactly for this purpose.

express.static takes a folder path and serves all files inside it as static assets. For example:

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

// Serve files from the 'uploads' folder at the '/files' URL path
app.use('/files', express.static('uploads'));

Now, if there is a file uploads/avatar-123456.png, it becomes available at http://localhost:3000/files/avatar-123456.png. The URL path you choose (/files) can be anything; it doesn't have to match the folder name.

A common practice is to serve the uploads folder under a dedicated path like /uploads or /files to keep the URL structure clear.

Setting up the complete flow

Let's combine Multer and static serving into a single Express app to see the full picture:

const express = require('express');
const multer = require('multer');
const path = require('path');
const fs = require('fs');

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

// Ensure uploads folder exists
const uploadsDir = path.join(__dirname, 'uploads');
if (!fs.existsSync(uploadsDir)) {
  fs.mkdirSync(uploadsDir);
}

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

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

// Upload route
app.post('/upload', upload.single('photo'), (req, res) => {
  if (!req.file) {
    return res.status(400).json({ error: 'No file uploaded' });
  }
  // Build the public URL
  const fileUrl = `http://localhost:${port}/files/${req.file.filename}`;
  res.json({
    message: 'File uploaded successfully',
    url: fileUrl
  });
});

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

After uploading, the client receives a JSON response containing the direct URL. It can then use that URL to display an image, download a document, or simply check the file.

Accessing uploaded files via URL

The key insight is that the public URL is built from three parts:

Base URL of your server (e.g., http://localhost:3000)
Static serving path (e.g., /files)
Filename on disk (the unique name generated by Multer)

In the route handler, req.file.filename gives us the exact name stored on disk. Concatenating these pieces gives a valid URL that Express will serve from the uploads folder.

For a more production‑ready approach, you'd likely construct the URL from a configuration setting, not hardcode localhost. For example:

const baseUrl = process.env.BASE_URL || `http://localhost:${port}`;
const fileUrl = `${baseUrl}/files/${req.file.filename}`;

Now clients always get the correct URL regardless of the environment.

Security considerations for uploads

File uploads are powerful but also a potential attack vector if not handled carefully. Here are some essential safe‑handling practices that every developer should follow.

1. Limit allowed file types

Never accept arbitrary file types. Use Multer's fileFilter to check the MIME type or file extension before writing to disk. For example, if you expect images:

const upload = multer({
  storage,
  fileFilter: (req, file, cb) => {
    const allowedTypes = /jpeg|jpg|png|gif/;
    const mimeType = allowedTypes.test(file.mimetype);
    const extName = allowedTypes.test(path.extname(file.originalname).toLowerCase());
    if (mimeType && extName) {
      return cb(null, true);
    }
    cb(new Error('Only image files are allowed'));
  }
});

2. Restrict file size

You can set a limits object on the Multer instance to reject files that are too large:

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

This prevents someone from filling up your server's disk with a single request.

3. Rename files to avoid path traversal

Never trust the original filename directly in the storage path. Always generate a new name, as we did with the filename callback. Using Date.now() and a random number makes it nearly impossible for an attacker to guess the filename. Also avoid including user‑supplied strings in the path to prevent directory traversal attacks (e.g., ../../../etc/passwd).

4. Store uploaded files outside the public web root

If possible, keep the uploads folder outside the main Express static folder that is openly served. In our setup, we used /files explicitly, but the uploads folder itself is not automatically exposed except through that route. Still, it's a good idea to store uploads in a directory that is not directly under the static root, and then use express.static with an absolute path to serve it under a specific URL prefix. This prevents direct access via path guessing.

5. Do not execute uploaded files

Make sure your static file serving middleware only serves files with safe content types. For example, if someone uploads a .php or .js file and you serve it via express.static, a browser might try to interpret it as code, especially if served with the wrong Content-Type. Express/Node.js static middleware sends files with an appropriate MIME type based on the extension, which usually prevents execution. Still, it's wise to limit accepted extensions and avoid storing executable scripts in the uploads folder.

6. Scan for malware (advanced)

For high‑security applications, you can integrate virus scanning tools that inspect uploaded files before they're stored. This is beyond the scope of this post, but keep it in mind for production systems.

Conclusion

Storing and serving uploaded files completes the file upload puzzle. By using Multer's disk storage and Express's static middleware, you can quickly give your users the ability to upload content and retrieve it via clean URLs. Add a few security precautions, and you have a robust foundation that works for development and small production apps.

Let's quickly recap:

Uploaded files can be stored locally in a project folder (e.g., uploads/) or externally on cloud services for scalability.
express.static lets you serve the files under a URL prefix, making them accessible to clients.
Building a file URL combines the base URL, the static serving path, and the unique filename stored on disk.
Security is essential: limit file types and sizes, rename files, avoid executable files, and store uploads outside the main public root if possible.
A clear folder structure and the static middleware together create an intuitive upload‑serve flow.

Now you have the full cycle: receiving files and giving them back. In the next post, we'll explore something new, maybe working with databases or error handling. See you then!

Hope you found this helpful! If you spot any mistakes or have suggestions, let me know. You can find me on LinkedIn and X, where I post more about web development.

Handling File Uploads in Express with Multer

SATYA SOOTAR — Sun, 10 May 2026 14:00:30 +0000

Hello readers 👋, welcome to the 12th blog in our Node.js series!

In the last post, we learned how Express simplifies route handling and request processing. Today, we're going to tackle a common real‑world requirement that every backend developer faces: handling file uploads. Whether it's a profile picture, a PDF invoice, or a batch of images, users need to send files to your server, and you need a clean way to receive and store them.

Express itself doesn't handle file uploads out of the box. That's where a specialized middleware called Multer comes in. We'll understand why file uploads need special handling, how Multer works, and then build practical examples for single and multiple file uploads. By the end, you'll be able to accept files, store them on disk, and serve them back to clients.

Let's jump right in.

Why file uploads need middleware

When a browser sends a file, it uses a special encoding called multipart/form-data. This encoding splits the request body into multiple parts, each representing a form field or a file. A regular JSON body parser like express.json() cannot parse multipart data. If you try, req.body will be empty, and the file data will be lost.

To handle multipart/form-data, we need a parser that knows how to extract files from the request stream and make them available to our code. Multer is precisely that parser.

What Multer is

Multer is a Node.js middleware for handling multipart/form-data, which is primarily used for uploading files. It is designed to work with Express and sits as a middleware in the request pipeline. When a request with a file arrives, Multer processes the incoming stream, saves the file(s) to a location you specify (disk or memory), and attaches a file (or files) object to the req object. The rest of your route handler can then access the file details.

Multer adds a file or files property to the request object. A single file upload sets req.file, while multiple files set req.files (an array or an object, depending on configuration). Each file object contains fields like originalname, mimetype, size, and path (if stored on disk).

The multipart/form-data concept simply

Imagine you want to mail a letter along with a small gift. You can't just stuff the gift into a regular envelope; you need a special package with compartments. Similarly, when a browser sends form data that includes a file, it can't just put everything into a single JSON object. It uses multipart/form-data, which creates boundaries (think of them as separators) that tell the server where each field or file begins and ends.

When you set enctype="multipart/form-data" on a form, the browser encodes the data using this format. Multer is the tool on the server side that understands these compartments and extracts the file from the correct part.

Setting up Multer

First, install Multer in your project:

npm install multer

Then, require it and configure a storage engine. We'll start with disk storage, which saves files directly to a folder on your server.

Minimal storage configuration

const multer = require('multer');

// Define where to store files and how to name them
const storage = multer.diskStorage({
  destination: function (req, file, cb) {
    // Specify the upload folder
    cb(null, 'uploads/');
  },
  filename: function (req, file, cb) {
    // Give the file a unique name, preserving the extension
    const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1E9);
    const extension = file.originalname.split('.').pop();
    cb(null, file.fieldname + '-' + uniqueSuffix + '.' + extension);
  }
});

const upload = multer({ storage: storage });

Here, multer.diskStorage lets you control the destination folder and filename. The callback cb is used to pass the final path or error. We generate a semi‑unique filename to avoid collisions.

Handling a single file upload

Let's create an Express route that accepts a single file, for example, a profile picture. The client sends the file under a field name, say avatar.

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

// Ensure the "uploads" folder exists, or Multer will error
const fs = require('fs');
const path = require('path');
const uploadsDir = path.join(__dirname, 'uploads');
if (!fs.existsSync(uploadsDir)){
    fs.mkdirSync(uploadsDir);
}

// Single file upload middleware
app.post('/profile', upload.single('avatar'), (req, res) => {
  // req.file contains information about the uploaded file
  if (!req.file) {
    return res.status(400).json({ message: 'No file uploaded' });
  }
  console.log(req.file);
  res.json({
    message: 'File uploaded successfully',
    file: {
      originalName: req.file.originalname,
      size: req.file.size,
      path: req.file.path
    }
  });
});

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

upload.single('avatar') is the Multer middleware. It expects the file to be sent in the form field named avatar. After successful upload, req.file contains:

fieldname – the name of the form field
originalname – the original name on the user's computer
mimetype – e.g., image/png
size – file size in bytes
destination – the folder where the file was saved
filename – the generated filename on disk
path – the full path to the uploaded file

Handling multiple file uploads

Multer provides several ways to accept multiple files.

1. Multiple files with the same field name (array of files)

Use upload.array('photos', 5) to accept up to 5 files in the field photos.

app.post('/gallery', upload.array('photos', 5), (req, res) => {
  if (!req.files || req.files.length === 0) {
    return res.status(400).json({ message: 'No files uploaded' });
  }
  const fileDetails = req.files.map(f => ({
    name: f.originalname,
    size: f.size
  }));
  res.json({ message: 'Files uploaded', files: fileDetails });
});

req.files is an array of file objects, each similar to req.file.

2. Multiple fields with different names

Use upload.fields([...]) when you have several distinct file fields, like avatar and cover.

const cpUpload = upload.fields([
  { name: 'avatar', maxCount: 1 },
  { name: 'cover', maxCount: 1 }
]);

app.post('/complete-profile', cpUpload, (req, res) => {
  // req.files is an object with keys 'avatar' and 'cover', each an array of files
  const avatar = req.files['avatar'] ? req.files['avatar'][0] : null;
  const cover = req.files['cover'] ? req.files['cover'][0] : null;
  res.json({ avatar: avatar?.originalname, cover: cover?.originalname });
});

Serving uploaded files

After uploading, you often need to serve the files back to the client (e.g., to display an image). Express has a built‑in middleware express.static for serving static files from a directory.

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

Now, if a file was saved as uploads/avatar-123456789.png, the client can access it at http://localhost:3000/files/avatar-123456789.png. You can use the relative path to build the URL.

Visualizing the upload flow

Client → Server → Storage flow:

Client (browser)
  │
  ├── Sends POST /profile with multipart/form-data (file in field "avatar")
  │
  ▼
Express Server
  │
  ├── Multer middleware (upload.single('avatar'))
  │     ├── Parses multipart data
  │     ├── Streams file to disk (or memory)
  │     └── Attaches req.file
  │
  ▼
Route Handler
  │
  ├── Accesses req.file details
  ├── Saves metadata to database (if needed)
  └── Sends response (e.g., file URL)

Multer middleware execution:

Request
  │
  ▼
Multer middleware (configured with storage engine)
  │
  ├── Read stream → Identify boundaries
  │
  ├── For each file field:
  │     ├── Extract filename, MIME type
  │     ├── Call storage._handleFile (disk or memory)
  │     │     └── Write to disk / buffer
  │     └── Emit 'file' event or push to array
  │
  ├── Calls next() when all fields and files processed
  │
  ▼
Next middleware / route handler (receives req.file or req.files)

That summarizes the lifecycle.

Conclusion

Multer makes handling file uploads in Express straightforward. By plugging it as a middleware, you can accept single or multiple files, control where they are saved, and then serve them back easily. Understanding multipart/form-data and Multer's role is key to building applications that accept user‑generated content.

Let's quickly recap:

File uploads use multipart/form-data; regular body parsers can't handle them.
Multer is an Express middleware that parses multipart data and gives you req.file or req.files.
Configure storage using multer.diskStorage to define destination and filename.
upload.single(), upload.array(), and upload.fields() cover most use cases.
Serve uploaded files with express.static for easy access.
The upload lifecycle flows from client to Multer to disk, then to your route handler.

Now you can confidently add file upload capabilities to your Node.js APIs. In the next post, we might explore error handling in Multer or move on to database integration. See you then!

Hope you found this helpful! If you spot any mistakes or have suggestions, let me know. You can find me on LinkedIn and X, where I post more about web development.

Creating Routes and Handling Requests with Express

SATYA SOOTAR — Sun, 10 May 2026 13:52:33 +0000

Hello readers 👋, welcome to the 11th blog in our Node.js series!

We've come a long way. We started by setting up Node.js, understood its event loop, explored blocking vs non‑blocking code, handled async operations with promises, secured routes with JWT, designed a REST API, and even dove into middleware. But to build those APIs and middleware, we used Express.js. Now it's time to shine a focused light on exactly how Express helps us create routes and handle requests so effortlessly.

In this post, we'll take a step back and talk about what Express.js is, why it makes Node.js development so much smoother, and how to create clean, readable routes for GET and POST requests. By the end, you'll see why Express has become the go‑to framework for building web servers with Node.js.

Let's jump in.

What is Express.js?

Express.js is a minimal and flexible web application framework for Node.js. It provides a thin layer of fundamental web application features, without obscuring Node.js features that you know and love. In simpler words, it's a set of tools that makes it ridiculously easy to handle HTTP requests, define routes, work with middleware, and send responses.

At its core, Express is just a function that returns an application object. You attach route handlers to it, and it efficiently maps incoming requests to the right handlers.

Why Express simplifies Node.js development

To appreciate Express, let's quickly compare it with building an HTTP server using Node.js's built‑in http module.

Raw Node.js HTTP server example:

const http = require('http');

const server = http.createServer((req, res) => {
  if (req.method === 'GET' && req.url === '/users') {
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify([{ id: 1, name: 'Satya' }]));
  } else if (req.method === 'GET' && req.url.startsWith('/users/')) {
    const id = req.url.split('/')[2];
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ id, name: 'Satya' }));
  } else if (req.method === 'POST' && req.url === '/users') {
    let body = '';
    req.on('data', chunk => body += chunk);
    req.on('end', () => {
      const user = JSON.parse(body);
      res.writeHead(201, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify(user));
    });
  } else {
    res.writeHead(404);
    res.end('Not found');
  }
});

server.listen(3000);

That works, but as your application grows, the code becomes a mess of if‑else statements, manual body parsing, and repetitive header writing.

Now look at the same logic with Express:

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

app.get('/users', (req, res) => {
  res.json([{ id: 1, name: 'Satya' }]);
});

app.get('/users/:id', (req, res) => {
  const id = req.params.id;
  res.json({ id, name: 'Satya' });
});

app.post('/users', (req, res) => {
  const user = req.body;
  res.status(201).json(user);
});

app.listen(3000);

Here's what Express gives you:

Clean routing: You directly map HTTP methods and URL patterns to handler functions. No need to manually parse req.url or check req.method.
Automatic body parsing: With express.json() middleware, the body is parsed and available at req.body.
Easy response helpers: res.json() automatically sets the content type and stringifies the object.
Route parameters: Express extracts :id from the URL and places it in req.params.
Middleware support: You can chain functions (like we explored in the previous blog) to handle logging, auth, validation.

Express takes away the boilerplate so you can focus on your application logic.

Creating your first Express server

Let's start from zero. First, initialize a project and install Express:

npm init -y
npm install express

Then create a file, say server.js:

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

app.get('/', (req, res) => {
  res.send('Hello from Express!');
});

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

Run it with node server.js, and open http://localhost:3000. You'll see the greeting. This is the absolute minimal Express server.

Handling GET requests

GET requests are used to fetch data. Express makes it very intuitive.

1. Simple GET route

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

2. Using route parameters

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

A request to /users/42 returns User ID: 42. Express automatically parses the :id segment.

3. Query string parameters

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

A request to /search?q=express&page=2 gives { "query": "express", "page": "2" }.

4. Returning JSON data

app.get('/api/users', (req, res) => {
  const users = [
    { id: 1, name: 'Satya' },
    { id: 2, name: 'Priya' }
  ];
  res.json(users); // sets Content-Type to application/json automatically
});

res.json() is the go‑to for API responses.

Handling POST requests

POST requests typically create new resources. To process them, you need to read the request body. Express's built-in middleware express.json() does exactly that.

app.use(express.json()); // parse JSON bodies

app.post('/api/users', (req, res) => {
  const { name, email } = req.body;
  // In a real app, you'd save to a database
  const newUser = { id: Date.now(), name, email };
  res.status(201).json(newUser);
});

Test it with a client that sends JSON:

{
  "name": "Rahul",
  "email": "rahul@example.com"
}

The response will be 201 Created with the new user object.

You can also handle form submissions using express.urlencoded({ extended: true }) if you're dealing with traditional HTML forms.

Sending responses

Express provides multiple methods to send responses, each suitable for different scenarios:

res.send(string) – sends a plain text or HTML string; sets Content-Type accordingly.
res.json(object) – sends a JSON object with proper header.
res.status(code).json(object) – sets the status code and sends JSON.
res.sendFile(path) – streams a file from disk.
res.redirect(url) – redirects to another URL.
res.download(path) – prompts the browser to download a file.

You can also chain status codes: res.status(404).send('Not Found').

Example:

app.get('/file', (req, res) => {
  res.sendFile(__dirname + '/sample.pdf');
});

Express is flexible and doesn't force one way of responding.

Conclusion

Express.js strips away the repetitive plumbing of raw Node.js HTTP servers and lets you define routes declaratively, making your code cleaner and faster to write. With just a few lines, you can set up a server, handle GET and POST requests, parse inputs, and send proper responses. This is the foundation of every Node.js backend I've built.

Let's recap:

Express is a minimal framework that simplifies creating HTTP servers in Node.js.
It offers clean routing with methods like app.get, app.post, app.put, etc.
Route parameters (req.params), query strings (req.query), and body parsing (req.body) are built in.
Response helpers (res.json, res.send, res.status) make sending data back straightforward.
Compared to raw Node, Express eliminates boilerplate and reduces developer friction.

Now that you're comfortable with routes and request handling, the next step is to build more complex applications, connect to databases, and structure larger codebases. We'll continue that journey in the next post.

Hope you found this helpful! If you spot any mistakes or have suggestions, let me know. You can find me on LinkedIn and X, where I post more about web development.

What is Middleware in Express and How It Works

SATYA SOOTAR — Sun, 10 May 2026 13:50:59 +0000

Hello readers 👋, welcome to the 10th blog in our Node.js series!

In the last post, we built a clean REST API using Express.js for a users resource. We defined routes and handled different HTTP methods. Today, we are going to explore a concept that sits quietly at the heart of every Express application: middleware.

If you have ever wanted to log every request, check authentication tokens, or validate incoming data before it hits your route handler, you have needed middleware. Let's understand what middleware is, how it fits into the request lifecycle, the different types, and how to chain multiple middleware to build powerful, reusable pipelines.

Let's get started.

What middleware is in Express

Middleware, in Express, are functions that have access to the request object (req), the response object (res), and the next middleware function in the application's request-response cycle. The next middleware function is conventionally denoted by a variable named next.

Think of middleware as a series of checkpoints or processing stations that every incoming request passes through before reaching the final route handler. At each checkpoint, you can:

Inspect or modify the request (e.g., add properties, parse the body).
Perform some logic (e.g., log the request time, check authentication).
Send an early response (e.g., return an error if the user is not authenticated) and stop the chain.
Call next() to pass control to the next middleware in line.

Middleware functions are executed in the order they are defined. That order is crucial and we'll explore it soon.

Where middleware sits in the request lifecycle

In a typical Express app, an incoming HTTP request flows through a pipeline:

The request arrives at the server.
It passes through each middleware function registered (both application-level and router-level) in the order they were added.
Finally, it reaches the route handler that matches the path and method.
The route handler sends a response.
If no middleware or route sends a response, the request hangs; Express doesn't automatically respond.

The middleware chain can be visualized as:

Request → [Middleware 1] → [Middleware 2] → [Route Handler] → Response

Each arrow is a next() call. If a middleware function does not call next(), the request stalls and never reaches the next middleware or route handler (unless you send a response and end the request). This pipeline concept is the backbone of Express.

The role of `next()`

The next function is a callback that tells Express "I'm done, move on to the next middleware or route handler." If the currently executing middleware function does not end the request-response cycle, it must call next().

There are two important variations:

next() – proceed to the next middleware in the stack.
next('route') – skip to the next route handler (only works in router-level middleware).

If you pass an error to next(err), Express skips all remaining non-error middleware and goes directly to an error-handling middleware, which has four parameters: (err, req, res, next). We'll keep error handling middleware for another post.

Application-level middleware

Application-level middleware are bound to an instance of the app object using app.use() or app.METHOD(). They run for every request (if no path is specified) or for requests that match a specific path prefix.

Example: logging middleware for every request

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

// Application-level middleware (no path, runs on every request)
app.use((req, res, next) => {
  console.log(`${req.method} ${req.url} - ${new Date().toISOString()}`);
  next();
});

Here, we log the HTTP method, URL, and timestamp for every request. We then call next() so the request continues down the pipeline.

Example: middleware for a specific path

You can limit middleware to a path prefix:

app.use('/admin', (req, res, next) => {
  console.log('Admin route accessed');
  next();
});

Middleware added this way will run for any route starting with /admin.

Router-level middleware

Router-level middleware works exactly like application-level middleware, except it is bound to an instance of express.Router(). It's used to organize route-specific middleware, especially when you have modular route files.

const router = express.Router();

// Router-level middleware: runs for every request handled by this router
router.use((req, res, next) => {
  console.log('Inside user router');
  next();
});

router.get('/profile', (req, res) => {
  res.send('User profile');
});

app.use('/users', router);

Now, any request starting with /users will first go through the router-level middleware before hitting the specific route handler.

Built-in middleware

Express has some built-in middleware functions that solve common tasks. You've already seen one: express.json(). These are middleware functions that come with Express and are used via app.use().

express.json() – parses incoming JSON payloads and populates req.body.
express.urlencoded({ extended: true }) – parses URL-encoded payloads (from HTML forms).
express.static('public') – serves static files (images, CSS, JS) from a directory.

Example:

app.use(express.json());
app.use(express.static('public'));

These are middleware too! They process the request and call next() for the next piece in the pipeline.

Execution order of middleware

The order in which you declare middleware matters immensely. Express executes them sequentially, top to bottom. If you place a middleware that sends a response before your route handler, the route handler will never run.

Consider this incorrect example:

app.use((req, res, next) => {
  res.send('This ends the request');
  next(); // This will still be called but no further middleware can modify the response after send
});
app.get('/', (req, res) => {
  res.send('Hello world');
});

Here, the first middleware sends a response, and unless you call next() before send(), the get handler never sees the request. More importantly, even if you call next() after send(), Express will not allow you to send another response; you'd get an error because headers are already sent. So, typically you either call next() without sending a response, or you end the request inside the middleware.

The correct pattern:

app.use((req, res, next) => {
  console.log('Logging');
  next(); // pass control
});

app.use((req, res, next) => {
  // maybe add timestamp to req
  req.requestTime = Date.now();
  next();
});

app.get('/', (req, res) => {
  res.send(`Hello world, request at ${req.requestTime}`);
});

Each middleware adds something and passes control. The route handler runs at the end.

Real-world examples

Let's see three practical middleware: logging, authentication, and request validation.

Logging middleware

You've already seen a basic logger. Let's write a slightly cleaner one:

function logger(req, res, next) {
  const start = Date.now();
  res.on('finish', () => {
    const duration = Date.now() - start;
    console.log(`${req.method} ${req.originalUrl} ${res.statusCode} - ${duration}ms`);
  });
  next();
}
app.use(logger);

This logs the method, URL, status code, and response time. It uses the finish event on the response to know when the response is sent.

Authentication middleware

This one checks for a valid JWT token (similar to our earlier JWT blog). If invalid, it stops the request with a 401 error. Otherwise, it attaches the user and continues.

function authenticate(req, res, next) {
  const authHeader = req.headers['authorization'];
  const token = authHeader && authHeader.split(' ')[1];
  if (!token) {
    return res.status(401).json({ message: 'Access token missing' });
  }
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded;
    next();
  } catch (err) {
    return res.status(403).json({ message: 'Invalid token' });
  }
}
// Protect a route
app.get('/profile', authenticate, (req, res) => {
  res.send(`User profile for ${req.user.userId}`);
});

Notice how the middleware stops the request (by returning a response) when authentication fails, so the route handler never executes.

Request validation middleware

You can validate input before it reaches business logic. This keeps your route handlers clean. Here's a simple one for creating a user:

function validateUserInput(req, res, next) {
  const { name, email } = req.body;
  if (!name || !email) {
    return res.status(400).json({ message: 'Name and email are required' });
  }
  if (typeof email !== 'string' || !email.includes('@')) {
    return res.status(400).json({ message: 'Invalid email' });
  }
  next();
}

app.post('/users', validateUserInput, (req, res) => {
  // create user logic...
});

When validation fails, we respond immediately with 400 Bad Request. Otherwise, next() passes control to the actual handler. This separation improves readability and reusability.

Middleware pipeline

Imagine a physical pipeline with several inspection stations. A request arrives, gets stamped at the logging station, then passes through a security gate (authentication), then a quality check (validation), and finally reaches the desired destination (route handler). At any point, if it fails inspection, it gets turned away with a response.

Conclusion

Middleware is one of those concepts that, once you understand it, Express becomes transparent. It's just a sequence of functions that have access to req and res and can either pass the request along with next() or end the cycle by sending a response. By chaining middleware, you can separate concerns like logging, authentication, and validation, making your code cleaner and more maintainable.

Let's quickly recap:

Middleware functions sit between the incoming request and the final route handler.
They can modify the request/response, run code, or end the request early.
The next() function passes control to the next middleware in the stack; without it, the request stalls.
Application-level middleware (app.use()) runs for all requests or a specific path.
Router-level middleware (router.use()) works for a specific router.
Built-in middleware like express.json() are just prepackaged middleware.
Execution order is top-to-bottom, so declare middleware before routes they should affect.
Real-world uses include logging, authentication, and input validation, which keep route handlers focused.

Now that you understand middleware, you can structure Express apps that are modular, secure, and easy to scale. In the next post, we'll continue building more practical features. See you there!

Hope you found this helpful! If you spot any mistakes or have suggestions, let me know. You can find me on LinkedIn and X, where I post more about web development.

REST API Design Made Simple with Express.js

SATYA SOOTAR — Sat, 09 May 2026 13:18:27 +0000

Hello readers 👋, welcome to the 9th blog in our Node.js series!

In our last post, we learned how JWT authentication keeps your application secure without the need for server-side sessions. Today, we're going to focus on something equally essential: how to design a clean, predictable, and intuitive API using Express.js following REST principles.

Whether you're building a mobile app, a frontend in React, or just exposing data to the world, you'll need an API that clients can understand and use easily. REST gives us a set of conventions that make APIs feel natural. We'll break down what a REST API is, map out HTTP methods, introduce status codes, and design routes for a simple users resource. By the end, you'll be able to structure your own Express.js APIs clearly.

Let's jump right in.

What is a REST API?

First, let's define API. An API (Application Programming Interface) is a set of rules that allows two pieces of software to talk to each other. When you use any app on your phone, it likely talks to a server using an API. The API is the contract between the client and the server: "you send me a request in this format, and I'll give you a response in that format."

REST stands for Representational State Transfer. It's an architectural style that uses the standard HTTP methods (GET, POST, PUT, DELETE) and follows a few guiding principles:

Everything is a resource (like a user, a product, an article).
Each resource is accessed via a unique URL (endpoint), like /users or /users/1.
The client and server are stateless: each request must contain all the information the server needs to process it, and the server doesn't keep any session state between requests.
Operations on resources are performed using the standard HTTP methods.

That's it. No magic, just a disciplined way of using URLs and HTTP verbs.

Resources in REST architecture

A resource is the core concept. In our example, we'll have a users resource. Think of a user as an object that the API can create, read, update, or delete. The endpoints (URLs) for this resource follow a convention:

/users – the collection of users.
/users/:id – a single user identified by a unique ID.

This consistent naming makes APIs intuitive. Even before you read the documentation, you can guess that GET /users returns all users, and GET /users/5 returns user #5.

HTTP methods and what they do

REST maps the basic CRUD operations (Create, Read, Update, Delete) to the following HTTP methods:

HTTP Method	Operation	Example Endpoint	Meaning
GET	Read	`GET /users`	Retrieve all users
GET	Read	`GET /users/1`	Retrieve a single user with ID 1
POST	Create	`POST /users`	Create a new user
PUT	Update (replace)	`PUT /users/1`	Replace the entire user with ID 1
PATCH	Update (partial)	`PATCH /users/1`	Modify only some fields of user 1
DELETE	Delete	`DELETE /users/1`	Remove user with ID 1

We'll focus on the most commonly used: GET, POST, PUT, and DELETE. Think of them as the verbs of your API.

Setting up the Express.js server

Let's quickly spin up a minimal Express server. If you haven't installed Express, run npm install express in your project folder.

const express = require('express');
const app = express();
app.use(express.json()); // to parse JSON request bodies

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

We'll add routes to this server.

Designing routes for the "users" resource

We'll create an in-memory array to hold user objects. Remember, in a real application you'd use a database, but the principles remain the same.

In-memory data store

let users = [
  { id: 1, name: 'Satya', email: 'satya@example.com' },
  { id: 2, name: 'Priya', email: 'priya@example.com' }
];
let nextId = 3; // to assign unique IDs

Now, let's implement each route following REST conventions.

1. GET /users – fetch all users

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

A simple GET request returns the entire users array with status 200 (OK, but it's implied in res.json).

2. GET /users/:id – fetch a single user

app.get('/users/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const user = users.find(u => u.id === id);
  if (!user) {
    return res.status(404).json({ message: 'User not found' });
  }
  res.json(user);
});

Here, :id is a route parameter. If the user doesn't exist, we return a 404 Not Found status code.

3. POST /users – create a new user

app.post('/users', (req, res) => {
  const { name, email } = req.body;
  if (!name || !email) {
    return res.status(400).json({ message: 'Name and email are required' });
  }
  const newUser = { id: nextId++, name, email };
  users.push(newUser);
  res.status(201).json(newUser);
});

A POST request creates a new resource. We send a 201 Created status code, along with the newly created object. We also validate input: if name or email is missing, we respond with 400 Bad Request.

4. PUT /users/:id – replace a user entirely

app.put('/users/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const { name, email } = req.body;
  if (!name || !email) {
    return res.status(400).json({ message: 'Name and email are required' });
  }
  const index = users.findIndex(u => u.id === id);
  if (index === -1) {
    return res.status(404).json({ message: 'User not found' });
  }
  // Replace the entire object
  users[index] = { id, name, email };
  res.json(users[index]);
});

PUT typically expects a complete replacement. If the user doesn't exist, we return 404. On success, we return the updated user with 200.

5. DELETE /users/:id – remove a user

app.delete('/users/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const index = users.findIndex(u => u.id === id);
  if (index === -1) {
    return res.status(404).json({ message: 'User not found' });
  }
  users.splice(index, 1);
  res.status(204).send(); // No Content
});

DELETE successfully returns a 204 No Content status with an empty body, indicating that the operation was successful and there's nothing else to send.

Status codes basics

HTTP status codes tell the client what happened. Here are the basics:

Code	Meaning	When to use
200	OK	Successful GET or PUT request
201	Created	Resource created successfully (POST)
204	No Content	Successful DELETE, nothing to return
400	Bad Request	Client sent invalid data (missing fields, wrong format)
401	Unauthorized	Authentication is missing or has failed
404	Not Found	Requested resource doesn't exist
500	Internal Server Error	Something went wrong on the server side

Always return the appropriate status code so the client can handle the response correctly. It's part of the contract.

The request-response lifecycle

When a client makes a request, here's what happens:

The client sends an HTTP request to a specific endpoint with a method, headers, and optionally a body.
The Express server receives the request and matches it to the defined route.
The route handler reads parameters, query strings, and body; performs business logic; and sends back a response with a status code and data.
The client receives the response and updates its UI or state.

For example, a POST /users with { "name": "Rahul", "email": "rahul@example.com" } triggers the creation of a new user and the 201 response.

Clean route naming conventions

When designing a REST API:

Use plural nouns for collections: /users, /posts, /products. This is conventional and predictable.
Use hierarchical routes for nested resources: /users/1/posts to get posts of user #1. But don't over-nest; keep it flat if possible.
Use query parameters for filtering, sorting, and pagination: GET /users?role=admin&limit=10.
Prefer kebab-case or lowercase: /user-profiles (though many prefer just nouns and sub-resources).

Putting it all together: a complete Express API for users

Here's the full code for a simple, working REST API:

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

let users = [
  { id: 1, name: 'Satya', email: 'satya@example.com' },
  { id: 2, name: 'Priya', email: 'priya@example.com' }
];
let nextId = 3;

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

// GET single user
app.get('/users/:id', (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  if (!user) return res.status(404).json({ message: 'User not found' });
  res.json(user);
});

// POST create user
app.post('/users', (req, res) => {
  const { name, email } = req.body;
  if (!name || !email) return res.status(400).json({ message: 'Name and email required' });
  const newUser = { id: nextId++, name, email };
  users.push(newUser);
  res.status(201).json(newUser);
});

// PUT replace user
app.put('/users/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const { name, email } = req.body;
  if (!name || !email) return res.status(400).json({ message: 'Name and email required' });
  const index = users.findIndex(u => u.id === id);
  if (index === -1) return res.status(404).json({ message: 'User not found' });
  users[index] = { id, name, email };
  res.json(users[index]);
});

// DELETE user
app.delete('/users/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const index = users.findIndex(u => u.id === id);
  if (index === -1) return res.status(404).json({ message: 'User not found' });
  users.splice(index, 1);
  res.status(204).send();
});

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

You can test these endpoints with Postman, curl, or your browser (for GET requests). The API is self-descriptive and follows REST conventions.

Here's a quick reference table:

CRUD Operation	HTTP Method	Endpoint	Example
Create	POST	`/users`	`POST /users` (with body)
Read (all)	GET	`/users`	`GET /users`
Read (one)	GET	`/users/:id`	`GET /users/1`
Update	PUT	`/users/:id`	`PUT /users/1` (with body)
Delete	DELETE	`/users/:id`	`DELETE /users/1`

Conclusion

A well-designed REST API makes your backend predictable and easy for any client to consume. Using Express.js, you can quickly map HTTP methods to resource actions, keep your routes clean, and respond with proper status codes. This forms the foundation of any full-stack application.

To recap the key points:

A REST API uses standard HTTP methods to perform operations on resources identified by URLs.
Resources are nouns; endpoints like /users represent collections, and /users/:id represent individual items.
GET retrieves data, POST creates, PUT replaces, and DELETE removes resources.
Status codes (200, 201, 204, 400, 404, etc.) communicate the result clearly.
Clean route naming and appropriate status codes make your API intuitive and easy to maintain.
Express.js provides a minimal and flexible way to build such APIs.

Now you're equipped to design your own RESTful APIs from scratch. In the next blog, we'll continue building on this foundation, perhaps adding real database storage or authentication to protect routes. See you there!

Hope you found this helpful! If you spot any mistakes or have suggestions, let me know. You can find me on LinkedIn and X, where I post more about web development.

JWT Authentication in Node.js Explained Simply

SATYA SOOTAR — Sat, 09 May 2026 13:11:39 +0000

Hello readers 👋, welcome to the 8th blog of our Node.js journey!

So far, we've covered how Node.js works under the hood, its event loop, non-blocking code, and how to handle async operations. Now we're going to build something practical that almost every real-world application needs: user authentication using JSON Web Tokens (JWT).

Authentication is how an application knows who you are. You see it every day: logging into a website, accessing private messages, or making a purchase. Today, we'll understand what JWT is, how it works (without diving into complex cryptography), and how to implement a simple, secure login flow in Node.js.

Let's get started.

What authentication means

Authentication is the process of verifying a user's identity. When you log in with a username and password, the server checks those credentials and, if they match, it should remember that you are authenticated for subsequent requests. Without authentication, anyone could pretend to be anyone, and there would be no security.

In traditional web applications, once logged in, the server creates a session and stores it in memory or a database. The client gets a session ID stored in a cookie. Each request sends that cookie, and the server looks up the session. This works, but it's stateful: the server must store session data, which can be a scalability bottleneck if you have multiple servers.

JWT offers a stateless approach. The server doesn't need to remember anything. Instead, after a successful login, the server creates a token that contains user information and signs it. The client stores this token and sends it with every request. The server simply verifies the signature and reads the user data directly from the token. No database lookups for sessions. This makes scaling much easier.

What JWT is

JWT stands for JSON Web Token. It's an open standard (RFC 7519) that defines a compact, self-contained way to transmit information between parties as a JSON object. The information can be trusted because it's digitally signed.

JWT is perfect for authentication. After a user logs in, the server generates a JWT containing their user ID (and maybe role) and sends it to the client. The client sends the token in the Authorization header of every subsequent request. The server checks the signature and extracts the user ID, thus identifying the user without a database session lookup.

Because the token itself contains the user information, it's self-contained. That's the "stateless" magic.

Structure of a JWT

A JWT looks like a long random string of characters with two dots:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInJvbGUiOiJhZG1pbiJ9.4x9MMbKd7P3qW7Y8lQZ2VcDhFfR1jNzOyU5wTkXy

This string is actually three parts, each Base64URL-encoded, separated by dots. Let's decode each part conceptually (not deep crypto, just the idea).

Header

The first part is the header. It typically contains two fields: the type of token (JWT) and the signing algorithm used (HS256 or RS256). After Base64 decoding, it looks like:

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

Payload

The second part is the payload. This is where the actual data (claims) about the user lives. The server puts information like user ID, username, role, and expiration time here. For example:

{
  "userId": 1,
  "username": "satya",
  "role": "admin",
  "iat": 1680000000,
  "exp": 1680003600
}

The iat (issued at) and exp (expiration) claims are standard. You can add custom data too. Remember: the payload is not encrypted, just Base64-encoded. Anyone can decode it, so never put sensitive info like passwords in it.

Signature

The third part is the signature. This is what makes the token trustworthy. To create the signature, the server takes the encoded header, the encoded payload, and a secret key, then applies the algorithm specified in the header (e.g., HMAC SHA256). The result is a cryptographic hash that ensures the token hasn't been tampered with.

If a malicious user tries to change the payload (e.g., change userId from 1 to 2), the signature will no longer match when the server recalculates it using the secret key. The server detects tampering and rejects the token. That's the core security.

Login flow using JWT

Let's walk through a typical login flow step by step, with code snippets using Node.js, the express web framework (for routing convenience), and the jsonwebtoken library.

1. Install required packages:

npm install express jsonwebtoken

2. Create a simple server with a login endpoint.

const express = require('express');
const jwt = require('jsonwebtoken');

const app = express();
app.use(express.json()); // to parse JSON request body

const SECRET_KEY = 'your-secret-key-change-this'; // in production, use an env var

// In-memory user store (for demo)
const users = [
  { id: 1, username: 'satya', password: 'password123', role: 'admin' }
];

app.post('/login', (req, res) => {
  const { username, password } = req.body;
  const user = users.find(u => u.username === username && u.password === password);
  if (!user) {
    return res.status(401).json({ message: 'Invalid credentials' });
  }

  // Create a token. The payload includes the user's id and role.
  // Don't include the password!
  const token = jwt.sign(
    { userId: user.id, role: user.role },
    SECRET_KEY,
    { expiresIn: '1h' } // token expires in 1 hour
  );
  res.json({ token });
});

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

What's happening here:

We receive username and password.
We check against a hardcoded list (in reality, you'd check a database with hashed passwords).
If valid, we use jwt.sign() to create a token with a payload containing the user ID and role. The token is signed with our secret key and set to expire in 1 hour.
We send the token back to the client as JSON.

3. Client stores the token and sends it with requests.

After login, the client (browser or mobile app) stores the token. In a web app, you might use localStorage or a secure HTTP-only cookie. For simplicity, we'll use the Authorization header with the Bearer scheme.

A subsequent request to a protected route would include the header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Protecting routes using tokens

Now we need to protect certain API routes so that only authenticated users can access them. We'll create a middleware that checks the token.

// Middleware to verify JWT
function authenticateToken(req, res, next) {
  const authHeader = req.headers['authorization'];
  const token = authHeader && authHeader.split(' ')[1]; // Bearer TOKEN
  if (!token) {
    return res.status(401).json({ message: 'Access token missing' });
  }

  jwt.verify(token, SECRET_KEY, (err, decoded) => {
    if (err) {
      return res.status(403).json({ message: 'Invalid or expired token' });
    }
    // decoded contains the payload, e.g., { userId: 1, role: 'admin', iat: ..., exp: ... }
    req.user = decoded;
    next(); // proceed to the next middleware/route handler
  });
}

Then we can protect any route by adding this middleware:

app.get('/profile', authenticateToken, (req, res) => {
  // req.user is available from the token
  res.json({ message: `Hello user ${req.user.userId}, your role is ${req.user.role}` });
});

app.get('/admin', authenticateToken, (req, res) => {
  if (req.user.role !== 'admin') {
    return res.status(403).json({ message: 'Admin access required' });
  }
  res.json({ message: 'Welcome to admin panel' });
});

How it works:

The client sends a request to /profile with the token.
The authenticateToken middleware extracts the token, calls jwt.verify() with the secret key.
If valid, it attaches the decoded payload to req.user and passes control to the actual route handler.
The handler can use req.user.userId or any custom claim.
If the token is invalid (bad signature, expired), the middleware sends a 403 response.

Sending token with requests: from client side

In a Node.js client (or frontend JS), you'd include the token after login:

// After login, store token
const tokenResponse = await fetch('/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ username: 'satya', password: 'password123' })
});
const { token } = await tokenResponse.json();
// Store token (e.g., in localStorage)
localStorage.setItem('token', token);

// Later, for protected requests:
const token = localStorage.getItem('token');
const profileResponse = await fetch('/profile', {
  headers: { 'Authorization': `Bearer ${token}` }
});

In a pure HTTP context (like Postman), you'd manually set the header.

The token validation lifecycle

From the moment the server issues a token to its eventual expiry or logout, the lifecycle is:

Issuance: Server creates and signs token on successful login.
Storage: Client stores token (memory, localStorage, cookie).
Transmission: Client sends token in Authorization header with each request.
Verification: Server middleware verifies signature and expiration. If valid, request proceeds; if invalid, 403.
Expiration: After the exp claim time, the token is rejected even if the signature is correct. This forces the user to re-login.
Logout (optional): Since JWTs are stateless, there's no server-side invalidation. To "logout", you simply remove the token from the client. For added security, you can maintain a token blacklist (stateful), but the stateless beauty is lost.

Visualizing the flow

JWT login authentication flow:

A note on security

Always use HTTPS: JWTs are transmitted in headers; without TLS, an attacker could steal the token.
Keep the secret key secret: Store it in environment variables, never in code.
Set a short expiration time: 15 minutes to 1 hour is typical. Use refresh tokens for longer sessions (beyond this article).
Don't put sensitive data in the payload: It's only Base64-encoded, not encrypted.
Consider token storage: localStorage is vulnerable to XSS attacks; HttpOnly cookies are more secure but require CSRF protection. The best approach depends on your application.

Conclusion

JWT authentication is a clean, stateless way to secure Node.js APIs. It eliminates server-side session storage, simplifies scaling, and gives you a self-contained token that carries user identity. By understanding the header, payload, and signature, you now know exactly why JWTs are secure and how to implement the full login and route protection flow.

Let's quickly recap:

Authentication verifies identity; JWT provides a stateless method by issuing a signed token.
A JWT consists of three Base64-encoded parts: header (algorithm), payload (user data), and signature (tamper-proof).
The login endpoint validates credentials and returns a JWT made with jsonwebtoken.sign().
The client sends the token in the Authorization: Bearer <token> header for subsequent requests.
Middleware verifies the token with jwt.verify(), extracts the user payload, and protects routes.
This flow is scalable, simple, and widely adopted.

With JWT authentication in your toolbox, you can now build secure, stateless Node.js backends. In the next post, we'll continue building practical features. See you then!

Hope you found this helpful! If you spot any mistakes or have suggestions, let me know. You can find me on LinkedIn and X, where I post more about web development.

Async Code in Node.js: Callbacks and Promises

SATYA SOOTAR — Sat, 09 May 2026 12:58:26 +0000

Hello readers 👋, welcome to the 7th of our Node.js journey!

Last time, we explored how a single-threaded Node.js process magically handles thousands of requests at once. We saw that non-blocking I/O is the secret, and the event loop keeps everything spinning. But we left one critical question unanswered: how do we actually write the code that starts an async operation and then does something with the result?

Today, we are going to dive into the two most fundamental ways to handle asynchronous code in Node.js: callbacks and promises. We'll see how callbacks work, why they can become messy, and how promises rescue us with cleaner, more readable code.

Let's get into it.

Why async code exists in Node.js

We already know that Node.js uses a non-blocking model. When you call something like fs.readFile, you don't wait for the file to be fully loaded. Instead, you pass a function (a callback) that the event loop will run later, once the file content is ready.

This pattern allows the main thread to stay responsive. But it also means you cannot simply write:

const data = readFile("file.txt");
console.log(data);

Because that would either block the thread (if the function is synchronous) or give you undefined (if it's asynchronous and returns immediately). You need a way to tell Node.js: "Here's what I want you to do, and here's the function to call when you're done."

That's the heart of async code: scheduling a future action.

Callback-based async execution

A callback is simply a function passed as an argument to another function. The outer function performs an operation and then, when the operation finishes, it "calls back" the inner function with the result.

In Node.js, many core modules follow a callback convention: the callback is the last argument, and the first parameter of the callback is an error object (if any), followed by the data. This is often called an error-first callback.

Let's start with a concrete file reading example:

const fs = require("fs");

console.log("Start reading file...");

fs.readFile("example.txt", "utf8", (err, data) => {
  if (err) {
    console.error("Failed to read file:", err.message);
    return;
  }
  console.log("File content:", data);
});

console.log("This runs before the file content is logged.");

The output:

Start reading file...
This runs before the file content is logged.
File content: (the actual content)

Step by step, here's how the callback flow works:

fs.readFile is called with the filename, encoding, and a callback function. Node.js hands the file read operation to the OS (or the libuv thread pool).
fs.readFile returns immediately. The main thread moves to the next line: console.log("This runs before...").
Sometime later, the file read completes. The callback is placed into the event loop's task queue.
When the call stack is empty, the event loop picks up the callback and executes it on the main thread.
Inside the callback, we check for errors first. If there's an error, we handle it; otherwise, we use the data.

This pattern works, and it's the core of many Node.js applications. But it has a well-known downside.

Problems with nested callbacks (callback hell)

Real applications rarely do just one async operation. Often, one operation depends on the result of another. For example: read a configuration file, then connect to a database, then fetch a user by ID, then load the user's orders.

With callbacks, each step nests inside the previous one. This leads to the infamous "pyramid of doom" or "callback hell":

fs.readFile("config.json", "utf8", (err, config) => {
  if (err) handleError(err);
  else {
    connectDB(config.dbUrl, (err, db) => {
      if (err) handleError(err);
      else {
        db.findUser("satya", (err, user) => {
          if (err) handleError(err);
          else {
            user.loadOrders((err, orders) => {
              if (err) handleError(err);
              else {
                console.log(orders);
              }
            });
          }
        });
      }
    });
  }
});

The problems are clear:

The code indents deeper and deeper, making it hard to read.
Error handling is repetitive and scattered across each callback.
Adding another step to the chain means adding another level of indentation.
The flow of logic is buried under syntax noise.

This style of code is brittle and difficult to maintain. It's especially painful when you need to coordinate multiple independent async operations.

Promise-based async handling

Promises were introduced to flatten this pyramid. A promise is an object that represents the eventual result of an asynchronous operation. It can be in one of three states: pending, fulfilled, or rejected. Once settled, it never changes.

Node.js core modules now provide promise-based alternatives. For the file system, you can use fs.promises (added in Node.js 10). For older modules, you can use util.promisify to convert callback-based functions into promise-returning ones.

Let's rewrite the file reading example using promises:

const fs = require("fs").promises;

console.log("Start reading file...");

fs.readFile("example.txt", "utf8")
  .then((data) => {
    console.log("File content:", data);
  })
  .catch((err) => {
    console.error("Failed to read file:", err.message);
  });

console.log("This runs before the file content is logged.");

The output is identical in order, but the structure is different. We call fs.readFile, which returns a promise. We then attach a .then() for the success case and a .catch() for errors. The promise handles the scheduling internally; we just react to the result.

How promises improve the chain

The real power becomes evident when we have multiple sequential operations. Because .then() itself always returns a new promise, we can chain further .then() calls without nesting. Error handling with .catch() works for the entire chain.

Let's reimagine the nested callback scenario with promises:

const fs = require("fs").promises;

function connectDB(config) { /* returns a promise */ }
function findUser(db, name) { /* returns a promise */ }
function loadOrders(user) { /* returns a promise */ }

fs.readFile("config.json", "utf8")
  .then(config => connectDB(JSON.parse(config).dbUrl))
  .then(db => findUser(db, "satya"))
  .then(user => loadOrders(user))
  .then(orders => console.log(orders))
  .catch(err => console.error("Something failed:", err.message));

Notice the difference:

Every operation is at the same indentation level.
The code reads top to bottom, matching the natural sequence.
A single .catch() at the end handles errors from any step in the chain.
You can easily insert a new step by adding another .then() without altering existing logic.

This flat, readable flow is the primary reason promises became the standard for async code.

Benefits of promises beyond readability

Promises offer more than just a clean syntax:

Reliable error propagation: If any .then() throws an error or returns a rejected promise, the error cascades down to the nearest .catch(). No more forgotten error checks in every callback.
Composability: You can run multiple promises in parallel using Promise.all, race them with Promise.race, or wait for all settled with Promise.allSettled. This is cumbersome with raw callbacks.
Return a value and move on: In a .then(), you can return a plain value (which becomes the resolved value of the next promise) or return another promise (the chain will wait for it). This allows dynamic decision making without extra nesting.
Unified interface: Any async operation can be wrapped in a promise, providing a consistent .then/.catch pattern across different modules and libraries.

Visualizing the difference: callback vs promise flow

Callback chain (conceptual):

readFile
 └─ callback(err, config)
      └─ connectDB(config)
           └─ callback(err, db)
                └─ findUser(db, name)
                     └─ callback(err, user)
                          └─ loadOrders(user)
                               └─ callback(err, orders)

Each step is physically nested inside the previous one.

Promise chain:

readFile
  .then(config) -> connectDB
                  .then(db) -> findUser
                                .then(user) -> loadOrders
                                                .then(orders) -> console.log
                                                .catch(handleError)

Each step is a link in a linear chain, with a single error exit point.

A gentle note: what about async/await?

You might have heard about async/await, which makes asynchronous code look even more synchronous. In our next post, we'll explore how async/await is just syntactic sugar over promises, and how it takes readability to an even higher level. For now, mastering promises is essential because async/await relies on them completely.

Conclusion

Asynchronous code in Node.js is unavoidable, but it doesn't have to be painful. Callbacks are the low-level foundation, but they can lead to messy, deeply nested code. Promises provide a clean, chainable, and more manageable way to handle asynchronous operations.

Let's recap what we covered:

Async code exists because Node.js performs non-blocking I/O, and we need a way to handle the results after they arrive.
Callbacks are functions passed to async operations and invoked upon completion, following an error-first convention.
Nested callbacks create the pyramid of doom, making code hard to read and maintain, with repetitive error handling.
Promises represent a future value and offer a flat .then/.catch pattern that drastically improves readability and simplifies error handling.
Promise chaining allows sequential async steps without nesting, and promises can be composed with Promise.all and others.
Understanding promises is the gateway to modern Node.js asynchronous patterns, including async/await.

With promises in your toolkit, you're ready to write cleaner, more robust Node.js code. Next time, we'll take the final step and see how async/await makes async code feel like synchronous code while keeping all the non-blocking benefits.

Hope you found this helpful! If you spot any mistakes or have suggestions, let me know. You can find me on LinkedIn and X, where I post more about web development.

How Node.js Handles Multiple Requests with a Single Thread

SATYA SOOTAR — Sat, 09 May 2026 12:53:42 +0000

Hello readers 👋, welcome to the 6th blog of our Node.js journey!

In the last post, we explored the crucial difference between blocking and non-blocking code. We saw that a single blocking call can freeze an entire server, while non-blocking code keeps it responsive. Today, we tackle the question that naturally follows: if Node.js runs JavaScript on just one thread, how on earth does it handle thousands of requests at the same time without falling apart?

It sounds impossible. A single checkout line in a supermarket can only process one customer at a time. Yet Node.js servers routinely manage tens of thousands of concurrent connections. The answer lies in a brilliant combination of the event loop, non-blocking I/O, and background workers. Let's break it down.

The single-threaded nature of Node.js

First, let's be clear: Node.js executes your JavaScript code in a single main thread. That means when you write:

console.log("Step 1");
console.log("Step 2");

These two lines never run simultaneously. Step 1 finishes before Step 2 starts. This single-threaded design simplifies your code because you don't have to worry about two pieces of code modifying the same variable at the same time.

But a traditional server that uses one thread per request (like many Java or PHP setups) would quickly run out of threads under high load. Each thread consumes memory, and context switching between hundreds of threads wastes CPU. Node.js takes a totally different path. It keeps the single thread but never lets it sit idle.

The magic comes from how it delegates work outside that thread. The main thread is like a project manager who never does heavy lifting; they hand tasks off to specialists and only get involved when results are ready.

The event loop: the master coordinator

The event loop is the core mechanism that enables this pattern. It's a continuously running loop that watches two things: the call stack (where functions execute) and the task queue (where callbacks wait). When the stack is empty, the loop picks the next callback from the queue and pushes it onto the stack for execution.

Think of the event loop as a restaurant's head chef. She can only cook one dish at a time (single thread). But she doesn't peel potatoes or wait for water to boil. She delegates those tasks to assistants (background workers). While they work, she moves on to the next order. When an assistant finishes, they call out "Done!" and the chef briefly pauses, plates the component, and continues.

In Node.js, this "delegation" happens whenever you call an asynchronous function like fs.readFile, http.get, or a database query. The main thread dispatches the I/O operation, registers a callback, and moves on to process the next request immediately.

Delegating tasks to background workers

Where does the actual I/O happen? Node.js uses two main mechanisms:

Operating system kernel: For network I/O, the OS provides non-blocking system calls (like epoll on Linux, kqueue on macOS). The main thread registers a socket with the kernel and asks to be notified when data arrives. The kernel handles the waiting, and the main thread carries on with other work. When data is ready, a callback is queued.
The libuv thread pool: For operations that don't have non-blocking OS support (like file system calls or some DNS lookups), libuv, the library that powers the event loop, maintains a pool of background threads. When you call fs.readFile, libuv grabs a thread from the pool, reads the file content on that thread, and then, once done, pushes the callback into the event loop's queue to be executed on the main thread.

In both cases, the main thread never blocks. It just schedules work and handles results. The heavy I/O happens elsewhere.

Handling multiple client requests: a step-by-step view

Imagine a Node.js HTTP server that logs the request, then responds after a short delay (simulating a database lookup). Here's the code:

const http = require("http");

http.createServer((req, res) => {
  console.log("Request received:", req.url);
  setTimeout(() => {
    res.writeHead(200, { "Content-Type": "text/plain" });
    res.end("Response for " + req.url);
    console.log("Response sent:", req.url);
  }, 100);
}).listen(3000, () => {
  console.log("Server running on port 3000");
});

Now, open three tabs and quickly hit the server with different URLs. If Node.js were single-threaded in a blocking way, each request would need to finish before the next one even starts. But what actually happens is:

Request A arrives. The main thread logs "Request received: /a" and calls setTimeout. This schedules a timer in libuv and immediately returns.
The main thread is free. Request B arrives instantly. It logs "Request received: /b", sets another timer, and returns.
Request C arrives, logs, sets a timer.
After about 100ms, the timers start firing. Libuv queues the callbacks. The event loop picks them up one by one, and the main thread sends responses: "Response sent: /a", then "Response sent: /b", then "Response sent: /c".

All three requests were accepted and processed concurrently, using a single JavaScript thread that never waited for the 100ms delay. The 100ms was spent in the background, not on the main thread.

This is concurrency without parallelism.

Why Node.js scales so well

The secret to Node.js's scalability is that it doesn't dedicate a thread to each connection. In a traditional threaded server, if you have 10,000 concurrent connections, you might have 10,000 threads. Each thread consumes roughly 1 MB of stack space, so that's 10 GB of memory just for thread stacks. Plus, the OS scheduler wastes CPU switching among them.

In Node.js, the memory footprint per connection is minimal: a small amount of state to remember the request, and a callback function. The event loop efficiently manages all of them on a single thread. This allows a Node.js process to comfortably handle tens of thousands of open connections (like WebSocket sessions) on modest hardware.

Moreover, the event loop model naturally matches I/O heavy workloads. Most web servers spend the majority of their time waiting for the database, filesystem, or external APIs. Node.js turns that waiting into an opportunity to serve other requests.

Concurrency vs parallelism: a crucial distinction

It's vital to understand that Node.js provides concurrency, not parallelism, within a single process.

Concurrency: Multiple tasks are in progress at the same time, but not necessarily executing simultaneously. The single thread switches between them so fast that it looks like they run together.
Parallelism: Multiple tasks literally run at the same instant on different CPU cores.

Node.js is concurrent through the event loop. But you can achieve parallelism by running multiple Node.js processes (clustering) or using worker threads for CPU-intensive tasks. However, the default model, and the one we're discussing, is single-threaded concurrency.

The head chef analogy makes this clear. The chef is concurrent: she manages several dishes at once, keeping them all moving forward. But she only has two hands; she cannot physically chop and stir at the same instant. She is not parallel. If she needs to chop fifty onions (a CPU-heavy task), she would block the whole kitchen. So she hires an assistant (a worker thread) to do that in parallel. For most server tasks (I/O), the assistants are already built in (the OS and libuv).

Visualizing the single thread handling multiple requests

Here's a mental picture of the flow:

Time 0ms:   Request A arrives → main thread logs, starts async I/O, moves on
Time 1ms:   Request B arrives → main thread logs, starts async I/O, moves on
Time 2ms:   Request C arrives → main thread logs, starts async I/O, moves on
...
Time 100ms: I/O for Request A completes → callback queued
            I/O for Request B completes → callback queued
Time 101ms: Event loop picks A's callback → main thread sends response A
Time 102ms: Event loop picks B's callback → main thread sends response B
...

The main thread was blocked for only a tiny fraction of the total time (the logging and response sending). The actual waiting happened in the background, concurrently, for all requests.

Conclusion

Node.js handles multiple requests with a single thread by never waiting. It delegates I/O tasks to the OS kernel or a background thread pool, uses an event loop to manage callbacks, and keeps its main thread free to accept new work. This is a radical departure from the thread-per-connection model and is the reason Node.js excels at building fast, scalable network applications.

To recap:

Node.js JavaScript runs on one thread, ensuring simplicity and avoiding synchronization bugs.
The event loop orchestrates concurrency by continuously dispatching callbacks when the stack is empty.
Time-consuming I/O is handed off to the OS (non-blocking) or to a libuv thread pool, never blocking the main thread.
Multiple client requests are handled by interleaving their short, non-blocking pieces, giving the illusion of simultaneous processing.
This model scales well because memory per connection is tiny, and CPU time isn't wasted on thread management.
Node.js provides concurrency, not parallelism, on a single process. For true parallel computation, you can use clustering or worker threads.

Now that you understand this foundational concept, you're ready to build applications that can handle massive concurrency with ease. In the next post, we'll explore some of the most commonly used built-in modules that Node.js provides to make all this power accessible.

Hope you found this helpful! If you spot any mistakes or have suggestions, let me know. You can find me on LinkedIn and X, where I post more about web development.

Blocking vs Non-Blocking Code in Node.js

SATYA SOOTAR — Sat, 09 May 2026 12:50:09 +0000

Hello readers 👋, welcome to the 5th blog of our Node.js Series!

In the last post, we unpacked the event loop and saw how it keeps Node.js responsive by juggling callbacks. Today we are going to look at a concept that directly affects performance: blocking vs non-blocking code. Understanding this difference is the key to writing fast, scalable Node.js applications. It's not just academic; it shows up every time you read a file or query a database.

We'll start with simple definitions, use everyday analogies, and then look at real Node.js examples that show exactly how blocking code can bring a server to its knees while non-blocking code lets it fly.

What blocking code means

Blocking code is code that stops the execution of the rest of your program until a particular operation finishes. When the main thread encounters a blocking operation, it sits there and waits. Nothing else happens during that wait: no new requests are processed, no timers fire, no callbacks run. The entire Node.js process is frozen until that operation completes.

In synchronous programming, blocking is the default. For example, consider this synchronous file read:

const fs = require("fs");

console.log("Start reading file");
const data = fs.readFileSync("big-file.txt", "utf8");
console.log("File content length:", data.length);
console.log("This runs after the file is read");

The output is predictable:

Start reading file
File content length: 12345
This runs after the file is read

The second console.log does not execute until the file is completely read into data. While the file is being read (maybe 50ms or more), the thread is blocked. In a script that does one thing, that's fine. But in a server handling hundreds of requests, it's a disaster.

What non-blocking code means

Non-blocking code, as we saw with the event loop, initiates an operation and then immediately moves on to the next line without waiting for the operation to finish. A callback, a promise, or an await expression later handles the result, but the main thread is never stuck.

The asynchronous version of the file read looks like this:

const fs = require("fs");

console.log("Start reading file");
fs.readFile("big-file.txt", "utf8", (err, data) => {
  if (err) throw err;
  console.log("File content length:", data.length);
});
console.log("This runs immediately, before the file is read");

The output order is:

Start reading file
This runs immediately, before the file is read
File content length: 12345

The main thread registers the read operation, attaches a callback, and keeps going. It never waits. When the data is ready, the event loop pushes the callback onto the stack, and the file content length is logged.

An analogy: waiting in line vs taking a buzzer

Imagine a busy food truck. There are two ways orders can be handled:

Blocking (synchronous): You place your order, and then you stand at the counter, waiting until the cook finishes your meal. The line behind you doesn't move. Only one person can be "in service" at a time. If the cook takes 3 minutes per order, 20 people will take an hour, and most of that time is spent staring at the cook.

Non-blocking (asynchronous): You place your order, pay, and receive a buzzer. You step aside and let the next person order. When your food is ready, the buzzer beeps, and you pick it up. The food truck can take orders from many people rapidly, and the cook works in parallel, while the cashier (the main thread) never gets stuck.

Blocking code is standing at the counter. Non-blocking code is taking the buzzer. In a server, every blocked request is a person stuck at the counter, and the whole queue grinds to a halt.

Why blocking slows servers

Node.js shines when it's non-blocking because its single thread can handle many concurrent connections. But if you introduce a blocking operation, that single thread is completely occupied for the duration of that operation. While it's blocked, zero other work gets done. Timers don't fire. Incoming HTTP requests wait. The entire server freezes.

Let's see a tiny HTTP server with a blocking call:

const http = require("http");
const fs = require("fs");

http.createServer((req, res) => {
  if (req.url === "/slow") {
    // Blocking file read
    const data = fs.readFileSync("huge-file.txt", "utf8");
    res.writeHead(200, { "Content-Type": "text/plain" });
    res.end("File size: " + data.length);
  } else {
    res.writeHead(200, { "Content-Type": "text/plain" });
    res.end("Fast response");
  }
}).listen(3000, () => {
  console.log("Server running at http://localhost:3000");
});

If you open /slow in your browser, it will take a few hundred milliseconds (depending on file size). During that time, if you open a new tab and hit the root /, you'll get no response until the /slow request finishes. The second request is sitting in the queue, waiting for the event loop, which is stuck in readFileSync. The whole server experiences a pause.

Now replace readFileSync with fs.readFile (asynchronous):

http.createServer((req, res) => {
  if (req.url === "/slow") {
    fs.readFile("huge-file.txt", "utf8", (err, data) => {
      if (err) {
        res.writeHead(500);
        return res.end("Error");
      }
      res.writeHead(200, { "Content-Type": "text/plain" });
      res.end("File size: " + data.length);
    });
  } else {
    res.writeHead(200, { "Content-Type": "text/plain" });
    res.end("Fast response");
  }
}).listen(3000);

Now, hitting /slow still takes time to read the file, but the server is not blocked. Requests to / get immediate responses, even while the file is being read in the background. The event loop continues to spin, serving other clients.

Real-world examples: file operations and database calls

Blocking isn't limited to fs.readFileSync. Any synchronous I/O or CPU-heavy work that hangs on the main thread is blocking. Real-world culprits include:

Synchronous file operations: fs.readFileSync, fs.writeFileSync, fs.existsSync.
CPU-intensive computations: huge loops, cryptography, image processing done on the main thread.
Synchronous database queries: some database drivers offer sync methods (like db.execSync()), though most Node.js drivers are async by default.

For databases, a typical non-blocking call uses callbacks, promises, or async/await. For example, with a MySQL driver:

// Non-blocking (callback-based)
connection.query("SELECT * FROM users", (err, results) => {
  if (err) throw err;
  console.log(results);
});

// The line below runs immediately after the query is sent, not after it returns
console.log("Query sent");

Using async/await (still non-blocking):

async function getUsers() {
  const [rows] = await connection.promise().query("SELECT * FROM users");
  console.log(rows);
}
// The function suspends at await, but the main thread is free to handle other requests.

Note: await looks synchronous, but under the hood it's non-blocking. It pauses the async function, not the entire thread. That's the beauty.

How to keep your Node.js code non-blocking

Prefer asynchronous versions of modules: fs.readFile over fs.readFileSync, crypto.pbkdf2 over crypto.pbkdf2Sync.
For CPU-heavy tasks, use worker threads or offload: Node.js provides worker_threads for parallelism, or you can spawn child processes, use message queues, or delegate to external services. Don't do heavy math on the main event loop.
Be careful with large synchronous loops: Even a simple loop over a million items can block the thread for a noticeable time. Split work into chunks and yield control with setImmediate or setTimeout if needed.
Use async/await with Promises, not sync variants: Always check if a library offers a promise-based API and use it.

Conclusion

Understanding blocking vs non-blocking code is foundational for building performant Node.js applications. The main thread is a precious resource; keep it moving. If you block it, your whole server stops. If you keep things async, the event loop can handle vast numbers of concurrent connections effortlessly.

Let's quickly recap:

Blocking code stops the execution of the entire program until the current operation finishes. It freezes the single thread.
Non-blocking code initiates an operation and immediately proceeds, handling the result later via callbacks, promises, or async/await.
Blocking the main thread in a server causes all other requests to queue up and wait, destroying responsiveness.
Real-world blocking sources include synchronous file I/O, heavy computation, and synchronous database calls.
Use asynchronous methods, worker threads for CPU work, and always think about the event loop.

Now that you can distinguish between blocking and non-blocking patterns, you are equipped to write Node.js code that is fast and responsive under load. In the next post, we'll explore the built-in global objects and utilities that Node.js offers to make development smoother.

Hope you found this helpful! If you spot any mistakes or have suggestions, let me know. You can find me on LinkedIn and X, where I post more about web development.

The Node.js Event Loop Explained

SATYA SOOTAR — Sat, 09 May 2026 12:45:37 +0000

Hello readers 👋, welcome to the 4th blog in our Node.js journey!

In the last few posts, we installed Node.js, explored what it is, and uncovered why it's so fast for web applications. We kept mentioning the event loop as the secret sauce behind Node.js's non-blocking superpower. Today, we are going to shine a light directly on it and understand what the event loop actually does, how it manages async operations, and why it makes Node.js incredibly scalable.

Think of this as meeting the conductor of the orchestra. Let's get started.

The single-threaded reality

Before we dive into the event loop, we need a clear reminder: Node.js runs your JavaScript code on a single thread. That means only one piece of JavaScript can execute at any given moment. This might sound like a limitation, but Node.js turns it into a strength by never letting that single thread sit idle while waiting for something to finish.

In a traditional server, we saw that waiting (blocking) ties up a thread. If you have only one thread and it blocks, your entire application freezes. So, how does Node.js keep things moving? It uses the event loop to stay busy with ready tasks while I/O operations happen in the background.

What the event loop is

At its core, the event loop is a task manager that continuously checks if there is any work to do and executes it. It follows a simple, never-ending cycle: check for pending tasks, pick the next one, run it, repeat.

In Node.js, almost everything is delegated to the operating system's asynchronous capabilities through the libuv library. When you initiate an I/O operation (like reading a file, making a network request, or waiting for a timer), Node.js hands it off, registers a callback, and moves on. The event loop's job is to bring those callbacks back to the main thread at the right time.

You can imagine the event loop as a conveyor belt. Your JavaScript code places orders (I/O requests) onto the belt, each with a callback attached. Workers in the background (the operating system kernel or a thread pool) process these orders. When a job completes, the callback is placed into a task queue. The event loop constantly watches this queue; whenever the main thread is free (the call stack is empty), it grabs the next callback from the queue and pushes it onto the call stack for execution.

Call stack and task queue: the dynamic duo

To understand the event loop, we need two concepts: the call stack and the task queue.

Call stack: a LIFO (Last In, First Out) structure where the currently executing function lives. When you call a function, it's pushed onto the stack; when it returns, it's popped off. Synchronous code runs directly on the stack.
Task queue (often called the callback queue or macrotask queue): a FIFO (First In, First Out) queue where callbacks from completed asynchronous operations wait to be executed. When the call stack is empty, the event loop takes the oldest callback from the task queue and pushes it onto the stack.

A tiny example will make this concrete:

console.log("Start");

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

console.log("End");

The output is:

Start
End
Timeout callback

Here's what happened:

console.log("Start") is pushed onto the stack, executed, popped off.
setTimeout is called. The timer is registered with the system; the callback is scheduled. Node.js doesn't wait. setTimeout returns.
console.log("End") runs.
The call stack is now empty. The event loop checks the task queue and finds the timer callback ready (even with 0ms delay, it was queued). It pushes the callback onto the stack, which logs "Timeout callback".

This demonstrates the fundamental dance between the call stack, the event loop, and the task queue.

How async operations are handled

Let's follow a more realistic async operation, like reading a file:

const fs = require("fs");

console.log("Before read");

fs.readFile("example.txt", "utf8", (err, data) => {
  if (err) throw err;
  console.log("File content:", data);
});

console.log("After read");

Output:

Before read
After read
File content: (actual content)

Step by step:

console.log("Before read") runs on the stack.
fs.readFile is called. Node.js hands the operation to libuv and the operating system. A callback is registered. The main thread does not wait; it immediately moves to the next line.
console.log("After read") runs.
Meanwhile, the operating system reads the file in the background. When done, the callback is placed into the task queue.
The event loop, seeing an empty call stack, picks the callback from the queue and runs it, logging the file content.

Notice how the non-blocking behavior keeps the thread free between the read call and the callback execution. This is how Node.js can handle thousands of concurrent requests: the event loop keeps picking up callbacks, while I/O happens in parallel in the OS.

Timers vs I/O callbacks (high level)

You might wonder: do timer callbacks and I/O callbacks wait in the same queue? The event loop has multiple phases, each with its own queue of callbacks. But for now, we can think of them as different types of events that the loop processes in a specific order.

Timer callbacks: scheduled by setTimeout and setInterval. They are executed only after the specified minimum delay has passed. However, they are not guaranteed to run exactly after that time; they wait until the event loop reaches the timers phase and no other script is blocking the thread.
I/O callbacks: these are callbacks from file system operations, network requests, and other asynchronous I/O. They are processed in the "poll" phase of the event loop, after timers and some other internal checks.

In practice, this means that a long-running synchronous operation can delay both timer and I/O callbacks. The event loop will simply not get a chance to push them from the queue until the call stack clears. This is why we avoid heavy synchronous code in Node.js.

The key takeaway: both timer and I/O callbacks are scheduled by the event loop, and the loop ensures they are executed in a fair, orderly manner. The exact order of phases isn't critical for everyday use, but knowing that the loop processes callbacks in batches (timers first, then I/O) helps you avoid surprises.

The event loop's role in scalability

The event loop is the engine behind Node.js's ability to handle massive concurrency with a single thread. Because the main thread never blocks on I/O, the event loop can continuously accept new connections and schedule their work. The operating system handles the actual parallel I/O, and the event loop merely dispatches results when they arrive.

This model scales extremely well for I/O-bound applications. A single Node.js process can maintain tens of thousands of open connections (like WebSocket sessions) because the memory cost is minimal: each connection is just a small amount of state and a callback, not a whole thread.

The event loop also encourages developers to write asynchronous code that doesn't block the thread. This mindset leads to applications that are inherently more responsive under load.

Visualizing the event loop execution cycle

Common misconceptions

"Node.js is single-threaded, so it can't handle multiple requests at once."

False. It handles many requests concurrently by interleaving their asynchronous operations. The main thread never gets stuck on one request; it quickly cycles through them, thanks to the event loop.

"setTimeout(fn, 0) runs immediately."

Not quite. It schedules the callback to run after 0 milliseconds, but the event loop still has to wait for the current call stack to empty. It's a common trick to defer code execution until after the current synchronous block finishes.

"All callbacks go into the same queue."

Not precisely. The event loop has distinct phases (timers, I/O, check, close) with separate queues. But conceptually, they all funnel into the same serial execution flow on the main thread.

Conclusion

The event loop is the heartbeat of Node.js. It takes the inherent single-threadedness of JavaScript and turns it into a powerful asynchronous dispatcher that never sleeps. By understanding how the call stack, task queue, and event loop work together, you gain insight into why your code executes in the order it does and how to write truly non-blocking applications.

Let's quickly recap:

Node.js runs JavaScript on a single thread, but uses an event loop to avoid blocking.
The event loop is a task manager that continuously picks callbacks from the task queue and runs them when the stack is empty.
The call stack handles synchronous code; the task queue holds callbacks waiting their turn.
Async operations like file reads are handed off to the OS; upon completion, their callbacks enter the queue and are later executed by the loop.
Timer callbacks (setTimeout) and I/O callbacks are handled in separate phases of the loop, but the core idea is the same: they only run after the current stack finishes.
This design allows Node.js to scale massively for I/O-heavy workloads while using minimal resources.

With the event loop now demystified, you have the foundation to write robust, high-performance Node.js applications. In the next post, we'll start exploring the built-in modules that make Node.js so powerful right out of the box.

Hope you found this helpful! If you spot any mistakes or have suggestions, let me know. You can find me on LinkedIn and X, where I post more about web development.

DEV Community: SATYA SOOTAR

Sessions vs JWT vs Cookies: Understanding Authentication Approaches

What are cookies?

What are sessions?

What are JWT tokens?

Stateful vs stateless authentication

Sessions vs JWT: detailed comparison

When to use each method

Conclusion

URL Parameters vs Query Strings in Express.js

What URL parameters are

What query strings (query parameters) are

Differences between URL parameters and query strings

Accessing params in Express

Accessing query strings in Express

When to use params vs query: practical examples

User profile ID (use params)

Search filters (use query strings)

Mixed usage

Visualizing the URL structure

Conclusion

Storing Uploaded Files and Serving Them in Express

Where uploaded files are stored

Local storage vs external storage concept

Serving static files in Express

Setting up the complete flow

Accessing uploaded files via URL

Security considerations for uploads

1. Limit allowed file types

2. Restrict file size

3. Rename files to avoid path traversal

4. Store uploaded files outside the public web root

5. Do not execute uploaded files

6. Scan for malware (advanced)

Conclusion

Handling File Uploads in Express with Multer

Why file uploads need middleware

What Multer is

The multipart/form-data concept simply

Setting up Multer

Minimal storage configuration

Handling a single file upload

Handling multiple file uploads

1. Multiple files with the same field name (array of files)

2. Multiple fields with different names

Serving uploaded files

Visualizing the upload flow

Conclusion

Creating Routes and Handling Requests with Express

What is Express.js?

Why Express simplifies Node.js development

Creating your first Express server

Handling GET requests

1. Simple GET route

2. Using route parameters

3. Query string parameters

4. Returning JSON data

Handling POST requests

Sending responses

Conclusion

What is Middleware in Express and How It Works

What middleware is in Express

Where middleware sits in the request lifecycle

The role of next()

Application-level middleware

Router-level middleware

Built-in middleware

Execution order of middleware

Real-world examples

Logging middleware

Authentication middleware

Request validation middleware

Middleware pipeline

Conclusion

REST API Design Made Simple with Express.js

What is a REST API?

Resources in REST architecture

HTTP methods and what they do

Setting up the Express.js server

Designing routes for the "users" resource

The role of `next()`