DEV Community: Loknath Patel

Stop Returning `200 OK` for Every API Response in Express

Loknath Patel — Wed, 28 Oct 2026 14:17:43 +0000

A common pattern in Express tutorials is to end every route with res.json(...) and report failures inside the response body:

app.get('/users/:id', async (req, res) => {
  const user = await db.findUser(req.params.id);

  if (!user) {
    return res.json({
      success: false,
      message: 'User not found'
    });
  }

  res.json({ success: true, user });
});

The problem is that Express sends 200 OK by default when you don't set another status code. The HTTP response says the request succeeded, while the body says it failed.

That mismatch makes your API harder to use correctly.

The status code is part of your API contract

Browsers, HTTP clients, proxies, monitoring tools and application logs can all work with HTTP status codes. They don't automatically understand a custom field such as success: false.

Consider the Fetch API. A request that receives a 404 or 500 doesn't normally reject the fetch() promise. You check response.ok to determine whether the response has a successful HTTP status.

If every response returns 200, response.ok stays true, even when the body describes a failure. Every client has to remember to inspect your custom response format, and one missed check can lead to incorrect behaviour.

Using the right status code makes the outcome clear at the HTTP level.

Success responses: 200, 201 and 204

These three status codes describe different kinds of successful requests.

Use 200 OK when the request succeeds and you have a response to return. Fetching a user or returning an updated record are common examples.

Use 201 Created when the request creates a resource. For example, after creating a user, you can return the resource and its location:

app.post('/users', async (req, res) => {
  const user = await db.createUser(req.body);

  res
    .status(201)
    .location(`/users/${user.id}`)
    .json(user);
});

The Location header identifies the new resource. For an API that creates a user, this can make the resource easier for clients to locate.

Use 204 No Content when the request succeeds and you don't need to return a response body. A successful DELETE request is a common example:

app.delete('/users/:id', async (req, res) => {
  const deleted = await db.deleteUser(req.params.id);

  if (!deleted) {
    return res.status(404).json({
      error: 'User not found'
    });
  }

  return res.status(204).end();
});

A 204 response must not contain a body. Don't use res.status(204).json({ deleted: true }) to communicate the result. If the client needs confirmation data in the body, use an appropriate response such as 200 OK instead.

Client errors: 400, 401, 403 and 404

These status codes are easy to mix up, but each communicates a different problem.

400 Bad Request is appropriate when the request is invalid or malformed. Examples include invalid JSON or a request that fails your input-validation rules.

401 Unauthorized means valid authentication credentials are missing or unavailable. Despite the name, it concerns authentication rather than permission. A 401 response generally needs a WWW-Authenticate header describing the authentication scheme.

For example, a Bearer-authenticated API might respond like this:

return res
  .status(401)
  .set('WWW-Authenticate', 'Bearer')
  .json({ error: 'Authentication required' });

403 Forbidden means the server understood the request but refuses to fulfil it. A user who is authenticated but lacks permission to delete an order is a typical example.

Returning 401 to an authenticated user who lacks a required role is misleading. Asking that user to sign in again won't grant the missing permission.

404 Not Found means the requested resource couldn't be found. If /users/9999 refers to a user that doesn't exist, 404 is appropriate.

There is one useful distinction: a request for /users?role=admin can return 200 OK with an empty array. The collection endpoint exists, even if no users match the filter.

Sometimes an API may deliberately return 404 instead of 403 to avoid revealing whether a protected resource exists. That should be a consistent security decision, not an accidental choice.

Use 500 for unexpected server failures

500 Internal Server Error is for a server-side failure that prevents the request from being fulfilled. Examples include an unexpected application exception or an internal failure that hasn't been mapped to a more specific response.

A common mistake is to catch every error and return 500, including validation failures. If the client submits an invalid email address, returning 500 incorrectly suggests that the server is at fault.

Express supports centralized error handling, so routes don't have to build every error response independently.

For example, you can define an error type that carries an HTTP status:

class HttpError extends Error {
  constructor(status, message) {
    super(message);
    this.status = status;
  }
}

A route can then pass a known error to the error handler:

app.get('/orders/:id', async (req, res, next) => {
  try {
    const order = await db.findOrder(req.params.id);

    if (!order) {
      throw new HttpError(404, 'Order not found');
    }

    return res.json(order);
  } catch (err) {
    return next(err);
  }
});

The try/catch pattern above forwards errors to Express through next(err), including when using Express 4.

You can handle those errors centrally:

app.use((err, req, res, next) => {
  if (res.headersSent) {
    return next(err);
  }

  const status = Number.isInteger(err.status) &&
    err.status >= 400 &&
    err.status <= 599
      ? err.status
      : 500;

  return res.status(status).json({
    error: status === 500
      ? 'Internal server error'
      : err.message
  });
});

Register the error-handling middleware after your routes. The res.headersSent check matters because a response that has already started cannot simply be replaced with a new JSON error response.

For unexpected 500 errors, return a generic message rather than exposing stack traces or internal details to clients. Keep the full error in your server-side logs so you can investigate it.

Express 5 can forward rejected promises from async route handlers automatically. With Express 4, use next(err) or an appropriate async wrapper to forward asynchronous errors.

A few edge cases worth getting right

Validation errors and conflicts aren't the same thing. A malformed email can produce 400 Bad Request. A valid email that is already registered may produce 409 Conflict, because the request conflicts with the current state of the resource.

Malformed JSON can already have a client-error status. Express's JSON parser can produce a parsing error with a 400 status. A catch-all handler that overwrites every error with 500 loses that distinction.

A status code doesn't replace a useful response body. A client may need to know whether a user was missing, a permission was denied or a field was invalid. Return a concise, consistent error object alongside the appropriate status code.

For example:

{
  "error": "Validation failed",
  "details": {
    "email": "A valid email address is required"
  }
}

Choose an error format that fits your API and document it so clients know what to expect.

Make the HTTP response tell the truth

A response body can explain what happened, but the status code tells clients whether the HTTP request succeeded, failed or needs special handling.

Returning 200 OK for every outcome forces clients to understand your custom conventions before they can interpret a response correctly. Use status codes deliberately, keep error bodies consistent, and let your API communicate clearly at both levels.

Your Website Works With a Mouse, But Fails With a Keyboard

Loknath Patel — Fri, 23 Oct 2026 10:35:14 +0000

Picture a settings page. There's an Export control in the toolbar, a filter dropdown, and a Settings dialog. Everything works when you click. Now push your mouse aside and press Tab. The focus ring has vanished, Export never receives focus, and the dialog opens while keyboard focus stays on the page behind it.

Nothing in this page throws an error, and a mouse-driven demo would pass. That gap is what this article is about, and the test that exposes it is one question: can someone use this interface without touching a mouse?

A clickable div is not a button

This is the most common version of the problem:

<div class="btn" onclick="exportReport()">Export</div>

A <div> isn't focusable, so Tab skips it. It has no button role, so assistive technology doesn't know it's a control. Enter and Space do nothing even if you could reach it. A mouse click works because onclick listens for pointer events, and that's the only input this element supports.

The fix is the element that already does all of this:

<button type="button" id="export">Export</button>

document.getElementById('export').addEventListener('click', exportReport);

A native <button> is focusable, exposes the right role, and activates with Enter and Space. The W3C's Using ARIA guidance puts this as its first rule: if a native element already has the semantics and behavior you need, use it instead of repurposing another element and adding ARIA.

It's tempting to think role="button" on the div solves the problem. It doesn't. The same guidance notes that changing an element's role doesn't add behaviors to it. A role changes what assistive technology is told about the element, and nothing else. If you truly can't use a <button>, you have to rebuild the behavior yourself:

<div role="button" tabindex="0" id="export">Export</div>

const el = document.getElementById('export');
el.addEventListener('click', exportReport);
el.addEventListener('keydown', (event) => {
  if (event.key === 'Enter') exportReport();
  if (event.key === ' ') {
    event.preventDefault(); // stop the page from scrolling
    exportReport();
  }
});

This is a sketch, not a replacement. A native button also handles the disabled state, form submission, and other details this version ignores. Links follow the same logic. If an action navigates somewhere, use <a href>, which gives you Enter activation, middle-click, and "open in new tab" for free.

Removing the focus outline removes the map

The usual culprit is a CSS reset:

:focus { outline: none; }

Keyboard users rely on the focus indicator to know where they are. WCAG 2.4.7 Focus Visible (Level AA) requires that any keyboard-operable interface has a mode of operation where the focus indicator is visible. The same page lists styling that removes or hides the indicator as a documented failure (F78).

You don't have to show a ring on every mouse click to comply. The Understanding document explicitly allows user agents to show the indicator only when the keyboard is in use, and :focus-visible is the CSS tool for that:

button:focus-visible,
a:focus-visible,
input:focus-visible {
  outline: 3px solid #0b57d0;
  outline-offset: 2px;
}

Browsers' default styles already behave this way, so often the best fix is deleting the reset. If you replace the outline, remember it's also a graphical object, so it falls under 1.4.11 Non-text Contrast.

WCAG 2.2 added a related requirement. 2.4.11 Focus Not Obscured (Minimum) (Level AA) says a component that receives keyboard focus must not be entirely hidden by author-created content. The classic offender is a sticky header or cookie banner covering the control you just tabbed to. Reserving space with scroll-padding is a common mitigation:

html { scroll-padding-top: 5rem; } /* roughly the sticky header's height */

Test it rather than trusting the number. Tab through the page at a few viewport sizes and watch whether the focused element stays in view.

Dialogs need focus to go somewhere, and to come back

A dialog that opens visually but leaves focus behind is one of the most disorienting keyboard failures. The APG modal dialog pattern describes the expected behavior: focus moves into the dialog when it opens, Tab and Shift+Tab stay inside it, Escape closes it, and focus returns to the element that opened it. The pattern notes exceptions, such as when the invoking element no longer exists.

Building this by hand means managing focus, containment, and Escape yourself. The native <dialog> element does most of it when opened with showModal():

<button type="button" id="open-settings">Settings</button>

<dialog id="settings" aria-labelledby="settings-title">
  <h2 id="settings-title">Settings</h2>
  <form method="dialog">
    <label for="name">Display name</label>
    <input id="name" name="name" autocomplete="name">
    <button value="cancel">Cancel</button>
    <button value="save">Save</button>
  </form>
</dialog>

const dialog = document.getElementById('settings');
document.getElementById('open-settings')
  .addEventListener('click', () => dialog.showModal());

Per MDN's <dialog> documentation, showModal() makes content outside the dialog inert and sets focus on the first focusable element inside. The autofocus attribute lets you choose a better starting point. The APG suggests, for example, focusing the least destructive action when a dialog confirms something hard to undo. W3C's technique H102 also describes the browser returning focus to the invoking element on close.

Two cautions. Calling dialog.show() or setting the open attribute gives you a non-modal dialog without the inert background. And don't put tabindex on the <dialog> itself, since MDN notes it isn't an interactive element.

If you build a modal from divs instead, the APG says to set aria-modal="true" only when your code actually prevents interaction with everything outside it and the styling visually obscures that content. Marking something modal when it isn't can hurt screen reader users.

Menus and widgets don't share one key pattern

Tab moves between controls. Inside a composite widget such as a menu, tabs, or a listbox, arrow keys often move within the widget instead. But the right pattern depends on the widget, so check the APG patterns before choosing. Many site navigation dropdowns are better built as a button that toggles a list of links (the APG disclosure pattern) than as an application-style role="menu", which promises arrow-key behavior you then have to deliver.

This is where tabindex gets misused. tabindex="0" puts an element in the natural tab order, and tabindex="-1" makes it focusable by script but not by Tab. The APG describes values above zero as strongly discouraged, since they override document order and become hard to maintain. Adding tabindex="0" to non-interactive content doesn't make it accessible either. It adds a stop that does nothing.

ARIA attributes work the same way as roles. aria-expanded="false" on a button tells assistive technology the state, but your script has to flip it and show or hide the content. Keyboard accessibility and screen reader accessibility overlap, but they aren't the same thing. A custom control can have perfect ARIA and still be unreachable by Tab, or be fully keyboard operable and announce nothing useful.

Forms: labels and errors need a keyboard path

Start with <label for> tied to each input's id. Placeholder text isn't a label. For errors, WCAG 3.3.1 Error Identification (Level A) requires that a detected error be identified and described in text. The W3C WAI forms tutorial adds that moving focus to the first field with an error is convenient after a failed submission.

<form id="signup" novalidate>
  <label for="email">Email</label>
  <input id="email" name="email" type="email" required
         aria-describedby="email-error" aria-invalid="false">
  <p id="email-error" hidden></p>
  <button type="submit">Create account</button>
</form>

const form = document.getElementById('signup');
form.addEventListener('submit', (event) => {
  const field = form.elements.email;
  if (field.validity.valid) return;

  event.preventDefault();
  const error = document.getElementById('email-error');
  error.textContent = 'Enter an email address like name@example.com.';
  error.hidden = false;
  field.setAttribute('aria-invalid', 'true');
  field.focus();
});

The message is plain text, so sighted users see it. aria-describedby connects it to the input, so it's read when the field gains focus. aria-invalid flags the state, and focus() puts a keyboard user on the problem. W3C's ARIA21 technique notes that aria-invalid alone doesn't associate message text with the control. In a longer form, an error summary with links to each field is a documented approach too (G139). Reset aria-invalid once the field is fixed.

Focus order and keyboard traps

Tab order follows the DOM, not the visual layout. If you reorder content with CSS order or absolute positioning, focus can jump around the screen in a way that no longer matches the reading sequence. That's the territory of 2.4.3 Focus Order.

A real trap is different from a modal dialog that intentionally contains focus. 2.1.2 No Keyboard Trap is about focus that can enter a component and can't leave by keyboard. Embedded video players, rich text editors, and third-party widgets are common sources. A modal dialog has Escape and a close button as exits.

A keyboard test you can run in ten minutes

Unplug or ignore the mouse, then work through the page:

Can you reach every link, button, and form control with Tab and Shift+Tab?
Is the focus indicator always visible, including against dark backgrounds and under sticky headers?
Does Enter activate links and buttons, and Space activate buttons?
Does the tab order match the visual order?
When a dialog or menu opens, does focus move into it? Does Escape close it, and does focus go back to the trigger?
Can you leave every component, including embeds, without a mouse?
After a failed form submission, can you tell what's wrong and get to the field?

This checks keyboard operability only. It won't tell you what a screen reader announces, so pair it with screen reader testing. Whether these criteria are legally required depends on your jurisdiction and context. WCAG Levels A and AA are the usual targets, and the APG is guidance on how to build things, not a set of conformance requirements.

How to Call an API with JavaScript fetch() and Handle Errors Properly

Loknath Patel — Sun, 18 Oct 2026 04:04:46 +0000

Most fetch() tutorials only show the happy path. The bug that actually catches beginners is a different one: fetch() does not throw an error when a server responds with a 404 or 500. Your code just keeps running with bad data.

This article is for you if you know basic JavaScript but haven't used fetch() yet. We'll write a small script that:

requests data from a public test API,
checks whether the request succeeded,
parses the JSON response,
handles errors and timeouts without crashing.

fetch() works in modern browsers and in Node.js (it's built in since Node 18, so use a currently supported LTS version). There's nothing to install.

The test API

We'll use JSONPlaceholder, a free fake REST API made for testing and prototyping. It doesn't need an API key. The /posts/1 endpoint returns this JSON:

{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
}

What `fetch()` actually does

fetch(url) sends an HTTP request (a GET by default) and returns a Promise. Once the server sends back its response headers, that promise resolves to a Response object.

Two things to know before we go further:

The Response isn't your data yet. It's a wrapper around the status, headers, and body. To get the data, you call a method like response.json(), which also returns a Promise.
fetch() only rejects its promise when the request itself fails, for example when there's no connection, the URL is invalid, CORS blocks the request, or it gets aborted or times out. A 404 or 500 still counts as a completed round trip, so the promise resolves. That's why you have to check the status yourself.

`async/await` in one minute

async/await lets you write Promise-based code that reads from top to bottom.

A function marked async always returns a Promise.
Inside it, await pauses the function until a Promise settles, then hands you the result.
If the awaited Promise rejects, await throws, so you can catch it with try/catch.

The complete example

Save this as example.mjs. The .mjs extension lets Node run it as an ES module without any setup:

const BASE_URL = "https://jsonplaceholder.typicode.com";

async function getPost(id) {
  const response = await fetch(`${BASE_URL}/posts/${id}`);

  if (!response.ok) {
    throw new Error(`HTTP error: ${response.status}`);
  }

  return response.json();
}

async function main() {
  try {
    const post = await getPost(1);
    console.log("Title:", post.title);
    console.log("Post:", post);
  } catch (error) {
    console.error("Request failed:", error.message);
  }
}

main();

Run it:

node example.mjs

Expected output

If the request succeeds, Node prints:

Title: sunt aut facere repellat provident occaecati excepturi optio reprehenderit
Post: {
  userId: 1,
  id: 1,
  title: 'sunt aut facere repellat provident occaecati excepturi optio reprehenderit',
  body: 'quia et suscipit\n' +
    'suscipit recusandae consequuntur expedita et cum\n' +
    'reprehenderit molestiae ut ut quas totam\n' +
    'nostrum rerum est autem sunt rem eveniet architecto'
}

Node splits long strings across lines when it prints objects, but the data is the same JSON you saw above.

You can also skip Node entirely: open your browser's DevTools console, paste in the whole script, and press Enter.

Watch an error happen

Now change getPost(1) to getPost(99999) and run it again. That post doesn't exist, so JSONPlaceholder responds with a 404:

Request failed: HTTP error: 404

Without the response.ok check, this request would have looked like a success, and your code would have carried on with an empty object. That's exactly what the check protects you from.

How it works, step by step

1. Send the request.

const response = await fetch(`${BASE_URL}/posts/${id}`);

await waits for the response headers to arrive and gives you the Response object.

2. Check for HTTP errors with response.ok.

if (!response.ok) {
  throw new Error(`HTTP error: ${response.status}`);
}

response.ok is true when the status code is between 200 and 299. For anything else, like a 404 or 500, we throw our own error so the problem gets handled in one place instead of being ignored.

3. Parse the JSON.

return response.json();

response.json() reads the body and turns it into a JavaScript object. It returns a Promise, and since we return it from an async function, callers get the parsed object when they await getPost(1).

4. Catch errors in one place. The try/catch in main() covers everything that can go wrong: network failures, the error we throw for bad status codes, and invalid JSON.

Gotcha: This works because the try/catch lives in main(). If you later add a try/catch inside getPost, a JSON parse error will slip past it when you write return response.json(). Use return await response.json() there, so the rejection is thrown inside your try block.

The ways a request can fail

What went wrong	What happens
Server returns 404 or 500	`fetch()` resolves, `response.ok` is `false`, and our code throws
Server returns a non-JSON body with a 200 status	`response.json()` rejects with a `SyntaxError`
Server can't be reached	`fetch()` rejects with a `TypeError`
Request takes too long (with a timeout set)	`fetch()` rejects with a `TimeoutError`

Error message text varies between runtimes and versions, and browsers and Node word things differently. So don't compare against message strings. Use response.status for HTTP errors, and treat everything else as "something went wrong."

If you want to react to a specific status code, attach it to the error:

if (!response.ok) {
  const error = new Error(`HTTP error: ${response.status}`);
  error.status = response.status;
  throw error;
}

Tip for Node: A network failure often shows up as just fetch failed. The useful detail, such as ENOTFOUND or ECONNREFUSED, is in error.cause, so log that too:

console.error("Request failed:", error.message, error.cause);

Tip for browsers: If CORS blocks a request, all you'll see is a generic TypeError: Failed to fetch. Check the DevTools console and network tab for the real reason. The server has to allow your origin, and you can't fix that from the client.

Add a timeout

If a server never answers, a request can hang for a very long time. To give up after a set number of milliseconds, pass AbortSignal.timeout() as the signal:

const response = await fetch(`${BASE_URL}/posts/${id}`, {
  signal: AbortSignal.timeout(5000), // give up after 5 seconds
});

When time runs out, fetch() rejects with an error whose name is "TimeoutError". You can handle it separately in your catch:

catch (error) {
  if (error.name === "TimeoutError") {
    console.error("The request took too long.");
  } else {
    console.error("Request failed:", error.message);
  }
}

Common mistakes

1. Assuming fetch() throws on 404 or 500.
It doesn't. Try getPost(99999): JSONPlaceholder returns a 404, the promise resolves normally, and response.ok is false. Without a response.ok check, your code behaves as if everything worked.

2. Forgetting await (or .json()).
Both fetch() and response.json() return Promises. If you skip await, you get a pending Promise (it prints as Promise { <pending> }) instead of your data.

3. Reading the body twice.
A response body can only be read once, and calling response.json() a second time throws a TypeError. If you need it twice, call response.clone() first, or store the result in a variable.

4. Calling response.json() on a response that isn't JSON.
Some error responses come back as plain text or HTML. Check response.ok first, and use response.text() when you need to see what the server actually sent.

5. Skipping try/catch.
An unhandled rejection from await fetch(...) can crash a Node script or leave a browser UI stuck on a loading state.

Bonus: sending data with POST

The same pattern works for other HTTP methods. Pass an options object as the second argument. Save this as a separate file called post.mjs:

const BASE_URL = "https://jsonplaceholder.typicode.com";

async function createPost(data) {
  const response = await fetch(`${BASE_URL}/posts`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(data),
    signal: AbortSignal.timeout(5000),
  });

  if (!response.ok) {
    throw new Error(`HTTP error: ${response.status}`);
  }

  return response.json();
}

async function main() {
  try {
    const created = await createPost({
      title: "Hello",
      body: "My first post",
      userId: 1,
    });
    console.log(created);
  } catch (error) {
    console.error("Request failed:", error.message);
  }
}

main();

Run it with node post.mjs. JSONPlaceholder accepts write requests but doesn't save anything, so it's safe to experiment. It echoes back what you sent, plus a fake id:

{ title: 'Hello', body: 'My first post', userId: 1, id: 101 }

Conclusion

Here's the pattern for calling an API with fetch():

await fetch(url) to get the Response.
Check response.ok and throw if it's false, because fetch() won't do it for you.
await response.json() to get your data.
Wrap everything in try/catch, and set a timeout with AbortSignal.timeout().

That covers most everyday API calls. From here, you can explore query parameters and custom request headers.

Session-Based Authentication in Node.js and TypeScript with HttpOnly Cookies and CSRF Protection

Loknath Patel — Wed, 14 Oct 2026 12:41:45 +0000

Most authentication tutorials end at "the user is logged in". That is the easy part. The hard part is everything around it: where the password actually goes, where the session lives, what happens when someone steals a cookie, and why your "protected" endpoint still accepts requests from a random website.

A common way this goes wrong: the session token sits in localStorage, an XSS bug or a compromised dependency injects a script, and every token in every open tab can be sent to an attacker's server with one fetch. HttpOnly cookies exist to stop exactly that.

This tutorial builds an authentication API that takes the boring parts seriously: Argon2id password hashing, server-side sessions, an HttpOnly session cookie, CSRF protection that matches the architecture, and a small test suite that covers the main failure paths.

What you will build

A small JSON API with four endpoints:

Method	Path	Purpose
`POST`	`/api/auth/register`	Create a user and start a session
`POST`	`/api/auth/login`	Verify credentials and rotate the session
`GET`	`/api/auth/me`	Return the signed-in user
`POST`	`/api/auth/logout`	Destroy the session

Plus GET /api/csrf-token for CSRF tokens and GET /api/health.

The stack:

Node.js 22 (LTS) with TypeScript. Tested on Node v22.23.2. Node 22 is in Maintenance LTS, with end-of-life on 2027-04-30.
Express 5
Argon2id for password hashing
SQLite (via better-sqlite3) for users and sessions
express-session with a custom SQLite store
csrf-sync for the synchronizer token pattern
Zod for input validation
Vitest and supertest for tests

The versions below were verified against the npm registry and the local runtime while writing: express@5.3.0, express-session@1.19.0, argon2@0.45.1, better-sqlite3@13.0.3, zod@4.6.7, helmet@8.3.0, csrf-sync@4.2.1, supertest@7.3.1, vitest@5.0.4, typescript@7.0.2, on node@v22.23.2.

The architecture, and why

Browser                          Server
  |                                 |
  |-- POST /api/auth/login -------->|  verify Argon2id hash
  |<-- Set-Cookie: sid=... ---------|  create session row in SQLite
  |    (HttpOnly; SameSite=Lax)     |  session data stays server-side
  |                                 |
  |-- GET /api/auth/me -------------|  look up session by signed id
  |    Cookie: sid=...              |  load userId from the store
  |<-- 200 {user} ----------------- |

Three decisions matter here.

The session lives on the server. The cookie carries only a signed, random session ID. The user's identity is stored in a database row, not in the browser. Logging out actually revokes access, because the server can delete the row. A stateless JWT can't be revoked without extra machinery.

The cookie is HttpOnly. document.cookie can't read it, so an XSS bug can't exfiltrate the session. MDN is explicit that HttpOnly doesn't stop the browser from sending the cookie, which is exactly why the next point matters.

Cookies are sent automatically, so the API needs CSRF protection. If the browser attaches your session cookie to a request from evil.example, then "the request carries a valid session" is not proof the user intended it. A CSRF token that a cross-site attacker can't read fixes that.

The threat model, briefly

Threat	Mitigation in this tutorial
Database leak exposes passwords	Argon2id + unique salt per password
XSS steals the session	`HttpOnly` cookie; session data server-side
Session hijacking in transit	`Secure` cookie in production, HTTPS
Cross-site request forgery	Synchronizer token in a custom header
Session fixation	Regenerate the session ID on login
User enumeration via login timing	Verify against a dummy hash when the email is unknown
User enumeration via registration	Not solved here - a duplicate email still returns `409`; see the limitations section
Brute force	Not solved here - see the limitations section

1. Project setup

mkdir secure-auth-demo && cd secure-auth-demo
npm init -y
npm pkg set type=module
npm install express express-session argon2 better-sqlite3 zod helmet csrf-sync
npm install -D typescript tsx vitest supertest @types/express @types/express-session \
  @types/better-sqlite3 @types/supertest @types/node@^22

Two dependency notes worth recording:

csurf is deprecated. Express's own blog announced the retirement of legacy packages including csurf and points developers at a strategy that fits their architecture. For session-based apps, csrf-sync implements the OWASP synchronizer token pattern directly. Don't copy older tutorials that still install csurf.
sqlite3 is no longer maintained. Its upstream repository, TryGhost/node-sqlite3, was archived on 1 July 2026 and is read-only, so no further releases are coming. (The final npm release, 6.0.1, is not itself flagged deprecated; the archival is the reason to avoid it.) better-sqlite3 is the actively maintained alternative, and its synchronous API also removes a layer of callback plumbing.

package.json scripts:

{
  "type": "module",
  "engines": { "node": ">=22" },
  "scripts": {
    "dev": "tsx watch --env-file=.env src/server.ts",
    "build": "tsc -p tsconfig.build.json",
    "start": "node --env-file-if-exists=.env dist/server.js",
    "typecheck": "tsc --noEmit",
    "test": "vitest run"
  }
}

--env-file is built into Node, so you don't need dotenv. The start script uses --env-file-if-exists: without a .env file, the config validator reports the missing SESSION_SECRET (tested on Node v22.23.2 only). With the plain --env-file flag, I ran npm start without a .env file and it failed with node: .env: not found. One caveat I hit while testing: Node's --env-file doesn't override variables that are already set in the environment. The file is a default source, not an override. If your shell exports PORT, that wins.

TypeScript configuration

TypeScript's Node target mapping lists Node 22 with target/lib ES2023 and module: "nodenext". With ESM and NodeNext, relative imports must include the emitted .js extension.

tsconfig.json (used for type-checking everything, including tests):

{
  "compilerOptions": {
    "target": "ES2023",
    "lib": ["ES2023"],
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "types": ["node"],
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noFallthroughCasesInSwitch": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true,
    "noEmit": true
  },
  "include": ["src", "tests", "vitest.config.ts"]
}

tsconfig.build.json narrows the build to src so tests are not shipped:

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "noEmit": false,
    "rootDir": "src",
    "outDir": "dist",
    "sourceMap": true
  },
  "include": ["src"]
}

2. Environment configuration

src/config.ts validates the environment once at boot:

import { z } from "zod";

/**
 * The whole app reads configuration from here, and the process refuses to
 * start with an invalid configuration instead of failing later at runtime.
 */

/**
 * A blank env var (for example `PORT=` in a .env file) should fall back to the
 * default rather than being coerced into 0 or NaN.
 */
function optionalNumber(fallback: number) {
  return z.preprocess(
    (value) => (typeof value === "string" && value.trim() === "" ? undefined : value),
    z.coerce.number().int().positive().default(fallback),
  );
}

const EnvSchema = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
  PORT: optionalNumber(3000),

  // The secret used to sign the session cookie. 32+ bytes of randomness.
  SESSION_SECRET: z
    .string()
    .min(32, "SESSION_SECRET must be at least 32 characters of randomness"),

  DATABASE_PATH: z.string().min(1).default("./data/app.db"),

  // How long a session stays valid, in milliseconds. Default: 8 hours.
  SESSION_TTL_MS: optionalNumber(1000 * 60 * 60 * 8),
});

const parsed = EnvSchema.safeParse(process.env);

if (!parsed.success) {
  const details = parsed.error.issues
    .map((issue) => `  - ${issue.path.join(".") || "(root)"}: ${issue.message}`)
    .join("\n");
  throw new Error(`Invalid environment configuration:\n${details}`);
}

export const config = parsed.data;

export const isProduction = config.NODE_ENV === "production";
export const isTest = config.NODE_ENV === "test";

.env.example:

NODE_ENV=development
PORT=3000

# Generate with:  node -e "console.log(require('crypto').randomBytes(48).toString('base64url'))"
SESSION_SECRET=

DATABASE_PATH=./data/app.db
SESSION_TTL_MS=28800000

Generate a real secret instead of typing one:

node -e "console.log(require('crypto').randomBytes(48).toString('base64url'))"

The min(32) check in the config is only a length check. It can't tell a random string from a guessable one. express-session signs the session ID with HMAC-256, and its README says the secret should contain at least 32 bytes of entropy, which is what the generated value gives you. An earlier version of .env.example had a placeholder here. I copied it as-is and the app booted with it, because the 45-character placeholder passed the 32-character check. That's why the value is blank now: the app refuses to start until you generate a real secret. Add .env, data/, and dist/ to .gitignore.

3. Database and users

src/db.ts opens SQLite and creates the schema:

import { mkdirSync } from "node:fs";
import { dirname } from "node:path";
import Database from "better-sqlite3";
import { config } from "./config.js";

// ":memory:" is used by the test suite; a file path is used everywhere else.
if (config.DATABASE_PATH !== ":memory:") {
  mkdirSync(dirname(config.DATABASE_PATH), { recursive: true });
}

export const db = new Database(config.DATABASE_PATH);

db.pragma("journal_mode = WAL");
db.pragma("foreign_keys = ON");

export function migrate(): void {
  db.exec(`
    CREATE TABLE IF NOT EXISTS users (
      id            INTEGER PRIMARY KEY AUTOINCREMENT,
      email         TEXT    NOT NULL UNIQUE,
      password_hash TEXT    NOT NULL,
      created_at    INTEGER NOT NULL
    );

    CREATE TABLE IF NOT EXISTS sessions (
      sid        TEXT    PRIMARY KEY,
      data       TEXT    NOT NULL,
      expires_at INTEGER NOT NULL
    );

    CREATE INDEX IF NOT EXISTS idx_sessions_expires_at
      ON sessions (expires_at);
  `);
}

migrate();

src/users.ts is the data access layer. Emails are normalized before they reach it, so a plain UNIQUE column is enough:

import { db } from "./db.js";

export interface User {
  id: number;
  email: string;
  passwordHash: string;
  createdAt: number;
}

interface UserRow {
  id: number;
  email: string;
  password_hash: string;
  created_at: number;
}

function toUser(row: UserRow): User {
  return {
    id: row.id,
    email: row.email,
    passwordHash: row.password_hash,
    createdAt: row.created_at,
  };
}

export function findUserByEmail(email: string): User | undefined {
  const row = db
    .prepare("SELECT id, email, password_hash, created_at FROM users WHERE email = ?")
    .get(email) as UserRow | undefined;
  return row ? toUser(row) : undefined;
}

export function findUserById(id: number): User | undefined {
  const row = db
    .prepare("SELECT id, email, password_hash, created_at FROM users WHERE id = ?")
    .get(id) as UserRow | undefined;
  return row ? toUser(row) : undefined;
}

export function insertUser(email: string, passwordHash: string): User {
  const row = db
    .prepare(
      `INSERT INTO users (email, password_hash, created_at)
       VALUES (?, ?, ?)
       RETURNING id, email, password_hash, created_at`,
    )
    .get(email, passwordHash, Date.now()) as UserRow;
  return toUser(row);
}

Every query uses bound parameters (?), so a crafted email can't inject SQL.

4. Password hashing

OWASP's Password Storage Cheat Sheet recommends Argon2id first, and lists one of its minimum configurations: 19 MiB of memory, 2 iterations, parallelism 1 (m=19456, t=2, p=1).

import argon2 from "argon2";

/**
 * One of the minimum Argon2id configurations listed in the OWASP Password Storage Cheat Sheet: m=19456 (19 MiB), t=2, p=1.
 */
const ARGON2_OPTIONS = {
  type: argon2.argon2id,
  memoryCost: 19456,
  timeCost: 2,
  parallelism: 1,
} as const;

export function hashPassword(password: string): Promise<string> {
  return argon2.hash(password, ARGON2_OPTIONS);
}

export async function verifyPassword(hash: string, password: string): Promise<boolean> {
  try {
    // The encoded hash carries its own algorithm and parameters, so no options
    // are needed here.
    return await argon2.verify(hash, password);
  } catch {
    return false;
  }
}

argon2.verify takes no algorithm option, because the encoded hash string already records the algorithm, memory cost, iterations, and salt, which is why a single password_hash column is enough. verifyPassword returns false on a malformed hash rather than throwing, so a corrupted row can't produce a 500.

Why not bcrypt? OWASP lists bcrypt as an acceptable choice for legacy systems, with a work factor of at least 10, and calls out its 72-byte input limit: passwords longer than that are silently truncated in some implementations. Argon2id is the better default for new code.

5. A SQLite-backed session store

express-session's default MemoryStore is explicitly not for production: it leaks memory and can't be shared across processes. Since SQLite is already in the project, a small store is the cheapest correct option.

express-session calls touch only if the store has one. This setup depends on it, because rolling: true uses it to push the expiry forward. A maintained package, better-sqlite3-session-store, is listed in the express-session README. I wrote a small one here so you can see what a store has to do.

import session from "express-session";
import type { SessionData } from "express-session";
import { config } from "./config.js";
import { db } from "./db.js";

interface SessionRow {
  data: string;
  expires_at: number;
}

export class SqliteSessionStore extends session.Store {
  override get(sid: string, callback: (err: unknown, session?: SessionData | null) => void): void {
    try {
      const row = db
        .prepare("SELECT data, expires_at FROM sessions WHERE sid = ?")
        .get(sid) as SessionRow | undefined;

      if (!row) {
        callback(null, null);
        return;
      }

      if (row.expires_at <= Date.now()) {
        // Expired sessions are deleted lazily, on the next read.
        this.destroy(sid, () => callback(null, null));
        return;
      }

      callback(null, JSON.parse(row.data) as SessionData);
    } catch (error) {
      callback(error);
    }
  }

  override set(sid: string, sessionData: SessionData, callback?: (err?: unknown) => void): void {
    try {
      const expiresAt = this.expiresAtFor(sessionData);
      db.prepare(
        `INSERT INTO sessions (sid, data, expires_at) VALUES (?, ?, ?)
         ON CONFLICT (sid) DO UPDATE SET data = excluded.data, expires_at = excluded.expires_at`,
      ).run(sid, JSON.stringify(sessionData), expiresAt);
      callback?.();
    } catch (error) {
      callback?.(error);
    }
  }

  override destroy(sid: string, callback?: (err?: unknown) => void): void {
    try {
      db.prepare("DELETE FROM sessions WHERE sid = ?").run(sid);
      callback?.();
    } catch (error) {
      callback?.(error);
    }
  }

  override touch(sid: string, sessionData: SessionData, callback?: (err?: unknown) => void): void {
    try {
      db.prepare("UPDATE sessions SET expires_at = ? WHERE sid = ?").run(
        this.expiresAtFor(sessionData),
        sid,
      );
      callback?.();
    } catch (error) {
      callback?.(error);
    }
  }

  /** Removes every expired row. Useful as a periodic cleanup job. */
  pruneExpired(): number {
    return db.prepare("DELETE FROM sessions WHERE expires_at <= ?").run(Date.now()).changes;
  }

  private expiresAtFor(sessionData: SessionData): number {
    const { expires, maxAge } = sessionData.cookie ?? {};
    if (expires) {
      return new Date(expires).getTime();
    }
    if (typeof maxAge === "number") {
      return Date.now() + maxAge;
    }
    return Date.now() + config.SESSION_TTL_MS;
  }
}

Expiry is enforced in two places: the store refuses to return an expired row, and pruneExpired() sweeps the table. Expired sessions are deleted on read, so a stale cookie is treated as signed out.

6. Session middleware and secure cookies

import type { Request } from "express";
import session from "express-session";
import { config, isProduction } from "./config.js";
import { SqliteSessionStore } from "./session-store.js";

/**
 * OWASP recommends the `__Host-` prefix for session cookies: it forces the
 * browser to require Secure + Path=/ and to reject any Domain attribute, which
 * makes cookie tossing harder. Browsers refuse `__Host-` cookies over plain
 * HTTP, so we only use it in production where TLS is mandatory.
 */
export const SESSION_COOKIE_NAME = isProduction ? "__Host-sid" : "sid";

export const sessionStore = new SqliteSessionStore();

type RequestHandler = ReturnType<typeof session>;

export function createSessionMiddleware(): RequestHandler {
  return session({
    name: SESSION_COOKIE_NAME,
    secret: config.SESSION_SECRET,
    store: sessionStore,

    // Do not re-save untouched sessions. Fetching a CSRF token modifies the
    // session, so anonymous visitors who call /api/csrf-token do get a session row.
    resave: false,
    saveUninitialized: false,

    // Slide the expiry forward on activity, so active users are not logged out
    // mid-session while idle sessions still expire.
    rolling: true,

    cookie: {
      httpOnly: true,     // not readable from JavaScript
      secure: isProduction, // HTTPS only in production
      sameSite: "lax",    // blocks cross-site POSTs; see the CSRF section
      path: "/",
      maxAge: config.SESSION_TTL_MS,
    },
  });
}

export function regenerateSession(req: Request): Promise<void> {
  return new Promise((resolve, reject) => {
    req.session.regenerate((err) => (err ? reject(err) : resolve()));
  });
}

export function saveSession(req: Request): Promise<void> {
  return new Promise((resolve, reject) => {
    req.session.save((err) => (err ? reject(err) : resolve()));
  });
}

export function destroySession(req: Request): Promise<void> {
  return new Promise((resolve, reject) => {
    req.session.destroy((err) => (err ? reject(err) : resolve()));
  });
}

Every cookie attribute here matters:

httpOnly: true. The browser won't expose this cookie to JavaScript. MDN defines it exactly that way. This is the single most important attribute for session cookies.
secure: isProduction. The cookie is only sent over HTTPS (browsers make an exception for localhost).
sameSite: "lax". The cookie isn't attached to cross-site fetch calls or cross-site POSTs, which removes the simplest CSRF vectors. MDN documents Lax as allowing same-site requests plus cross-site top-level navigations using safe methods. Strict is stronger but hurts usability: clicking a link into your app from another site would arrive logged out.
No domain attribute. Omitting it makes this a host-only cookie. OWASP recommends this, and it is required for the __Host- prefix.
maxAge. A bounded lifetime instead of a session cookie that lives until the browser closes.

The three helper functions wrap the callback-based express-session API in promises so the route handlers stay readable. They are also why the tests can assert on await.

Session fixation

An attacker who can force a victim to use a session ID the attacker already knows can take over the session. Regenerating the ID on every privilege change (registration, login, and role change) makes that useless. regenerateSession(req) does that, and it is called on both login and registration.

One consequence you must handle in the client: the CSRF token lives in the session, so it is discarded by regeneration. After logging in, fetch /api/csrf-token again. This surprises people; it's not a bug.

7. CSRF protection

OWASP recommends the synchronizer token pattern for stateful apps: the server generates a secret token tied to the session and validates a submitted copy on unsafe methods. csrf-sync implements exactly that, storing the token in req.session.csrfToken.

import { csrfSync } from "csrf-sync";

/**
 * csrf-sync implements the OWASP "synchronizer token pattern" for stateful
 * (session-based) apps.
 *
 * Defaults we rely on, and why:
 *  - The token is stored server-side in `req.session.csrfToken`.
 *  - Unsafe methods (everything except GET/HEAD/OPTIONS) must present the token
 *    in the `x-csrf-token` request header.
 *  - Invalid or missing tokens produce an error with code `EBADCSRFTOKEN`,
 *    which the error handler turns into a 403.
 */
export const { csrfSynchronisedProtection, generateToken } = csrfSync();

I checked the installed source while writing this: csrf-sync ignores GET, HEAD, and OPTIONS by default, reads the token from the x-csrf-token header, generates 128 random bytes (a 256-character hex token), and raises an error with code: "EBADCSRFTOKEN".

The token must not live in a cookie, and it must not be sent in a URL, because either would defeat the point. A custom header works because reading a custom header requires CORS permission the attacker doesn't have.

8. Routes

import { Router } from "express";
import { z } from "zod";
import { isProduction } from "../config.js";
import { hashPassword, verifyPassword } from "../password.js";
import { requireAuth, currentUserId } from "../middleware/require-auth.js";
import {
  SESSION_COOKIE_NAME,
  destroySession,
  regenerateSession,
  saveSession,
} from "../session.js";
import { findUserByEmail, findUserById, insertUser } from "../users.js";

export const authRouter = Router();

/** Normalise the email before validating it, so case never creates duplicates. */
const emailSchema = z.string().trim().toLowerCase().pipe(z.email());

const registerSchema = z.object({
  email: emailSchema,
  // Length matters more than character-class rules. NIST SP 800-63B recommends
  // allowing long passphrases; we require at least 12 characters and cap the
  // length so a huge body cannot be used to burn CPU.
  password: z.string().min(12).max(200),
});

// Login must not re-apply the registration policy: doing so would leak the
// policy and lock out accounts created before a policy change.
const loginSchema = z.object({
  email: emailSchema,
  password: z.string().min(1).max(200),
});

interface PublicUser {
  id: number;
  email: string;
}

function toPublicUser(user: { id: number; email: string }): PublicUser {
  return { id: user.id, email: user.email };
}

function isUniqueViolation(error: unknown): boolean {
  return (
    typeof error === "object" &&
    error !== null &&
    "code" in error &&
    (error as { code?: string }).code === "SQLITE_CONSTRAINT_UNIQUE"
  );
}

/**
 * A throwaway hash used when the submitted email does not exist. A failed login
 * then performs one real Argon2id verification whether or not the account
 * exists, which narrows the timing gap. It does not remove it: the database
 * lookup and session handling still differ, so treat this as best-effort.
 */
let dummyHash: Promise<string> | undefined;
function getDummyHash(): Promise<string> {
  dummyHash ??= hashPassword("timing-equalisation-placeholder-value");
  return dummyHash;
}
void getDummyHash(); // warm up at startup so the first unknown-email login isn't slower

authRouter.post("/register", async (req, res) => {
  const parsed = registerSchema.safeParse(req.body);
  if (!parsed.success) {
    res.status(400).json({
      error: "Invalid registration details",
      issues: parsed.error.issues.map((issue) => ({
        field: issue.path.join("."),
        message: issue.message,
      })),
    });
    return;
  }

  const { email, password } = parsed.data;

  if (findUserByEmail(email)) {
    res.status(409).json({ error: "Email is already registered" });
    return;
  }

  const passwordHash = await hashPassword(password);

  let user;
  try {
    user = insertUser(email, passwordHash);
  } catch (error) {
    // Two requests can pass the check above at the same time; the UNIQUE
    // constraint is the real guarantee, so translate it into the same 409.
    if (isUniqueViolation(error)) {
      res.status(409).json({ error: "Email is already registered" });
      return;
    }
    throw error;
  }

  // Never keep the pre-login session id after a privilege change.
  await regenerateSession(req);
  req.session.userId = user.id;
  await saveSession(req);

  res.status(201).json({ user: toPublicUser(user) });
});

authRouter.post("/login", async (req, res) => {
  const parsed = loginSchema.safeParse(req.body);
  if (!parsed.success) {
    res.status(400).json({ error: "Invalid login payload" });
    return;
  }

  const { email, password } = parsed.data;
  const user = findUserByEmail(email);

  const hash = user?.passwordHash ?? (await getDummyHash());
  const passwordMatches = await verifyPassword(hash, password);

  if (!user || !passwordMatches) {
    // Identical response for "no such user" and "wrong password" so the API
    // does not confirm which emails exist.
    res.status(401).json({ error: "Invalid email or password" });
    return;
  }

  await regenerateSession(req);
  req.session.userId = user.id;
  await saveSession(req);

  res.json({ user: toPublicUser(user) });
});

authRouter.get("/me", requireAuth, (req, res) => {
  const userId = currentUserId(req);

  const user = userId === undefined ? undefined : findUserById(userId);
  if (!user) {
    res.status(401).json({ error: "Authentication required" });
    return;
  }

  res.json({ user: toPublicUser(user) });
});

authRouter.post("/logout", async (req, res) => {
  await destroySession(req);
  res.clearCookie(SESSION_COOKIE_NAME, {
    httpOnly: true,
    secure: isProduction,
    sameSite: "lax",
    path: "/",
  });
  res.status(204).end();
});

A few notes on that code:

toPublicUser never includes passwordHash. Don't serialize database rows straight to JSON. An explicit projection is the difference between a working API and a hash-leak.
Normalize, then validate. z.string().trim().toLowerCase().pipe(z.email()) means " Alice@Example.COM " and "alice@example.com" are the same account.
The dummy-hash trick. When the email is unknown, the code still runs a real Argon2id verification against a throwaway hash, so a failed login does the same expensive work whether or not the account exists. Without it, a request naming a non-existent email would skip hashing entirely and return noticeably faster, a timing side channel that can disclose which emails are registered. This narrows the gap; it doesn't make the two paths identical, because the database lookup and session handling still differ. I saw the lazy version of this: my first unknown-email login after server start took 0.0457 s against about 0.024 s afterwards, because the dummy hash was created lazily.
One error message for both failures. "Invalid email or password" for both cases avoids a second enumeration channel.
The database constraint is the real guard. The pre-check is for a friendly 409; the UNIQUE constraint is what actually prevents two accounts in a race. Both paths return the same response.

SP 800-63B-4 sets 15 characters as the minimum for single-factor passwords; this demo uses 12 to balance security with user friction.

src/middleware/require-auth.ts:

import type { NextFunction, Request, Response } from "express";

/** The id of the authenticated user, or `undefined` if not signed in. */
export function currentUserId(req: Request): number | undefined {
  const { userId } = req.session;
  return typeof userId === "number" ? userId : undefined;
}

export function requireAuth(req: Request, res: Response, next: NextFunction): void {
  if (currentUserId(req) === undefined) {
    res.status(401).json({ error: "Authentication required" });
    return;
  }
  next();
}

And the session type augmentation, src/types/express-session.d.ts:

import "express-session";

declare module "express-session" {
  interface SessionData {
    /** The authenticated user's id. Absent for anonymous visitors. */
    userId?: number;
  }
}

9. App wiring: order is the specification

import express, { type Express } from "express";
import helmet from "helmet";
import { isProduction } from "./config.js";
import { csrfSynchronisedProtection, generateToken } from "./middleware/csrf.js";
import { errorHandler, notFoundHandler } from "./middleware/error-handler.js";
import { authRouter } from "./routes/auth.js";
import { createSessionMiddleware } from "./session.js";

export function createApp(): Express {
  const app = express();

  // Behind a TLS-terminating proxy, trust the first hop so express-session sees
  // X-Forwarded-Proto and will set `Secure` cookies correctly.
  if (isProduction) {
    app.set("trust proxy", 1);
  }

  app.disable("x-powered-by");

  app.use(helmet());
  app.use(express.json({ limit: "16kb" }));
  app.use(createSessionMiddleware());

  app.get("/api/health", (_req, res) => {
    res.json({ status: "ok" });
  });

  // Hand the client a CSRF token bound to its session. GET is a safe method, so
  // this route is exempt from CSRF checks.
  app.get("/api/csrf-token", (req, res) => {
    res.json({ csrfToken: generateToken(req) });
  });

  app.use(csrfSynchronisedProtection);
  app.use("/api/auth", authRouter);

  app.use(notFoundHandler);
  app.use(errorHandler);

  return app;
}

Order matters:

helmet() sets security headers on every response, including errors, so it goes first.
express.json({ limit: "16kb" }) must precede anything reading req.body, and the size limit stops a giant body from burning CPU in Argon2. Requests over the limit are rejected with 413 before any handler runs.
The session middleware must precede CSRF and routes, because both need req.session.
/api/csrf-token must be registered before csrfSynchronisedProtection. Register it after, and clients can never obtain a token for their first mutation. It's an easy mistake to make.
CSRF protection guards every unsafe request below it.
notFoundHandler and errorHandler come last.

A note if you are new to Express 5: it automatically forwards rejected promises from async handlers to the error middleware, so the route handlers above don't need try/catch around every await. That was a manual next(err) in Express 4.

src/middleware/error-handler.ts:

import type { NextFunction, Request, Response } from "express";

interface HttpErrorLike {
  code?: string;
  type?: string;
  status?: number;
  statusCode?: number;
}

export function notFoundHandler(_req: Request, res: Response): void {
  res.status(404).json({ error: "Not found" });
}

/**
 * Central error handler. It must keep all four parameters — Express detects
 * error-handling middleware by arity.
 */
export function errorHandler(
  err: unknown,
  _req: Request,
  res: Response,
  next: NextFunction,
): void {
  if (res.headersSent) {
    next(err);
    return;
  }

  const httpError = err as HttpErrorLike;

  if (httpError?.code === "EBADCSRFTOKEN") {
    res.status(403).json({ error: "Invalid or missing CSRF token" });
    return;
  }

  // body-parser marks malformed JSON with type: "entity.parse.failed".
  if (httpError?.type === "entity.parse.failed") {
    res.status(400).json({ error: "Malformed JSON body" });
    return;
  }

  // Other body-parser failures carry their own 4xx status (for example
  // "entity.too.large" -> 413 from the 16kb limit, and "encoding.unsupported"
  // -> 415). Honour it instead of reporting a server fault for a client error.
  const status = httpError?.status ?? httpError?.statusCode;
  if (typeof status === "number" && status >= 400 && status < 500) {
    res.status(status).json({
      error: httpError?.type === "entity.too.large" ? "Request body too large" : "Bad request",
    });
    return;
  }

  // Anything else is unexpected: log it server-side and return a generic
  // message so stack traces and SQL errors never reach the client.
  console.error("Unhandled error:", err);
  res.status(500).json({ error: "Internal server error" });
}

The handler maps each failure to a status: EBADCSRFTOKEN to 403, a malformed JSON body to 400, and other body-parser errors to the 4xx status they already carry, for example entity.too.large to 413 when a request exceeds the 16kb limit. Without that last branch an oversized body falls through to the generic case and is reported as a 500 server fault, which misleads the client and buries a client error in your server logs.

The error handler must keep all four parameters, because Express identifies error middleware by arity. Dropping the unused next silently turns it into ordinary middleware that never runs.

10. Entry point

import { createApp } from "./app.js";
import { config } from "./config.js";
import { sessionStore } from "./session.js";

const app = createApp();

const server = app.listen(config.PORT, () => {
  console.log(`Auth API listening on http://localhost:${config.PORT} (${config.NODE_ENV})`);
});

const PRUNE_INTERVAL_MS = 30 * 60 * 1000;
const pruneTimer = setInterval(() => {
  const removed = sessionStore.pruneExpired();
  if (removed > 0) {
    console.log(`Pruned ${removed} expired session(s)`);
  }
}, PRUNE_INTERVAL_MS);
pruneTimer.unref();

function shutdown(signal: NodeJS.Signals): void {
  console.log(`${signal} received, shutting down`);
  clearInterval(pruneTimer);
  server.close(() => {
    process.exit(0);
  });
}

process.on("SIGINT", shutdown);
process.on("SIGTERM", shutdown);

11. Tests

vitest.config.ts injects a deterministic environment, including an in-memory database so each run starts clean:

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    env: {
      NODE_ENV: "test",
      PORT: "3000",
      // 32+ characters so it passes config validation.
      SESSION_SECRET: "test-only-secret-value-please-change-me-0001",
      // In-memory SQLite: each test file gets its own throwaway database.
      DATABASE_PATH: ":memory:",
    },
  },
});

The integration tests drive the app through supertest with a cookie-persisting agent. The suite has 6 cases, and this is the whole file:

import request from "supertest";
import { describe, expect, it } from "vitest";
import { createApp } from "../src/app.js";
import { db } from "../src/db.js";

const app = createApp();
const VALID_PASSWORD = "correct horse battery staple";

type Agent = ReturnType<typeof request.agent>;

function setCookieHeaders(res: request.Response): string[] {
  const raw = res.headers["set-cookie"];
  if (!raw) return [];
  return Array.isArray(raw) ? raw : [raw];
}

function sessionCookie(res: request.Response): string {
  const cookie = setCookieHeaders(res).find((value) => value.startsWith("sid="));
  if (!cookie) throw new Error("Response did not set a session cookie");
  return cookie;
}

async function getCsrfToken(agent: Agent): Promise<string> {
  const res = await agent.get("/api/csrf-token");
  expect(res.status).toBe(200);
  return res.body.csrfToken as string;
}

async function register(agent: Agent, email: string, password = VALID_PASSWORD) {
  const token = await getCsrfToken(agent);
  return agent.post("/api/auth/register").set("x-csrf-token", token).send({ email, password });
}

describe("auth api", () => {
  it("sets an HttpOnly, SameSite=Lax session cookie", async () => {
    const agent = request.agent(app);
    const res = await register(agent, "cookie@example.com");
    const cookie = sessionCookie(res);

    expect(cookie).toMatch(/HttpOnly/i);
    expect(cookie).toMatch(/SameSite=Lax/i);
    expect(cookie).not.toMatch(/;\s*Secure/i); // dev/test, so it also works over HTTP
  });

  it("rejects a duplicate email with 409", async () => {
    const first = request.agent(app);
    expect((await register(first, "dup@example.com")).status).toBe(201);

    const second = request.agent(app);
    const res = await register(second, "dup@example.com");
    expect(res.status).toBe(409);
  });

  it("rotates the session id on login to prevent session fixation", async () => {
    const agent = request.agent(app);
    const registered = await register(agent, "rotate@example.com");
    const before = sessionCookie(registered);

    const token = await getCsrfToken(agent);
    const loggedIn = await agent
      .post("/api/auth/login")
      .set("x-csrf-token", token)
      .send({ email: "rotate@example.com", password: VALID_PASSWORD });

    expect(loggedIn.status).toBe(200);
    expect(sessionCookie(loggedIn)).not.toBe(before);
  });

  it("rejects an unknown email with the same message as a wrong password", async () => {
    const agent = request.agent(app);
    const token = await getCsrfToken(agent);
    const res = await agent
      .post("/api/auth/login")
      .set("x-csrf-token", token)
      .send({ email: "nobody@example.com", password: VALID_PASSWORD });

    expect(res.status).toBe(401);
    expect(res.body.error).toBe("Invalid email or password");
  });

  it("blocks a state-changing request that has no token", async () => {
    const res = await request(app)
      .post("/api/auth/register")
      .send({ email: "no-csrf@example.com", password: VALID_PASSWORD });

    expect(res.status).toBe(403);
    expect(res.body.error).toMatch(/CSRF/i);
  });

  it("invalidates the session on logout", async () => {
    const agent = request.agent(app);
    await register(agent, "logout@example.com");
    expect((await agent.get("/api/auth/me")).status).toBe(200);

    const token = await getCsrfToken(agent);
    expect((await agent.post("/api/auth/logout").set("x-csrf-token", token)).status).toBe(204);
    expect((await agent.get("/api/auth/me")).status).toBe(401);
  });
});

My first version of the fourth test failed with TypeError: Cannot read properties of null (reading 'address') from supertest, because I awaited the CSRF token inside the request chain. Fetching the token into a variable first, as the test above does, fixes it.

Run it:

npm test

Expected result on this codebase:

 Test Files  1 passed (1)
      Tests  6 passed (6)
   Duration  808ms (import 45%, tests 43%, transform 11%, worker 1%)

Durations differ between machines; the counts are what matter. Also run npm run typecheck (which must exit 0) and npm run build before deploying anywhere; build compiles src to dist/ via tsconfig.build.json.

12. Trying it by hand

With npm run dev running, this curl sequence exercises the whole flow. The cookie jar is what makes the session persist across calls.

JAR=$(mktemp); B=http://localhost:3000

# 1. Grab a CSRF token; the cookie jar now holds the session cookie.
TOKEN=$(curl -s -c "$JAR" $B/api/csrf-token | sed -E 's/.*"csrfToken":"([^"]+)".*/\1/')

# 2. Register (201)
curl -s -b "$JAR" -c "$JAR" -X POST $B/api/auth/register \
  -H 'Content-Type: application/json' -H "x-csrf-token: $TOKEN" \
  -d '{"email":"me@example.com","password":"correct horse battery staple"}'

# 3. Get a fresh token (the session was rotated) and read the profile (200)
TOKEN=$(curl -s -b "$JAR" -c "$JAR" $B/api/csrf-token | sed -E 's/.*"csrfToken":"([^"]+)".*/\1/')
curl -s -b "$JAR" $B/api/auth/me

# 4. Logout (204), then confirm access is gone (401)
curl -s -o /dev/null -w '%{http_code}\n' -b "$JAR" -c "$JAR" -X POST $B/api/auth/logout -H "x-csrf-token: $TOKEN"
curl -s -o /dev/null -w '%{http_code}\n' -b "$JAR" $B/api/auth/me

Output from this project, including the Set-Cookie header (session ID shortened):

Set-Cookie: sid=s%3A<id>.<signature>; Path=/; Expires=Wed, 14 Oct 2026 19:53:24 GMT; HttpOnly; SameSite=Lax

Note there is no Secure flag because NODE_ENV=development. Set NODE_ENV=production, terminate TLS, and the cookie becomes __Host-sid=...; Secure; HttpOnly; SameSite=Lax.

Common mistakes and troubleshooting

"403 on every POST, even with a token." Three usual causes. The token endpoint is registered after csrfSynchronisedProtection. Or the client is reading csrfToken from the wrong place. Or the client is sending the token as a cookie or a query parameter instead of the x-csrf-token header.

"Login succeeds but the very next mutation fails with 403." That's expected. Login regenerates the session, which discards the CSRF token. Fetch a new token after authenticating.

"The cookie is set but never sent back." Check, in order: secure: true over plain HTTP (the browser drops it, with a localhost exception); sameSite: "strict" breaking a top-level navigation from another origin; a domain mismatch; or a cross-origin client that is not sending credentials. For fetch calls, credentials: "include" is required, along with explicit CORS Access-Control-Allow-Credentials: true and a specific origin, because * is not allowed with credentials.

"req.session is undefined in a route." The session middleware is registered after the route, or after CSRF. Both need it, so it must come first.

"Users get logged out randomly." resave and saveUninitialized are usually to blame, or the store is not saving. With saveUninitialized: false, a session is only created when it is actually modified, which is correct for login flows.

"Argon2 install fails." argon2 and better-sqlite3 are native modules. Most platforms get prebuilt binaries; if not, the resolution is a working build toolchain, not a switch to a pure-JS hash.

"JSON.parse throws inside the session store." If you changed the stored shape, clear the sessions table. A schema change to session data effectively logs everyone out.

"SESSION_SECRET must be at least 32 characters" on boot. That message comes from the config validator. Generate a value rather than inventing one. It also fires if SESSION_SECRET is left blank in your .env.

What this tutorial does not cover

This is not a finished product. Deliberately out of scope:

Registration discloses whether an email is registered. POST /api/auth/register answers 409 for an email that already exists, so anyone can probe the endpoint for accounts. Login is protected against this; registration is not, because the answer the caller wants is also the answer that makes the API useful. Hiding it requires moving account creation behind an email-verification step.
Rate limiting, lockout, and hashing cost. Nothing here slows down credential stuffing. Add per-IP and per-account throttling (for example express-rate-limit) and alert on repeated failures. Argon2id is expensive by design, so a burst of login attempts can exhaust worker capacity. The 16kb body limit and the 200-character password cap bound one request's input; they don't bound the request rate, which is the rate limiter's job.
Email verification, password reset, and MFA. Email verification and password reset both need a token with its own single-use, expiring lifecycle, and MFA should be added before anything else.
Anonymous session rows. Every GET /api/csrf-token without a cookie creates a row, and nothing limits how many. Three cookie-less calls added three rows to my sessions table. My first draft's comment claimed anonymous visitors don't get a session.
No absolute session lifetime. rolling: true slides the expiry forward on every authenticated request, so an active session never expires on its own.
No breached-password check. SP 800-63B-4 says passwords SHALL be compared against a blocklist; this code doesn't.
Secret rotation, audit logging, and observability. OWASP's session guidance covers renewing session IDs and detecting session-related attacks; this code does neither. There are no metrics, no tracing, and no structured logging.
Scaling. SQLite is a single-writer database. It is a fine fit for one process or one machine, and it is the wrong fit for horizontal scaling. The store interface is the seam: swap in Redis or Postgres.
__Host- prefix in development. It requires HTTPS, which is why it is production-only here. If you add local TLS, use it everywhere.

One more thing: disabling CSRF protection because "it is only an API" is not a mitigation. If your API is called from a browser with a cookie, it is a CSRF target.

Conclusion

The difference between "we added login" and "we added authentication" is a short list of decisions: hash with Argon2id at OWASP's parameters, keep session state on the server, mark the cookie HttpOnly and Secure, add SameSite, protect unsafe methods with a synchronizer token, regenerate the session ID on login, and make login fail the same way for an unknown email and a wrong password so it doesn't leak which accounts exist (registration still does, see the limitations).

The complete, runnable project, including the SQLite session store and all 6 tests, is at secure-auth-demo. npm install && npm test should print 6 passed.

References

OWASP Password Storage Cheat Sheet - Argon2id parameters, bcrypt caveats, scrypt and PBKDF2 guidance
OWASP Session Management Cheat Sheet - session ID entropy, cookie attributes, __Host- prefix, session renewal and destruction
OWASP Cross-Site Request Forgery Prevention Cheat Sheet - synchronizer token pattern, token transmission, SameSite as defense in depth
MDN: Set-Cookie header - exact semantics of HttpOnly, Secure, and SameSite
MDN: Using HTTP cookies - cookie scope, lifetime, and security
Node.js CLI documentation (--env-file) - env file loading and precedence
Node.js releases - which Node versions are LTS
TypeScript Node target mapping - target, lib, and module for Node 22
TypeScript module option - NodeNext semantics
Express 5 migration guide - promise rejection handling for async handlers
Express: retiring legacy packages - why csurf is deprecated
express-session on npm - MemoryStore is not production-ready
csrf-sync on npm - synchronizer token pattern for sessions
argon2 on npm - hashing and verification API
better-sqlite3 on npm - synchronous SQLite for Node
NIST SP 800-63B-4 - password length and memorized-secret guidance

Why Your Node.js API Is Slow in Production: 10 Mistakes That Pass Code Review

Loknath Patel — Mon, 12 Oct 2026 04:29:39 +0000

Spot the bug in 10 seconds:

const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 1000);

const res = await fetch(url, { signal: controller.signal });
clearTimeout(timer);
const body = await res.text();

The timeout is 1 second. The server sends its headers right away, then stalls the body for 3 seconds. I ran this on Node.js 22 and it waited 3.06 seconds. No error. No timeout. Nothing in the logs.

Found it? The answer is in Mistake 8. First, a picture of why bugs like this hurt so much.

Imagine a chai tapri with one counter and one person serving. A customer reaches the counter and spends five minutes counting coins. Everyone behind him waits too, even the person who only wants a 10-rupee chai. Nobody crashes. Nobody shouts. The line just gets longer.

That is your Node.js event loop. Your JavaScript runs on one thread, and one slow operation delays every request in the queue. Most mistakes below are variations of that picture: some block the counter, some wait forever with no timeout, some send the same order to the kitchen 100 times.

I reproduced ten mistakes like these on Node.js 22. They look fine in code review, they throw no errors, and they only hurt under real traffic. A few results from my tests:

A /fast route that took 190 ms instead of 0.7 ms because a different request was running (Mistake 1).
A cache that read the same file 100 times for 100 concurrent requests instead of once (Mistake 7).
An event-loop monitor that printed 20365311 ms of lag on a completely idle server (explained in the next section).

Every snippet marked Tested has a script you can run in the companion repo. Database and framework snippets are illustrative: names like pool, app and getUser stand in for your own code, and they were not run against a real database.

The golden rule: measure first

Optimizing without measuring is guessing. Start with a timer around suspicious code:

const { performance } = require('node:perf_hooks');

async function timedRoute(label, fn) {
  const start = performance.now();
  const result = await fn();
  console.log(`[PERF] ${label}: ${(performance.now() - start).toFixed(1)}ms`);
  return result;
}

Node ships more in perf_hooks: performance.now(), PerformanceObserver, performance.eventLoopUtilization() and monitorEventLoopDelay().

Timers only tell you how long something took. For the bigger picture, use a profiler and a load test:

node --cpu-prof server.js writes a .cpuprofile file when the process exits. Open it in Chrome DevTools.
Clinic.js draws flame graphs from a running app.
npx autocannon -c 100 -d 30 http://localhost:3000/your-route shows latency under 100 concurrent connections. Many bugs below only show up under concurrency.

The 20365311 gotcha

The docs say monitorEventLoopDelay() reports delays in nanoseconds. On an idle Node 22 process with resolution: 20, my p99 was 20,316,159. That is nanoseconds, about 20.3 ms. Print it with an ms label and you get twenty million milliseconds of lag, over five hours, on a server doing nothing. That was the number in the intro.

The 20 ms is not real lag. The values appear to include the sampling interval, so convert to milliseconds and subtract the resolution:

const { monitorEventLoopDelay } = require('node:perf_hooks');

const RESOLUTION_MS = 20;
const h = monitorEventLoopDelay({ resolution: RESOLUTION_MS });
h.enable();

setInterval(() => {
  const toMs = (ns) => ns / 1e6;
  const p99 = Math.max(0, toMs(h.percentile(99)) - RESOLUTION_MS);
  const max = Math.max(0, toMs(h.max) - RESOLUTION_MS);
  console.log(`event loop lag: p99 ~ ${p99.toFixed(1)}ms, max ~ ${max.toFixed(1)}ms`);
  h.reset();
}, 10_000).unref();

Tested: with this 10-second window and one deliberate 300 ms synchronous block, p99 stayed around 0.6 ms while max reported about 297 ms. The window held about 476 samples, so a single stall is one sample and p99 can miss it. Watch max (or use a shorter window) as well, and pick alert thresholds from your own baseline.

Each mistake below has an Impact tag. These are my judgment, not a measurement: Outage-level can take the whole service down, High means large latency or load that grows with your data or traffic, and Medium is wasteful and noticeable at scale.

1. One slow function freezes every request

Impact: Outage-level.

Node runs your JavaScript on one thread. A synchronous operation inside a request handler delays every other request, not just the current one. Typical culprits are fs.readFileSync(), crypto.pbkdf2Sync(), huge JSON.parse() / JSON.stringify() calls, and heavy loops or regexes.

Tested: I ran a server in one process and a load generator in another. A pbkdf2Sync call took about 235 ms by itself. While it ran, requests to an unrelated /fast route had a median latency of 190 ms and a worst case of 233 ms. With the async pbkdf2, the same /fast route stayed at a median of 0.7 ms. Same work, same machine. The only difference is whether the counter was blocked.

Fixes

Do synchronous work once at startup. readFileSync at boot is fine.
At runtime, use the async APIs. crypto.pbkdf2, fs.promises, zlib and similar calls run on libuv's thread pool (4 threads by default, so it is small, not unlimited).
For CPU-bound work you cannot make async, move it to worker_threads. Do not spawn a worker per request; use a pool such as Piscina.

const { Worker } = require('node:worker_threads');

function runInWorker(file, data) {
  return new Promise((resolve, reject) => {
    const w = new Worker(file, { workerData: data });
    w.once('message', resolve);
    w.once('error', reject);
    w.once('exit', (code) => {
      if (code !== 0) reject(new Error(`worker exited with code ${code}`));
    });
  });
}

A caveat: reading a small file synchronously from a local disk is cheap. Blocking becomes a real problem with large files, slow or network disks, and heavy CPU work, so measure before you rewrite.

Blocking is the famous one. The next one is the most common bug in database-backed APIs, and it hides behind code that reads well.

2. The N+1 query: one endpoint, one query per row

Impact: High.

You load a list, then run one more query per item. The code looks clean and the database suffers.

// N+1: 1 query for orders + 1 query per order
async function getUserOrders(userId) {
  const { rows: orders } = await pool.query(
    'SELECT * FROM orders WHERE user_id = $1', [userId]
  );
  for (const order of orders) {
    const { rows } = await pool.query(
      'SELECT * FROM order_items WHERE order_id = $1', [order.id]
    );
    order.items = rows;
  }
  return orders;
}

Batch the child lookup so the query count stays at two, however many orders there are:

async function getUserOrders(userId) {
  const { rows: orders } = await pool.query(
    'SELECT id, status, total FROM orders WHERE user_id = $1', [userId]
  );
  if (orders.length === 0) return [];

  const { rows: items } = await pool.query(
    'SELECT * FROM order_items WHERE order_id = ANY($1)',
    [orders.map((o) => o.id)]
  );

  const byOrder = new Map();
  for (const item of items) {
    if (!byOrder.has(item.order_id)) byOrder.set(item.order_id, []);
    byOrder.get(item.order_id).push(item);
  }
  return orders.map((o) => ({ ...o, items: byOrder.get(o.id) ?? [] }));
}

A single JOIN also works, but it repeats parent columns on every child row, so you have to regroup the rows. In GraphQL servers, DataLoader batches per-tick lookups for you.

With an ORM, N+1 hides behind property access: order.items looks like a field but fires a query. Use eager loading (include in Prisma and Sequelize) and read the SQL log once to confirm.

How to find it: log how many queries each request runs. A request that suddenly runs hundreds is the signal. Some APM tools flag repeated query patterns automatically, and this Scout write-up shows one way to detect it with Prisma.

3. Sending columns nobody reads

Impact: Medium.

SELECT *, or returning a whole ORM document, sends columns the client never uses. That costs database I/O, network bytes and serialization time, and it can leak fields you never meant to expose.

app.get('/api/users/:id', async (req, res) => {
  const { rows } = await pool.query(
    'SELECT id, username, profile_image_url, created_at FROM users WHERE id = $1',
    [req.params.id]
  );
  res.json(rows[0] ?? null);
});

I did not measure the database side, but I can measure what the extra columns do to the response. Tested with synthetic rows: 10,000 rows with 4 fields serialize to 1.27 MB in about 3 ms. The same rows with 30 fields are 11.7 MB and take about 55 ms. That is roughly 9 times the bytes and 19 times the event-loop time, and the client only needed 4 fields.

That serialization time is the bridge to Mistake 10. First, a mistake that costs you latency without blocking anything.

4. Serial await that should run in parallel

Impact: Medium.

Independent calls should run together. Sequential:

// Total time is the sum of all three
const user = await getUser(id);
const orders = await getOrders(id);
const prefs = await getPreferences(id);

Parallel:

// Total time is about the slowest one
const [user, orders, prefs] = await Promise.all([
  getUser(id), getOrders(id), getPreferences(id),
]);

Tested with three simulated 200 ms calls: sequential took about 602 ms, Promise.all about 201 ms.

Things to watch:

Only parallelize independent work. A checkout flow like validate cart, calculate totals, create order, charge payment is dependent: each step needs the previous result, so it must stay sequential.
await does not block the event loop. The cost of serial awaits is latency for that one request.
Promise.all rejects as soon as one promise rejects, and the others keep running (they are not cancelled). Use Promise.allSettled when you need every result.
Parallel queries each take a pool connection, so a high fan-out can exhaust a small pool (Mistake 6).

Three of these ten can take a whole service down, not just slow it. You have already seen one: Mistake 1. The other two are Mistake 6 and Mistake 8. But the next one is the one that gets quietly worse every month, until the day it does not.

5. The query that was fine at 100 rows

Impact: High.

A query that filters, joins or sorts on an unindexed column scans the whole table. That is fine at 100 rows and painful at millions. Confirm with EXPLAIN ANALYZE:

EXPLAIN ANALYZE SELECT id, status, total FROM orders WHERE customer_id = 42;
-- Seq Scan on orders  -> consider an index

CREATE INDEX CONCURRENTLY idx_orders_customer_id ON orders (customer_id);
-- run EXPLAIN ANALYZE again: look for an Index Scan

Indexes are not free. They use disk space and slow down writes, so add the ones your real queries need and verify they are used.

CONCURRENTLY avoids blocking writes while building an index on a live table, but it cannot run inside a transaction block (see the PostgreSQL docs). Many migration tools wrap each migration in a transaction, so mark that migration as non-transactional.

Also remember that EXPLAIN ANALYZE actually runs the query. For INSERT, UPDATE or DELETE, use plain EXPLAIN or run it inside a transaction you roll back.

6. A new database connection per request

Impact: Outage-level.

PostgreSQL (pg): create one pool at startup and reuse it. Never create a Client or Pool per request. And set the timeouts, because the defaults wait forever.

const { Pool } = require('pg');

const pool = new Pool({
  max: 10,                        // per process. See the math below
  connectionTimeoutMillis: 5_000, // fail fast if no connection is free (default 0 = wait forever)
  statement_timeout: 10_000,      // the server cancels any query running longer than 10 s
});

// An idle client can error (for example when the database restarts).
// Without a listener, that unhandled 'error' event can crash the process.
pool.on('error', (err) => console.error('idle pg client error:', err.message));

app.get('/data', async (req, res) => {
  const { rows } = await pool.query('SELECT id, name FROM users LIMIT 50');
  res.json(rows);
});

For transactions or multi-statement work, check out a client and always release it. If ROLLBACK itself fails, the connection is in an unknown state. The node-postgres docs say that passing true to release() makes the pool destroy that client instead of reusing it:

async function transfer(a, b, amount) {
  const client = await pool.connect();
  let destroy = false;
  try {
    await client.query('BEGIN');
    // ... statements ...
    await client.query('COMMIT');
  } catch (err) {
    try {
      await client.query('ROLLBACK');
    } catch (rollbackErr) {
      destroy = true; // do not return a broken client to the pool
      console.error('ROLLBACK failed:', rollbackErr.message);
    }
    throw err; // always surface the original error
  } finally {
    client.release(destroy);
  }
}

The production math nobody does in dev

The pool limit is per process. Postgres has one global limit. If you run 10 instances with max: 20, that is 200 connections, and Postgres' default max_connections is typically 100 (it can be lower on some systems). Autoscaling multiplies the problem exactly when traffic is highest. Pick max so that instances x max stays under the database limit with headroom, or put a pooler like PgBouncer in front.

Connections are not free on the server either: each one is a separate Postgres process, and memory per connection depends on your workload (see this PGConf talk). Keep the count bounded and pooled. See the node-postgres pool docs for every option.

MongoDB: every MongoClient already contains a connection pool (default maxPoolSize is 100). The mistake is creating a new client per request. The driver docs say to create one client and reuse it for all operations in a process.

Two of the three outage-level mistakes are behind us. The third is the puzzle from the top. But first, a mistake that makes everything above cheaper.

7. Recomputing the same thing on every request

Impact: Medium.

If every request recomputes or refetches the same data, you pay for it on every request. Cache in layers:

In-process for small, hot, read-mostly data such as config and reference tables.
A shared cache (for example Redis) when several instances need the same data.
HTTP caching (Cache-Control, ETag) for browsers and CDNs.

But the obvious in-process cache has a trap. Here is a feature-flag loader that looks correct:

let cache = null;

async function loadFlags() {
  if (cache) return cache;
  cache = JSON.parse(await fs.readFile('/etc/app/feature-flags.json', 'utf8'));
  return cache;
}

The value is stored only after the await. Every request that arrives while the first read is still running starts its own read. This is a cache stampede. Tested: 100 concurrent callers on a cold cache caused 100 file reads. Caching the promise instead caused 1.

Here is a small in-process cache that caches the promise, de-duplicates in-flight calls, evicts the least recently used entry, bounds its own size, and stops sharing a call that never finishes (pendingMs, which you should set above your function's own timeout from Mistake 8):

function cached(fn, ttlMs, { maxEntries = 1000, pendingMs = 30_000 } = {}) {
  const store = new Map(); // insertion order = least recently used first

  return (key) => {
    const now = Date.now();
    const hit = store.get(key);
    if (hit && hit.expires > now) {            // pending entries expire after pendingMs
      store.delete(key); store.set(key, hit);  // touch: move to most recently used
      return hit.promise;
    }

    const entry = { promise: null, expires: now + pendingMs };
    // new Promise(...) also turns a synchronous throw from fn into a rejection
    entry.promise = new Promise((resolve) => resolve(fn(key))).then((value) => {
      entry.expires = Date.now() + ttlMs;      // the TTL starts when the call finishes
      return value;
    });

    store.delete(key);
    store.set(key, entry);
    if (store.size > maxEntries) store.delete(store.keys().next().value); // evict LRU

    // never cache failures, and never delete a newer entry for the same key
    entry.promise.catch(() => { if (store.get(key) === entry) store.delete(key); });
    return entry.promise;
  };
}

const getUserCached = cached(loadUserFromDb, 5_000);

Tested:

100 concurrent calls for the same key triggered 1 underlying call.
After 10,000 distinct keys with maxEntries: 100, only the last 100 were still cached.
A hot key that is read again survives eviction; a cold key does not (LRU, not FIFO).
With a 600 ms call and a 400 ms TTL, a second call right after completion was a cache hit. If the TTL started when the call started, any call slower than its TTL would be expired the moment it finished.
A failed call is not cached, and a slow old failure does not delete a newer entry for the same key.
A call that never finishes is shared only for pendingMs. After that, the next caller starts a fresh call instead of waiting on a hung promise forever.

Caching has costs. Decide how stale data may be, how entries are invalidated, and how big the cache may grow. With several instances, in-process caches can disagree with each other.

Caching protects you from slow dependencies. The next mistake is about dependencies that never answer at all.

8. Outbound calls with no timeout, or a leaky one

Impact: Outage-level.

Here is the answer to the puzzle at the top. If you call clearTimeout as soon as fetch resolves, the timeout no longer covers reading the body:

// Timer is cleared when headers arrive, so a stalled body is NOT covered
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 1000);
const res = await fetch(url, { signal: controller.signal });
clearTimeout(timer);
await res.text();

fetch() resolves when the headers arrive. The body is a separate stream, and it is still being read after your timer is gone.

Tested against a server that sends headers, then stalls the body for 3 seconds, with a 1-second timeout:

Pattern	Result
Manual timer, cleared right after `fetch`	finished after 3.06 s, no timeout applied
`AbortSignal.timeout(1000)`	aborted after 1.00 s with a `TimeoutError`
Manual timer, cleared in `finally` after the body	aborted after 1.00 s with an `AbortError`

The simplest fix is the built-in signal:

const res = await fetch('https://api.example.com/data', {
  signal: AbortSignal.timeout(5_000),
});
const data = await res.json();

If you prefer a manual AbortController, clear the timer only after the body is fully read:

async function fetchText(url, ms = 5_000) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), ms);
  try {
    const res = await fetch(url, { signal: controller.signal });
    return await res.text(); // the timer still covers reading the body
  } finally {
    clearTimeout(timer);
  }
}

Every outbound call means the database too. Mistake 6 showed connectionTimeoutMillis and statement_timeout. A query without a timeout is the same bug as a fetch without one.

Good to know: Node's built-in fetch (undici) defaults to 300 s for both the headers timeout and the body timeout, so a stuck request will not hang forever, but five minutes is far too long for most APIs. On the server side, Node 22's http.createServer() defaults to requestTimeout 300000 ms and headersTimeout 60000 ms. Review them for your traffic.

That was the last outage-level one. The remaining mistakes are about memory and CPU, starting with a very common way to waste both.

9. Loading a whole file into memory just to send it

Impact: Medium.

This looks harmless:

app.get('/download', async (req, res) => {
  const data = await fs.promises.readFile('./large-file.zip'); // whole file in memory, per request
  res.send(data);
});

readFile is asynchronous, so it does not block the event loop, but it loads the whole file into memory for every concurrent request. If you are just serving a file from disk, Express's res.sendFile() and res.download() already stream it. When you need your own logic, stream with pipeline() so errors are handled and streams are cleaned up:

const fs = require('node:fs');
const { pipeline } = require('node:stream/promises');

app.get('/download', async (req, res, next) => {
  try {
    await fs.promises.stat('./large-file.zip'); // 404 before streaming starts
    res.setHeader('Content-Type', 'application/zip');
    await pipeline(fs.createReadStream('./large-file.zip'), res);
  } catch (err) {
    if (res.headersSent) {
      // too late for a status code; pipeline already closed the response.
      // A client closing the tab mid-download is normal, so do not log it as an error.
      if (err.code !== 'ERR_STREAM_PREMATURE_CLOSE') console.error('stream failed:', err.code);
      return;
    }
    if (err.code === 'ENOENT') return res.status(404).end('not found');
    next(err);
  }
});

Tested with a plain Node http server:

A missing file returned 404, and a 5 MB file streamed completely (5,242,880 bytes).
When the client disconnected mid-download, pipeline() rejected with ERR_STREAM_PREMATURE_CLOSE after the headers had already been sent. That is why the catch checks res.headersSent before trying to send a status.
With fs.createReadStream(missing).pipe(res), the same missing file crashed the process with an unhandled ENOENT error event, because pipe() does not forward errors. pipeline() does.

Both pipe() and pipeline() handle backpressure for you. Checking the return value of write() is only needed when you call write() manually.

Streaming helps with big files. Big JSON has the same shape of problem, but it blocks the loop instead of filling memory.

10. Serializing big JSON on the event loop

Impact: Medium.

JSON.stringify() is synchronous. A very large response blocks the event loop for the whole time it serializes, which is Mistake 1 in disguise. Tested, median of several runs on a 1 vCPU test box:

Payload	Rows	`JSON.stringify` time
0.12 MB	1,000 rows, 4 fields	0.2 ms
1.27 MB	10,000 rows, 4 fields	2.9 ms
11.7 MB	10,000 rows, 30 fields	54.5 ms
13.0 MB	100,000 rows, 4 fields	43 ms
119.9 MB	100,000 rows, 30 fields	573 ms

That is roughly 3 to 5 ms of blocked event loop per MB on this machine. Your hardware will differ, so run the script on yours. A 120 MB response blocks the counter for over half a second, and every other request waits.

The first fixes are boring, and they work:

Return fewer fields (Mistake 3).
Paginate. Do not return 100,000 rows from a list endpoint.
For exports, stream the rows (for example as NDJSON) instead of building one giant array.
For rare, genuinely huge payloads, serialize in a worker thread.

Schema-based serializers such as fast-json-stringify (used by Fastify for response schemas) are often suggested. In my test, with one simple 4-field schema, it was slower than plain JSON.stringify at every size I tried, for example about 196 ms against 29 ms at 100,000 rows. That does not mean it is slow in general. It means one schema on one machine did not show a gain, so benchmark your own payloads before adopting it.

Bonus 1: AsyncLocalStorage is not free

AsyncLocalStorage is the standard way to carry request context (request IDs, tenants, tracing) without passing it through every function. Do not trust a client-supplied ID blindly: it ends up in your logs, so validate its shape and length.

const { AsyncLocalStorage } = require('node:async_hooks');
const crypto = require('node:crypto');

const requestContext = new AsyncLocalStorage();
const SAFE_ID = /^[A-Za-z0-9._-]{1,64}$/;

app.use((req, res, next) => {
  const incoming = req.headers['x-request-id'];
  const requestId = typeof incoming === 'string' && SAFE_ID.test(incoming)
    ? incoming
    : crypto.randomUUID();
  requestContext.run({ requestId }, next);
});

function log(message) {
  const ctx = requestContext.getStore();
  console.log(`[${ctx?.requestId}] ${message}`);
}

Tested: two concurrent requests each logged their own request ID, and a header containing spaces and a tab was replaced with a generated UUID.

On cost, benchmark conditions matter. Platformatic's benchmark (a simple HTTP server, 100 connections) measured AsyncLocalStorage at about 93% of baseline throughput on Node 24.4.1, roughly 7% overhead, and about 90% on Node 22.17.1, roughly 10%. I did not reproduce those numbers. A micro-benchmark that isolates the primitive will show a larger percentage. Measure it inside your own app before deciding.

Bonus 2: Async errors in Express 4 vs Express 5

In Express 5, a rejected promise from an async handler is passed to your error handler automatically (see the migration guide). Express 4 does not do that.

Tested on Node 22 with Express 4: an async handler that throws did not reach the error middleware. The client got a dropped connection, and the whole server process exited with code 1, because Node terminates the process on an unhandled promise rejection by default. If you installed an unhandledRejection listener, you would see the other symptom instead: a request that hangs until a timeout.

On Express 4, wrap your async handlers:

const asyncHandler = (fn) => (req, res, next) =>
  Promise.resolve(fn(req, res, next)).catch(next);

app.get('/users/:id', asyncHandler(async (req, res) => {
  const user = await getUser(req.params.id);
  if (!user) return res.status(404).json({ error: 'not_found' });
  res.json(user);
}));

Bonus 3: Framework benchmarks are not your benchmarks

Fastify's README says its headline throughput numbers come from a synthetic hello-world benchmark that measures framework overhead only. Those numbers say little about an endpoint that spends its time waiting on a database. Benchmark your own routes before switching frameworks.

Back to the puzzle

The 1-second timeout that waited 3.06 seconds was Mistake 8: the timer was cleared as soon as the headers arrived. The 20365311 "milliseconds" of lag was nanoseconds, about 20.3 ms, mostly the sampling interval. The cache that read a file 100 times was Mistake 7. And the /fast route that took 190 ms instead of 0.7 ms was one synchronous call in someone else's handler.

If you only have an hour in your own codebase, here is the order I would check them, based on my impact tags and not on any benchmark of your system:

Timeouts (8 and 6). Search for every fetch, HTTP client and database call. Does each one have a timeout that covers the whole response?
Pool math (6). Multiply instances by max and compare it with the database limit.
Event loop lag (1). Add the monitor from the start of this article and alert on max, not only p99.

Quick checklist

No synchronous I/O or heavy CPU work in request handlers. Monitor event loop max.
Batch child queries (no N+1), including the ones your ORM hides.
Select only the columns you return.
Parallelize only independent work.
Index what you filter, join and sort on, and verify with EXPLAIN ANALYZE.
One pool or client per process, with pool.on('error'), connectionTimeoutMillis, statement_timeout, and instances x max under the database limit.
Cache the promise, not just the value: TTL, in-flight de-duplication, LRU and a size cap, plus a plan for staleness and invalidation.
A timeout on every outbound call, including the body and including the database.
Stream large responses with pipeline().
Paginate big responses and benchmark serializers on your own data.

Do you still install uuid, qs or Moment out of habit? I checked 10 built-in browser APIs against MDN and tested the examples in Chrome, and noted when to keep the package.

Loknath Patel — Sun, 11 Oct 2026 03:56:30 +0000

Loknath Patel

Oct 11

10 Browser APIs That Can Replace npm Packages (and When They Can't)

#javascript #webdev #frontend #tutorial

8 min read

10 Browser APIs That Can Replace npm Packages (and When They Can't)

Loknath Patel — Sun, 11 Oct 2026 03:53:43 +0000

Many of us type npm install without thinking twice. But browsers keep adding built-in APIs that can handle tasks we once needed a package for. Sometimes, those packages stay in our projects simply because nobody stopped to check whether we still need them.

I checked these 10 APIs against MDN and the web-platform-dx web-features data. I also tested the key parts of each example in the Chrome DevTools console on desktop. For each API, you'll see what it can replace, how to use it, where it falls short, and its Baseline support status.

A quick note on Baseline: "Newly available" means a feature works in the latest versions of all major browsers. "Widely available" means it's been supported across those browsers for a while.

This isn't an argument against using dependencies. It's about knowing what's already available before adding another package to your project.

Check the platform first, then decide.

1. `structuredClone()` replaces lodash `cloneDeep`

Deep cloning JavaScript objects used to mean either reaching for JSON.parse(JSON.stringify(obj)) or installing lodash. The JSON approach has its own problems: Dates become strings, Maps and Sets lose their contents, and circular references cause errors.

For supported data types, structuredClone() offers a built-in alternative.

// Before
import cloneDeep from 'lodash/cloneDeep';
const copy = cloneDeep(user);

// After
const copy = structuredClone(user);

It can clone Dates, Maps, Sets, Blobs, ArrayBuffers, typed arrays, and circular references.

Caveat: Functions and DOM nodes can't be cloned. If a value can't be structured-cloned, the method throws a DataCloneError. Class instances also lose their custom prototype, so their prototype methods won't be preserved. If your code depends on those behaviors, keep cloneDeep.

Support: Baseline since March 2022 (Chrome 98, Firefox 94, Safari 15.4).

2. `crypto.randomUUID()` replaces `uuid`

The uuid package is useful, but if all you need is a random v4 UUID, the browser already has a method for that.

// Before
import { v4 as uuidv4 } from 'uuid';
const id = uuidv4();

// After
const id = crypto.randomUUID();
// e.g. '36b8f84d-df4e-4d49-b662-bcde71a8764f'

That's all you need for a standard v4 UUID.

Caveat: crypto.randomUUID() only generates v4 UUIDs and requires a secure context, such as HTTPS or localhost. If you need other versions, such as v1, v5, or v7, the uuid package may still be the better choice.

Support: Baseline since March 2022.

3. `fetch()` + `AbortSignal.timeout()` replaces axios for simple requests

For straightforward HTTP requests, the built-in fetch() API can do the job without axios. You can also use AbortSignal.timeout() to set a timeout without creating your own timer.

Here's what the difference looks like:

// Before
const { data } = await axios.get('/api/users', { timeout: 5000 });

// After
try {
  const res = await fetch('/api/users', {
    signal: AbortSignal.timeout(5000),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const data = await res.json();
} catch (err) {
  if (err.name === 'TimeoutError') {
    // the request took longer than 5 seconds
  } else {
    throw err;
  }
}

There are a few differences worth knowing before switching.

Caveats:

fetch() doesn't reject its promise just because the server returns a 404 or 500 response. Check res.ok to handle HTTP errors yourself.
A timeout normally produces a TimeoutError. In Chrome 103 through 123, however, it produced an AbortError, so the TimeoutError check above won't match those versions.
If your application relies on axios interceptors, replacing axios with fetch() means implementing that behavior yourself.

Support: AbortSignal.timeout() is Baseline Newly available since April 2024 (Chrome 124, Firefox 100, Safari 16). The web-features data expects it to become Widely available on 18 October 2026.

4. `Intl.RelativeTimeFormat` replaces Moment for "time ago"

Moment is a large date library, and its own website describes it as a legacy project in maintenance mode. If you only need to display text such as "3 minutes ago", a browser API can handle the formatting.

The catch is that Intl.RelativeTimeFormat doesn't calculate the time difference or choose the right unit for you. You'll need a small helper for that.

const DIVISIONS = [
  { amount: 60, unit: 'second' },
  { amount: 60, unit: 'minute' },
  { amount: 24, unit: 'hour' },
  { amount: 7, unit: 'day' },
  { amount: 4.34524, unit: 'week' },
  { amount: 12, unit: 'month' },
  { amount: Infinity, unit: 'year' },
];

const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });

function timeAgo(date) {
  let duration = (date - Date.now()) / 1000;
  for (const { amount, unit } of DIVISIONS) {
    if (Math.abs(duration) < amount) {
      return rtf.format(Math.round(duration), unit);
    }
    duration /= amount;
  }
}

timeAgo(new Date(Date.now() - 3 * 60 * 1000)); // '3 minutes ago'

Setting numeric: 'auto' gives you natural phrases such as "yesterday" instead of "1 day ago". The formatter also supports localization.

Caveat: This only handles relative-time formatting. If you need date parsing, date arithmetic, or time-zone handling, a dedicated library is still useful. Moment's own team recommends considering alternatives such as Luxon, Day.js, and date-fns.

Support: Baseline Widely available since March 2023.

5. `URLSearchParams` replaces `qs` and `query-string` for flat query strings

If you're building or reading simple URL query strings, you may not need a separate package.

// Before
import qs from 'qs';
const query = qs.stringify({ q: 'web apis', page: 2 });

// After
const params = new URLSearchParams({ q: 'web apis', page: 2 });
params.toString(); // 'q=web+apis&page=2'

const url = new URL('https://example.com/search?q=web+apis&page=2');
url.searchParams.get('q'); // 'web apis'

URLSearchParams handles encoding and decoding query parameters for you. You can also use it through a URL object's searchParams property to read or update an existing URL.

Caveat: It doesn't serialize nested objects or arrays in the same way as qs. If your API expects bracket notation or a particular nested-query format, keep the package that handles it.

Support: Baseline Widely available.

6. `IntersectionObserver` replaces scroll listeners for visibility checks

You don't always need to listen for every scroll event just to find out whether an element is visible. IntersectionObserver notifies you when an element enters or leaves a viewport, or another observation area, without requiring you to calculate its position on every scroll.

const observer = new IntersectionObserver((entries) => {
  entries.forEach((entry) => {
    if (entry.isIntersecting) {
      entry.target.classList.add('visible');
      observer.unobserve(entry.target);
    }
  });
}, { threshold: 0.2 });

document.querySelectorAll('.card').forEach((el) => observer.observe(el));

This example adds a visible class when a card intersects the viewport, then stops observing that card.

The threshold: 0.2 option controls when the callback runs, and entry.isIntersecting only tells you the element intersects the viewport. If you need "at least 20% visible", check entry.intersectionRatio >= 0.2 instead.

You can use the same API for infinite scrolling, scroll-triggered animations, lazy loading, and visibility analytics.

Caveat: If all you need is lazy-loaded images, the native loading="lazy" attribute on an <img> element may be enough. And if you're working with React or another framework, a wrapper library can still save you some setup.

Support: Baseline Widely available since September 2021 (Chrome 58, Firefox 55, Safari 12.1).

7. `ResizeObserver` replaces window `resize` listeners for element sizes

The window's resize event tells you when the window changes size. It doesn't tell you whenever a particular element changes size.

That's where ResizeObserver comes in. It watches an element directly, making it useful for charts, dashboards, and responsive components whose dimensions can change even when the window stays the same.

const ro = new ResizeObserver((entries) => {
  for (const entry of entries) {
    console.log(entry.contentRect.width);
  }
});

ro.observe(element);

Here, the observer logs the content width whenever the observed element's size changes.

Caveat: Be careful when changing an element's dimensions inside its own resize callback. That can trigger further observations and cause a "ResizeObserver loop" warning. Handle layout updates carefully to avoid repeated changes.

Support: Baseline Widely available since January 2023 (Chrome 64, Firefox 69, Safari 13.1).

8. Page Visibility API replaces small tab-visibility helper libraries

People often leave a tab open while working somewhere else. If your application keeps polling an API or running unnecessary tasks in the background, you may be wasting resources.

The Page Visibility API lets you respond when a document becomes hidden or visible.

const video = document.querySelector('video');

document.addEventListener('visibilitychange', () => {
  if (document.hidden) {
    video.pause();
    // also stop polling here
  } else {
    // the tab is visible again: resume or refresh data
  }
});

You can use this event to pause videos, stop polling, and reduce unnecessary CPU and battery use while the page isn't visible.

Caveat: A hidden tab doesn't necessarily mean the user has left your application. They might simply be looking at another tab. Use this API to manage background work, not to decide whether a session has ended.

Support: Long established and supported in all major browsers.

9. `BroadcastChannel` replaces the `localStorage` event trick for cross-tab messages

One way to synchronize browser tabs is to write data to localStorage and listen for the storage event. It works, but there's a built-in API designed specifically for messaging between contexts: BroadcastChannel.

// Tab 1
const channel = new BroadcastChannel('app-sync');
channel.postMessage({ type: 'theme-changed', theme: 'dark' });

// Tab 2
const channel = new BroadcastChannel('app-sync');
channel.onmessage = (event) => {
  console.log(event.data); // { type: 'theme-changed', theme: 'dark' }
};

Contexts using the same channel name can exchange messages. This works across tabs, windows, iframes, and workers, provided they share the relevant origin and storage partition.

One practical example is logging a user out across all open tabs when their session ends.

Caveat: Messages only reach contexts that share the same storage partition. For example, an iframe from another site embedded in your page can't communicate through this API with a regular tab of that other site, even if both have the same origin.

Support: Baseline since March 2022 (Chrome 54, Firefox 38, Safari 15.4).

10. Clipboard API replaces `document.execCommand('copy')` and clipboard.js for copying text

If your application needs a simple "Copy" button, the modern Clipboard API can handle it without a separate library.

copyButton.addEventListener('click', async () => {
  try {
    await navigator.clipboard.writeText('Copied!');
  } catch (err) {
    console.error('Copy failed:', err);
  }
});

The writeText() method copies the supplied string to the clipboard and returns a promise, so you can handle success or failure asynchronously.

Caveat: The API requires a secure context, such as HTTPS or localhost. Clipboard access is also subject to browser permission rules and user-activation requirements. Calling it from a click handler, as shown above, is a practical approach.

Support: writeText() is Baseline Widely available since March 2020.

Quick summary

You may be installing	Built-in alternative	Keep the package if
lodash `cloneDeep`	`structuredClone()`	You need to clone functions or preserve class prototypes
`uuid`	`crypto.randomUUID()`	You need UUID versions other than v4
axios	`fetch()` + `AbortSignal.timeout()`	You rely on interceptors
Moment (time ago)	`Intl.RelativeTimeFormat`	You need parsing, date math, or time-zone support
`qs`	`URLSearchParams`	You need nested objects or arrays
Scroll listeners	`IntersectionObserver`	You want a ready-made framework wrapper
Window resize hacks	`ResizeObserver`	You need to support very old browsers
Visibility helper libraries	Page Visibility API	You need richer idle or activity detection
`localStorage` event trick	`BroadcastChannel`	You need to synchronize across devices, which requires a server
clipboard.js	Clipboard API	You must support non-HTTPS pages

These APIs aren't always direct replacements for the packages listed here. But for many everyday tasks, the browser already provides what you need. Removing an unnecessary dependency also means one less package to maintain and audit.

What this doesn't cover

Older browsers: I've included Baseline support information, but if your project targets older browsers, check caniuse.com against your actual browser requirements.
Other browsers: I tested the examples in Chrome on desktop only. Test them in the browsers your project supports before shipping.
Performance and bundle size: I haven't benchmarked these alternatives. Check Bundlephobia or your own build output if you want actual bundle-size numbers.
Why these packages exist: qs supports nested query strings, axios offers interceptors, and date libraries handle parsing and time zones. The point isn't to remove every dependency. It's to understand what you're installing and why.

Which package have you replaced with a browser API recently? And did the native alternative cover everything you needed, or did you run into a limitation? Let me know in the comments.

7 Node.js Built-in Features That Can Replace npm Packages

Loknath Patel — Sat, 10 Oct 2026 11:04:08 +0000

Fewer dependencies, faster installs, and less third-party code to trust.

Every package you install is also a package you have to update, audit and trust, along with everything that package depends on. Many popular packages were created to fill gaps that Node.js had at the time. Some of those gaps have since closed.

This article covers seven built-in features that handle the most common jobs of well-known packages. For each one you get the package it replaces, a short working example, and the cases where the package is still the better choice.

Which Node.js version? The examples target Node.js 24 (LTS). Node.js 26 enters LTS in October 2026, and Node.js 22 stays in maintenance until April 30, 2027. When a feature differs on Node.js 22, I say so.

A quick note on stability. Node.js marks every API with a stability index. Stability 2 means stable. Stability 1 means experimental, which means it can change in a minor release. I only picked features that are stable on recent Node.js 24 releases (24.12 or later).

1. `fetch()` instead of `axios` or `node-fetch`

For years, making an HTTP request in Node.js meant installing a package. Now the same fetch() you use in the browser is available as a global:

const res = await fetch('https://api.github.com/repos/nodejs/node', {
  headers: { Accept: 'application/vnd.github+json' },
  signal: AbortSignal.timeout(5000), // give up after 5 seconds
});

if (!res.ok) {
  throw new Error(`Request failed with status ${res.status}`);
}

const repo = await res.json();
console.log(repo.full_name, repo.stargazers_count);

Where the package still wins: fetch() does not throw on a 404 or 500 response, so you have to check res.ok yourself, as in the example above. There is also no built-in equivalent of axios interceptors or automatic retries. If you attach an auth header to every request in one place, a small wrapper function or axios is still convenient.

Version note: stable since Node.js 21.0.0.

2. `node:test` instead of Jest or Mocha

Node.js ships with a test runner and an assertion library, so your first test needs no config file and no install.

Suppose you have a small helper:

// slugify.js
export function slugify(text) {
  return text
    .toLowerCase()
    .trim()
    .replace(/[^a-z0-9]+/g, '-')
    .replace(/^-+|-+$/g, '');
}

And a test file next to it:

// slugify.test.js
import { describe, it } from 'node:test';
import assert from 'node:assert/strict';
import { slugify } from './slugify.js';

describe('slugify', () => {
  it('lowercases text and joins words with dashes', () => {
    assert.equal(slugify('Hello Node World'), 'hello-node-world');
  });

  it('removes leading and trailing separators', () => {
    assert.equal(slugify('  --Hi!--  '), 'hi');
  });
});

Run it with:

node --test

Node.js finds files named like *.test.js on its own. (These examples use ES modules, so set "type": "module" in your package.json or use the .mjs extension.)

Where the package still wins: code coverage is enabled with the --experimental-test-coverage flag, and mocking whole modules with mock.module() is still experimental (Stability 1.0) and needs the --experimental-test-module-mocks flag. If your test suite depends heavily on module mocking, keep Jest for now.

Version note: stable since Node.js 20.0.0.

3. `node --watch` instead of `nodemon`

Restarting your server every time you save a file is one of the oldest reasons to install nodemon. Node.js now does this with one flag.

// server.js
import { createServer } from 'node:http';

createServer((req, res) => {
  res.end('Hello from Node.js');
}).listen(3000);

{
  "scripts": {
    "dev": "node --watch server.js"
  }
}

Run npm run dev, edit server.js, and the process restarts automatically.

Where the package still wins: by default, Node.js watches the entry file and the modules it imports. A JSON file, a template or a .env file that you read at runtime will not trigger a restart. The --watch-path flag lets you choose which paths are watched, but it replaces the default module watching instead of adding to it. The official docs also list --watch-path as supported only on macOS and Windows, so test it on your platform. --watch also needs a file to run, so it cannot be combined with --run. nodemon lets you configure extensions, ignore lists and delays.

Version note: stable since Node.js 22.0.0 (and 20.13.0).

4. `--env-file` instead of `dotenv`

Loading a .env file used to be the job of dotenv. Node.js can read it before your code even starts.

# .env
PORT=3000
API_BASE_URL=https://api.example.com

// app.js
console.log(`Starting on port ${process.env.PORT}`);
console.log(`Calling ${process.env.API_BASE_URL}`);

node --env-file=.env app.js

If you prefer to load it from code, which is closer to how dotenv works, call process.loadEnvFile():

process.loadEnvFile(); // reads ./.env by default

Remember to add .env to your .gitignore.

Where the package still wins: Node.js does not expand variables inside values, so URL=http://${HOST}:3000 stays a literal string. --env-file throws an error if the file is missing (use --env-file-if-exists for optional files). And a variable that is already set in your shell takes priority over the file.

Version note: stable since Node.js 24.10.0 (and 22.21.0). Before those releases, the flag and the function were still marked experimental.

5. `util.parseArgs()` instead of `minimist`, `yargs` or `commander`

Small scripts often need two or three command line flags. You do not need a package for that.

// cli.js
import { parseArgs } from 'node:util';

const { values, positionals } = parseArgs({
  options: {
    port: { type: 'string', short: 'p', default: '3000' },
    verbose: { type: 'boolean', short: 'v', default: false },
  },
  allowPositionals: true,
});

console.log(values, positionals);

Running node cli.js --port 8080 -v build prints:

[Object: null prototype] { port: '8080', verbose: true } [ 'build' ]

(values is an object without a prototype, which is why Node.js prints that prefix.)

Where the package still wins: option types can only be 'string' or 'boolean', so you convert the port with Number(values.port) yourself. parseArgs only parses: it does not generate --help output or handle subcommands for you. By default an unknown option throws an error, unless you set strict: false. For a CLI that other people will install, commander is still worth it. For your own script with three flags, parseArgs is enough.

Version note: stable since Node.js 20.0.0.

6. TypeScript type stripping instead of `ts-node` or `tsx`

You can now run a .ts file directly. Node.js removes the type annotations and runs the JavaScript that is left.

// tasks.ts
type Task = { id: number; title: string; done: boolean };

const tasks: Task[] = [
  { id: 1, title: 'Write the article', done: false },
  { id: 2, title: 'Publish on dev.to', done: false },
];

function pending(list: Task[]): Task[] {
  return list.filter((task) => !task.done);
}

console.log(pending(tasks));

node tasks.ts

One important point: Node.js only strips the types, it does not check them. Type checking stays with the TypeScript compiler, so keep running tsc --noEmit in your editor or CI.

Where the package still wins: only syntax that can simply be erased is supported. Features that need real JavaScript to be generated, such as enum, namespace with runtime code and constructor parameter properties, fail with an error. Import specifiers need the file extension (./lib.ts, not ./lib), tsconfig.json settings such as paths are ignored, and .tsx files are not supported. The Node.js docs recommend TypeScript 5.8 or newer, and setting erasableSyntaxOnly: true in tsconfig.json makes tsc warn you about unsupported syntax before Node.js does.

Version note: stable in Node.js 24.12.0 and 25.2.0, and enabled by default since 22.18.0 (and 23.6.0).

7. `fs.glob()` instead of `glob`

Finding files by pattern used to mean installing glob or fast-glob. Now it lives in node:fs.

import { glob } from 'node:fs/promises';

const markdownFiles = await Array.fromAsync(
  glob('content/**/*.md', { exclude: ['content/drafts/**'] })
);

console.log(markdownFiles);

There is also a synchronous globSync() in node:fs that returns an array, and brace patterns like **/*.{md,mdx} work.

Where the package still wins: the promise version returns an async iterator, which is why the example wraps it in Array.fromAsync(). The option for skipping files is named exclude, not ignore, and negation patterns such as !foo.js are not supported in it. In Node.js 24, the documented options are cwd, exclude, withFileTypes and, from 24.16.0, followSymlinks. If you rely on advanced features of the glob package, check that they exist here before switching. For typical build scripts, the built-in is enough.

Version note: stable since Node.js 24.0.0 and 22.17.0. Earlier 22.x releases still mark it experimental. Passing an array of patterns to exclude needs Node.js 22.14.0 or newer (or 23.7.0+); on older versions, pass a function instead.

Quick reference

Package	Built-in replacement	Stable since
`axios`, `node-fetch`	`fetch()`	21.0.0
`jest`, `mocha`	`node:test` + `node:assert`	20.0.0
`nodemon`	`node --watch`	22.0.0 (20.13.0)
`dotenv`	`--env-file`, `process.loadEnvFile()`	24.10.0 (22.21.0)
`minimist`, `yargs`, `commander`	`util.parseArgs()`	20.0.0
`ts-node`, `tsx`	TypeScript type stripping	24.12.0 / 25.2.0
`glob`	`fs.glob()`	24.0.0 (22.17.0)

Final thoughts

Removing a dependency is not about purity. Each built-in above covers the common case and then stops, and the old package is still useful for whatever the built-in leaves out. Before you remove a package, read the "where the package still wins" part and ask whether you actually hit that case. In many projects you will not, and the dependency goes away together with its updates and its install time.

One last tip: pin the runtime so nobody has to guess which features are available.

{
  "engines": {
    "node": ">=24.12"
  }
}

A few more built-ins worth exploring in the Node.js docs: util.styleText() (a chalk alternative), crypto.randomUUID() (instead of uuid), the WebSocket global (the client side of ws), and the recursive option of fs.rm() and fs.mkdir() (instead of rimraf and mkdirp).

Which dependency did you remove from your last project? Tell me in the comments.

DEV Community: Loknath Patel

Stop Returning `200 OK` for Every API Response in Express

The status code is part of your API contract

Success responses: 200, 201 and 204

Client errors: 400, 401, 403 and 404

Use 500 for unexpected server failures

A few edge cases worth getting right

Make the HTTP response tell the truth

Your Website Works With a Mouse, But Fails With a Keyboard

A clickable div is not a button

Removing the focus outline removes the map

Dialogs need focus to go somewhere, and to come back

Menus and widgets don't share one key pattern

Forms: labels and errors need a keyboard path

Focus order and keyboard traps

A keyboard test you can run in ten minutes

How to Call an API with JavaScript fetch() and Handle Errors Properly

The test API

What fetch() actually does

async/await in one minute

The complete example

Expected output

Watch an error happen

How it works, step by step

The ways a request can fail

Add a timeout

Common mistakes

Bonus: sending data with POST

Conclusion

Session-Based Authentication in Node.js and TypeScript with HttpOnly Cookies and CSRF Protection

What you will build

The architecture, and why

The threat model, briefly

1. Project setup

TypeScript configuration

2. Environment configuration

3. Database and users

4. Password hashing

5. A SQLite-backed session store

6. Session middleware and secure cookies

Session fixation

7. CSRF protection

8. Routes

9. App wiring: order is the specification

10. Entry point

11. Tests

12. Trying it by hand

Common mistakes and troubleshooting

What this tutorial does not cover

Conclusion

References

Why Your Node.js API Is Slow in Production: 10 Mistakes That Pass Code Review

The golden rule: measure first

The 20365311 gotcha

1. One slow function freezes every request

Fixes

2. The N+1 query: one endpoint, one query per row

3. Sending columns nobody reads

4. Serial await that should run in parallel

5. The query that was fine at 100 rows

6. A new database connection per request

The production math nobody does in dev

7. Recomputing the same thing on every request

8. Outbound calls with no timeout, or a leaky one

9. Loading a whole file into memory just to send it

10. Serializing big JSON on the event loop

Bonus 1: AsyncLocalStorage is not free

Bonus 2: Async errors in Express 4 vs Express 5

Bonus 3: Framework benchmarks are not your benchmarks

Back to the puzzle

Quick checklist

Do you still install uuid, qs or Moment out of habit? I checked 10 built-in browser APIs against MDN and tested the examples in Chrome, and noted when to keep the package.

10 Browser APIs That Can Replace npm Packages (and When They Can't)

10 Browser APIs That Can Replace npm Packages (and When They Can't)

1. structuredClone() replaces lodash cloneDeep

2. crypto.randomUUID() replaces uuid

3. fetch() + AbortSignal.timeout() replaces axios for simple requests

4. Intl.RelativeTimeFormat replaces Moment for "time ago"

5. URLSearchParams replaces qs and query-string for flat query strings

6. IntersectionObserver replaces scroll listeners for visibility checks

What `fetch()` actually does

`async/await` in one minute

1. `structuredClone()` replaces lodash `cloneDeep`

2. `crypto.randomUUID()` replaces `uuid`

3. `fetch()` + `AbortSignal.timeout()` replaces axios for simple requests

4. `Intl.RelativeTimeFormat` replaces Moment for "time ago"

5. `URLSearchParams` replaces `qs` and `query-string` for flat query strings

6. `IntersectionObserver` replaces scroll listeners for visibility checks

7. `ResizeObserver` replaces window `resize` listeners for element sizes

9. `BroadcastChannel` replaces the `localStorage` event trick for cross-tab messages

10. Clipboard API replaces `document.execCommand('copy')` and clipboard.js for copying text

1. `fetch()` instead of `axios` or `node-fetch`

2. `node:test` instead of Jest or Mocha

3. `node --watch` instead of `nodemon`

4. `--env-file` instead of `dotenv`

5. `util.parseArgs()` instead of `minimist`, `yargs` or `commander`

6. TypeScript type stripping instead of `ts-node` or `tsx`

7. `fs.glob()` instead of `glob`