Read full article on CodeKK

Read full article on CodeKK

Read full article on CodeKK

If you've written even one Express app, you've typed something like this:

js

app.use(express.json());

You probably knew it lets you read req.body, and moved on. Fair enough, it works. But that one line is your first encounter with middleware, and once you understand what's actually happening there, a lot of Express starts making more sense, including why some bugs happen (like req.body being undefined) and why route order in your file actually matters.

The problem middleware solves

Every request that hits your Express server needs to go through some common processing before it reaches the actual logic you care about. Things like: is this request's body valid JSON? Is the user logged in? Should this request even be allowed to reach this route, or should it get rejected? Do we want to log that this request happened?

Without a shared way to handle this, you'd end up writing the same checks inside every single route handler.

js

app.get("/dashboard", (req, res) => {
  if (!req.headers.authorization) {
    return res.status(401).json({ message: "Not authorized" });
  }
  // ... actual dashboard logic
});

app.get("/settings", (req, res) => {
  if (!req.headers.authorization) {
    return res.status(401).json({ message: "Not authorized" });
  }
  // ... actual settings logic
});

That's repetitive, error-prone, and gets worse as your app grows. If you have twenty protected routes, you have twenty copies of that same check, and if you ever need to change how auth works, you're editing twenty places instead of one.

Express solves this with middleware: functions that sit in between the incoming request and your final route handler, each one able to inspect, modify, or reject the request before passing it along.

[IMAGE: Diagram showing a request arriving at the left, passing through three labeled middleware boxes in sequence (logger, auth check, body parser), and finally reaching the route handler box on the right, placed right after this paragraph]

The airport security analogy

Think of your Express app like an airport. A passenger (the request) doesn't walk straight from the entrance to their gate (the route handler). They pass through a sequence of checkpoints first: ID verification, baggage scanning, boarding pass check. Each checkpoint does one specific job, and each one has the power to let you through to the next checkpoint, or stop you right there and send you back.

That's exactly what middleware does. A request comes in, passes through however many middleware functions you've set up, each one does its job, checks something, logs something, parses something, and then either calls next() to send the passenger to the next checkpoint, or ends the journey right there by sending a response, like a rejected boarding pass.

What a middleware function actually looks like

Every middleware function in Express has the same basic shape:

js

function myMiddleware(req, res, next) {
  // do something with req or res
  console.log(`${req.method} request to ${req.url}`);
  next(); // pass control to the next middleware or route handler
}

app.use(myMiddleware);

Three parameters: req (the incoming request), res (the response you can send back), and next (a function you call to hand off control). That's it. That's the entire contract.

The part people forget most often is next(). If your middleware doesn't call next() and doesn't send a response either, the request just hangs there forever. The client keeps waiting, nothing times out on its own, and you'll be staring at your terminal wondering why the request never completes.

Middleware runs in order, and order matters

This is the part that trips up a lot of people building their first few Express apps. Middleware doesn't run all at once, it runs in the exact order you registered it, top to bottom in your code.

js

app.use(logger);        // runs first
app.use(checkAuth);     // runs second
app.use(express.json()); // runs third
app.get("/profile", getProfile); // runs last, only if all above called next()

[IMAGE: A vertical flowchart showing the exact order above, logger then checkAuth then express.json then getProfile, with arrows labeled "next()" between each step, placed right after this code block]

If you put checkAuth before express.json(), but your auth check needed to read something from req.body, it would fail, because the body hasn't been parsed yet at that point in the chain. This is also why you'll sometimes see express.json() registered right at the top of the file, before almost anything else, it needs to run early so everything after it can rely on req.body actually being there.

Built-in and third-party middleware

Express ships with a few built-in middleware functions you've probably already used:

js

app.use(express.json());              // parses JSON request bodies
app.use(express.urlencoded({ extended: true })); // parses form data
app.use(express.static("public"));    // serves static files like images and CSS

And the wider ecosystem has middleware for almost anything you'd want to do at the request level:

js

const cors = require("cors");
const morgan = require("morgan");
const helmet = require("helmet");

app.use(cors());     // handles cross-origin requests, covered in detail in the CORS blog
app.use(morgan("dev")); // logs every request to the console
app.use(helmet());   // sets a bunch of security-related HTTP headers

If you've read what is CORS and how to fix it, that entire fix is middleware, cors() is just a function that inspects the request's origin and adds the right headers before passing it along, exactly the same pattern as everything else on this page.

Writing your own middleware: an auth check example

Here's a realistic one, checking if a request has a valid token before letting it reach a protected route:

js

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

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

  try {
    const decoded = verifyToken(token); // your JWT verification logic
    req.user = decoded; // attach user info to the request for later use
    next();
  } catch (err) {
    res.status(403).json({ message: "Invalid or expired token" });
  }
}

app.get("/dashboard", requireAuth, (req, res) => {
  res.json({ message: `Welcome ${req.user.name}` });
});

Notice requireAuth is placed directly as a second argument to app.get, before the actual route handler. Express lets you chain as many middleware functions as you want for a single route this way. If requireAuth calls next(), the request moves on to the route handler. If it sends a response instead (like the 401 or 403 above), the route handler never runs at all. If you want to go deeper on what's actually inside that token and why it works this way, that's covered in how JWT authentication works.

This is also exactly why the status codes you choose here matter, a well-behaved API should be specific about why a request failed, something explained further in HTTP status codes explained.

Error-handling middleware: the one everyone forgets exists

There's a second kind of middleware most tutorials skip over: error-handling middleware. It looks almost identical to regular middleware, except it takes four parameters instead of three.

js

function errorHandler(err, req, res, next) {
  console.error(err.stack);
  res.status(500).json({ message: "Something went wrong" });
}

app.use(errorHandler);

[IMAGE: A simple diagram showing a normal middleware chain on top with three parameters, and an error-handling middleware chain below it triggered by "next(err)" with four parameters, placed right after this code block]

Express recognizes this as error-handling middleware specifically because of the four arguments, that's not a style choice, it's how Express distinguishes it from regular middleware. You trigger it by calling next(err) anywhere in your app instead of next():

js

app.get("/user/:id", async (req, res, next) => {
  try {
    const user = await getUserById(req.params.id);
    res.json(user);
  } catch (err) {
    next(err); // skips straight to error-handling middleware
  }
});

The important rule here: error-handling middleware needs to be registered last, after all your other routes and middleware. Express walks through middleware in order, and error handlers only catch errors from things registered before them.

Common mistakes

• Forgetting to call next(). The request just hangs, no error, no response, nothing. This is one of the most confusing bugs to debug for the first time because nothing actually crashes.

• Registering middleware in the wrong order. Auth checks that need req.body but run before express.json(), or route-specific middleware registered after the routes that need it.

• Calling next() after already sending a response. This throws a "Cannot set headers after they are sent" error, usually because a middleware both calls res.send() and next() in the same code path by mistake.

• Writing error-handling middleware with only three parameters. Express silently treats it as regular middleware instead, and it just never gets triggered by next(err).

What to actually take away from this

Middleware is just functions in a queue, each one gets a chance to look at the request, do something with it, and decide whether to pass it forward or stop it there. Once you see app.use(express.json()) as "a function that runs on every request and calls next() when it's done," the rest of Express middleware, auth checks, logging, CORS, error handling, all follow the exact same shape. You're not learning five different concepts, you're learning one pattern applied five different ways.

Read full article on CodeKK

You change one line of state, and the whole UI just updates. How?

You click a button, setCount(count + 1) runs, and somehow only the number on screen changes. Nothing flickers, nothing reloads, nothing else on the page gets touched. If you've used React for more than a week you've seen this happen a thousand times and probably stopped thinking about it.

But something is deciding what changed and what to leave alone. That something is the Virtual DOM, and understanding how it actually works will change how you think about performance, re-renders, and those weird bugs where a list item updates the wrong row.

The problem the Virtual DOM was built to solve

To understand why the Virtual DOM exists, you first need to understand what it's protecting you from: the real DOM.

The DOM (Document Object Model) is the browser's live representation of your HTML page. Every <div>, every <p>, every button is a DOM node, and the browser keeps track of all of them. The problem is that DOM nodes are heavy. They carry layout information, event listeners, computed styles, and a dozen other properties. When you change something in the DOM, the browser often has to recalculate the layout of the page (this is called reflow) and repaint pixels on screen.

Now imagine you're building something like a live chat app or a dashboard that updates every second. If every small data change meant directly touching the real DOM, tearing down elements and rebuilding them, your app would feel sluggish fast. Doing this manually with plain JavaScript is exactly the kind of thing that used to make jQuery-heavy apps slow and hard to maintain.

React needed a way to update the UI often, sometimes many times a second, without paying the full cost of touching the real DOM every single time. That's the actual problem the Virtual DOM solves.

So what is the Virtual DOM, really?

The Virtual DOM is not a browser feature. It's not part of any web standard. It's just a plain JavaScript object that React keeps in memory, structured to look like the DOM tree, but far lighter.

Think of it like this: every time you write JSX like this,

jsx

function Greeting() {
  return <h1 className="title">Hello, Kartik</h1>;
}

React doesn't turn this directly into a real DOM element. It first creates a JavaScript object that describes it, something conceptually similar to:

js

{
  type: "h1",
  props: {
    className: "title",
    children: "Hello, Kartik"
  }
}

That object is cheap to create and cheap to throw away. React can create thousands of these in a fraction of the time it would take to create thousands of real DOM nodes.

The actual analogy that makes this click

Picture a writer working on a long document with a co-editor. Instead of the co-editor rewriting the entire document every time the writer makes one small correction, they use "track changes." The editor compares the new draft to the old one, sees exactly which sentences changed, and only marks up those specific lines. The rest of the document stays untouched.

React does the same thing with your UI. Every time state or props change, React builds a fresh Virtual DOM tree describing what the UI should look like now. Then it compares this new tree against the previous one, line by line, node by node, and figures out exactly what's different. Nothing gets rebuilt from scratch. Only the actual differences get applied to the real DOM.

This comparison process has a name: diffing. And applying the result to the real DOM has a name too: reconciliation.

How diffing and reconciliation actually work

When state changes in a component, here's the real sequence of events:

1. React re-runs your component function and builds a new Virtual DOM tree.

2. React compares this new tree to the previous Virtual DOM tree using a diffing algorithm.

3. React calculates the minimal set of changes needed, this is often called the "patch."

4. React applies only that patch to the real DOM.

The diffing algorithm doesn't do a full, brute-force comparison of every possible tree structure. That would be too slow for large apps. Instead, React makes some practical assumptions to keep this fast:

• If two elements are of a different type (say a <div> became a <span>), React tears down the old one completely and builds a new one. It doesn't try to figure out what parts can be reused.

• If two elements are the same type, React keeps the same underlying DOM node and just updates the attributes that changed.

• For lists, React relies on the key prop to track which item is which across renders, instead of comparing them by position.

That last point is why you'll see warnings in the console if you render a list without keys, or worse, use the array index as a key when the list can reorder. Without a stable key, React can't reliably tell whether an item moved, changed, or is brand new, and it might update the wrong DOM node with the wrong data. This becomes especially important once you're fetching and rendering dynamic lists, something covered in more depth in how to fetch data in React.

A quick example to see it in action

jsx

function Counter() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  );
}

Every time you click the button:

• React re-runs Counter() and gets a new Virtual DOM tree back.

• It compares the new tree to the old one. The <div> is the same, the <button> is the same, but the text inside <p> changed from "Count: 0" to "Count: 1".

• React's patch is tiny: update the text content of that one text node.

• The real DOM only touches that single text node. The button, its event listener, the div, none of it gets rebuilt.

This is exactly why React feels fast even when you're updating state constantly. You're not paying the cost of the real DOM on every render, you're paying it only where something actually changed.

Where Fiber fits in

Modern React (16 and above) doesn't just diff and patch in one synchronous blocking pass. It uses something called Fiber, which is a reimplementation of React's core reconciliation algorithm that lets React break rendering work into small units, pause it, prioritize it, and resume it later if needed. This is what makes features like concurrent rendering and smoother handling of large updates possible. Fiber doesn't change the core idea of the Virtual DOM, it just makes the reconciliation process smarter about scheduling. If you've written components with useEffect and noticed how renders and effects are ordered, that behavior ties back to this same reconciliation system, explained in more detail in how useEffect actually works.

A misconception worth clearing up

A lot of developers repeat "Virtual DOM is faster than the real DOM" as if it's some kind of universal law. That's not quite accurate. For a single, isolated DOM update, direct manipulation can actually be faster than going through the Virtual DOM's diffing process. The real win isn't raw speed on one update, it's predictability and efficiency at scale. When you have a complex UI with many components that can change independently, the Virtual DOM gives React a systematic way to figure out the minimal set of real DOM changes needed, without you having to manually track what changed and write that update logic yourself.

That's the actual value: you write declarative code describing what the UI should look like for any given state, and React figures out how to get the real DOM there efficiently. You stop thinking about DOM manipulation and start thinking about state, which is a big part of why frameworks like Next.js build entire rendering strategies on top of this same React core, something worth understanding further in React vs Next.js.

What to take away from this

The Virtual DOM isn't magic and it isn't a performance guarantee by itself. It's a practical solution to a real problem: how do you update a UI often, based on changing state, without manually managing expensive DOM operations every time. React keeps a lightweight copy of the UI in memory, compares versions of it, and applies only the necessary changes to the real DOM. Once you see it this way, a lot of React's behavior, why keys matter, why re-renders happen, why some updates feel instant, stops feeling like a black box and starts feeling like a system you can reason about.

Read full article on CodeKK

Read full article on CodeKK

Read full article on CodeKK

How to Build an Active Link Indicator in Next.js - Navbar and Sidebar

If you have built a navbar in Next.js, you have probably run into this question - how do I highlight the link for the page the user is currently on? The active link indicator is one of those small UI details that makes your app feel polished and tells the user exactly where they are.

The good news is Next.js makes this surprisingly simple with one hook - usePathname. This blog walks through the complete setup, from creating the navbar to adding the active indicator, including a sidebar version at the end.

If you are not yet familiar with how Next.js routing works, check out the SSR, CSR, SSG, and ISR blog on codekk.dev - it covers the App Router and how pages are structured in a Next.js project.

What We Are Building

A navbar with navigation links where the currently active route gets a visible indicator - in this case a blue bottom border. As you navigate between pages, the indicator moves to the correct link automatically.

At the end we will also build the same thing for a sidebar, using a left border instead of a bottom border.

Project Setup

Start with a fresh Next.js project if you do not have one:

npx create-next-app@latest active-link-indicator

Choose TypeScript, Tailwind CSS, and the App Router when prompted.

Your folder structure will look like this:

└── active-link-indicator
    └── app
        ├── favicon.ico
        ├── globals.css
        ├── layout.tsx
        └── page.tsx
    └── public
    ├── .gitignore
    ├── next.config.ts
    ├── package.json
    └── tsconfig.json

Step 1 - Create the Navbar Component

Create a new folder and file at components/Navbar/Navbar.tsx. Keeping components in their own named folders is a clean habit - it makes the project easier to navigate as it grows.

└── components
    └── Navbar
        └── Navbar.tsx

Paste this starting code into Navbar.tsx:

"use client";
import Image from "next/image";
import Link from "next/link";
import { usePathname } from "next/navigation";
import React from "react";

function Navbar() {
  const pathName = usePathname();
  console.log(pathName); // logs "/" on the home page

  const navLinks = [
    { name: "home", url: "/" },
    { name: "about us", url: "/about-us" },
    { name: "services", url: "/services" },
    { name: "blogs", url: "/blogs" },
    { name: "contact us", url: "/contact-us" },
  ];

  return (
    <nav className="flex justify-between items-center px-10 py-3 border-b border-gray-400">
      <div className="h-6">
        <Image
          src="https://res.cloudinary.com/dyswu0gin/image/upload/v1786772071/logo_lxnwhq.png"
          alt="CodeKK"
          width={1000}
          height={1000}
          className="w-full h-full object-contain"
          loading="eager"
        />
      </div>
      <ul className="flex gap-2.5">
        {navLinks.map((navLink, index) => {
          return (
            <li key={index}>
              <Link
                href={navLink.url}
                className="text-base font-medium capitalize py-1 px-2.5"
              >
                {navLink.name}
              </Link>
            </li>
          );
        })}
      </ul>
    </nav>
  );
}

export default Navbar;

There are a few things worth understanding here before moving on.

"use client" at the top - usePathname is a React hook, and hooks only work in Client Components. Without "use client", Next.js treats this as a Server Component and the hook will throw an error. Any component that uses hooks, event listeners, or browser APIs needs this directive.

usePathname - this hook from next/navigation returns the current URL path as a string. On the home page it returns "/". On /about-us it returns "/about-us". It updates automatically whenever the route changes - no manual tracking needed.

The navLinks array - instead of hardcoding each link separately in JSX, we store them in an array of objects and map over them. This keeps the code clean and makes adding or removing links a one-line change.

Step 2 - Add the Navbar to Your Layout

Open app/layout.tsx and import the Navbar so it appears on every page:

import "./globals.css";
import Navbar from "./components/Navbar/Navbar";

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en" className="h-full antialiased">
      <body className="min-h-full flex flex-col">
        <Navbar />
        {children}
      </body>
    </html>
  );
}

Placing the Navbar in the root layout means it renders on every single page without having to import it individually. The {children} slot is where each page's content goes.

Step 3 - Configure Next.js for the External Image

Since we are loading the logo from Cloudinary, you need to tell Next.js it is an allowed image domain. Open next.config.ts and add this:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "res.cloudinary.com",
        pathname: "/**",
      },
    ],
  },
};

export default nextConfig;

Without this, the next/image component will refuse to load images from external domains and throw an error.

Step 4 - Create the Test Pages

To actually test the active indicator, you need pages to navigate between. Create these files:

app/
├── about-us/
│   └── page.tsx
├── blogs/
│   └── page.tsx
├── services/
│   └── page.tsx
└── contact-us/
    └── page.tsx

The content for each is simple - just a heading to confirm which page you are on. Here is about-us/page.tsx:

import React from "react";

function AboutUs() {
  return <h1 className="mt-4 text-2xl text-center">About Us</h1>;
}

export default AboutUs;

Create the same pattern for blogs/page.tsx, services/page.tsx, and contact-us/page.tsx - just change the component name and the heading text.

Now run your dev server:

npm run dev

Open the browser and check the console. You should see / logged on the home page.

[IMAGE: Browser showing the CodeKK navbar with Home, About Us, Services, Blogs, Contact Us links. Console open below showing "/" logged from Navbar.tsx]

Now click "About Us" in the navbar. Watch the console - it updates to /about-us.

[IMAGE: Browser on localhost:3001/about-us showing "About Us" heading. Console showing "/" then "/about-us" logged as navigation happened]

Click "Services" - the console shows /services.

[IMAGE: Browser on localhost:3001/services showing "Services" heading. Console showing the pathname updating to "/services"]

This is usePathname working. Every time you navigate, the hook returns the new pathname and the component re-renders with the updated value. That updated value is exactly what we will use to decide which link to highlight.

Step 5 - Adding the Active Link Indicator

Now the actual feature. The idea is simple - compare pathName with each navLink.url. If they match, apply the active style. If they do not, apply a transparent style so the layout does not shift.

Update Navbar.tsx with this one addition inside the map:

{navLinks.map((navLink, index) => {
  const isActive = pathName === navLink.url; // this is the key line

  return (
    <li key={index}>
      <Link
        href={navLink.url}
        className={`text-base font-medium capitalize py-1 px-2.5 border-b-2 ${
          isActive ? "border-b-[#0088d4]" : "border-b-transparent"
        }`}
      >
        {navLink.name}
      </Link>
    </li>
  );
})}

Here is what each part does:

const isActive = pathName === navLink.url - a simple strict equality check. If the current URL path exactly matches this link's URL, isActive is true. Otherwise it is false. This runs for every item in the array on every render.

border-b-2 - adds a 2px bottom border to every link. This is important. If you only added the border to the active link, the other links would shift slightly in height when they become active because the border would suddenly appear and take up space. Adding border-b-2 to all links keeps the height consistent - only the color changes.

isActive ? "border-b-[#0088d4]" : "border-b-transparent" - when active, the border color is blue (#0088d4). When inactive, the border is transparent - it still exists and takes up space, but you cannot see it. This is the trick that prevents layout shift.

[IMAGE: Browser showing the CodeKK navbar with "About Us" link highlighted with a blue bottom border, all other links having no visible border]

Navigate between pages and watch the blue border follow the current route automatically.

The Complete Navbar Component

Here is the full updated Navbar.tsx:

"use client";
import Image from "next/image";
import Link from "next/link";
import { usePathname } from "next/navigation";
import React from "react";

function Navbar() {
  const pathName = usePathname();

  const navLinks = [
    { name: "home", url: "/" },
    { name: "about us", url: "/about-us" },
    { name: "services", url: "/services" },
    { name: "blogs", url: "/blogs" },
    { name: "contact us", url: "/contact-us" },
  ];

  return (
    <nav className="flex justify-between items-center px-10 py-3 border-b border-gray-400">
      <div className="h-6">
        <Image
          src="https://res.cloudinary.com/dyswu0gin/image/upload/v1786772071/logo_lxnwhq.png"
          alt="CodeKK"
          width={1000}
          height={1000}
          className="w-full h-full object-contain"
          loading="eager"
        />
      </div>
      <ul className="flex gap-2.5">
        {navLinks.map((navLink, index) => {
          const isActive = pathName === navLink.url;

          return (
            <li key={index}>
              <Link
                href={navLink.url}
                className={`text-base font-medium capitalize py-1 px-2.5 border-b-2 ${
                  isActive ? "border-b-[#0088d4]" : "border-b-transparent"
                }`}
              >
                {navLink.name}
              </Link>
            </li>
          );
        })}
      </ul>
    </nav>
  );
}

export default Navbar;

Bonus - Active Link Indicator for a Sidebar

The same concept works for a sidebar, but the design is different. Instead of a bottom border on the link, a left border on the list item makes more sense visually - it is a common pattern you see in dashboards and admin panels.

Create components/Aside/Aside.tsx:

"use client";
import Link from "next/link";
import { usePathname } from "next/navigation";

function Aside() {
  const pathName = usePathname();

  const asideUrls = [
    { name: "all categories", url: "/all-categories" },
    { name: "product cards", url: "/loader-skeletons/product-cards" },
  ];

  return (
    <aside className="shrink-0 max-w-50 w-full border-r pl-2.5 py-10">
      <ul>
        {asideUrls.map((asideUrl, index) => {
          const isActive = pathName === asideUrl.url;

          return (
            <li
              key={index}
              className={`w-full h-fit relative after:absolute after:left-0 after:top-0 after:w-0.5 after:h-full ${
                isActive ? "after:bg-primary" : "after:bg-transparent"
              }`}
            >
              <Link
                href={asideUrl.url}
                className="px-3 py-1.5 text-sm font-medium capitalize block w-full h-full"
              >
                {asideUrl.name}
              </Link>
            </li>
          );
        })}
      </ul>
    </aside>
  );
}

export default Aside;

The logic is identical - usePathname, isActive check, conditional class. But the styling approach is different.

after:absolute after:left-0 after:top-0 after:w-0.5 after:h-full - this uses Tailwind's after: pseudo-element prefix to create a thin vertical line on the left side of the list item. The after: utility applies styles to the CSS ::after pseudo-element, which is an invisible element added after the content.

isActive ? "after:bg-primary" : "after:bg-transparent" - when active, the pseudo-element gets a background color (your primary brand color). When inactive, it is transparent. Same trick as the navbar - the element always exists, only the color toggles.

Using a pseudo-element here instead of a real element or a border keeps the layout clean. The li itself does not have a border that would affect its width or spacing - the indicator is painted on top using position: absolute.

Why This Works

The entire feature is built on one idea: usePathname gives you the current route as a string. You compare that string to each link's URL. If they match, apply the active class.

No complex state management. No context. No effect. Just a hook that returns a value and a conditional class that responds to it.

The fact that usePathname is reactive - it updates on every navigation without you doing anything - is what makes this so clean. Next.js handles the tracking internally. You just read the value and use it.

Read full article on CodeKK

Read full article on CodeKK

If you are building a Next.js project and you need a database, Supabase and Prisma together is one of the cleanest setups you can go with. Supabase gives you a hosted PostgreSQL database with a solid dashboard. Prisma gives you a type-safe ORM that makes querying that database feel natural in TypeScript.

This blog walks you through the entire setup - from creating a Supabase project to seeding your database with data. We will keep it practical and move step by step.

If you want to understand how Next.js itself works before diving into the database layer, check out the React vs Next.js blog and the SSR, CSR, SSG, and ISR blog on codekk.dev first.

What We Are Building

By the end of this blog you will have:

• A Supabase PostgreSQL database connected to your Next.js project

• Prisma set up as your ORM with a working schema

• Two database models - User and Post - migrated and ready

• Seed data inserted into your database

• A way to browse your data using Prisma Studio

Let's get into it.

Step 1 - Create a Supabase Account and Project

Before anything else, head to supabase.com and create a free account if you do not have one already.

Once you are in, click the Create a new project button.

You will see a project creation screen where you need to fill in your project name, set a database password, and choose a region.

Two things to remember here:

Region - select the region closest to where your users or your server will be. This keeps latency low.

Database password - copy this immediately and paste it somewhere safe like a notes app or password manager. You will need it in a later step and Supabase will not show it to you again after this screen.

Once your project is created, click the Connect button in the project dashboard.

You will see several connection options. Select ORM from the tabs. Supabase will then show you two ORM options - Prisma and Drizzle. Select Prisma.

You will see two connection strings here - DATABASE_URL and DIRECT_URL. Keep this tab open. You will need to copy these in a later step.

Step 2 - Set Up Your Next.js Project

If you do not have a Next.js project yet, create one:

npx create-next-app@latest my-app
cd my-app

Choose TypeScript when prompted - Prisma works best with TypeScript and the type safety it provides is one of the main reasons to use it.

If you want a refresher on Next.js project structure and how the App Router works, the SSR, CSR, SSG, and ISR blog covers it in detail.

Step 3 - Install Prisma and Dependencies

From your project root, run these four commands:

npm install prisma --save-dev
npm install @prisma/client
npm install @prisma/adapter-pg pg dotenv
npm install --save-dev @types/pg

Here is what each one does:

prisma - the Prisma CLI, installed as a dev dependency because you only use it during development for migrations and schema changes, not in production runtime.

@prisma/client - the actual Prisma client that your application code uses to query the database. This one goes into production.

@prisma/adapter-pg and pg - Prisma uses adapters to talk to different databases. Since Supabase is PostgreSQL, we need the pg adapter. pg is the underlying PostgreSQL client for Node.js.

dotenv - loads your .env file so Prisma can read your database connection strings from environment variables.

@types/pg - TypeScript type definitions for the pg package.

Step 4 - Initialize Prisma

Now initialize Prisma in your project:

npx prisma init

[IMAGE: Terminal output after running npx prisma init - showing the files created]

This command creates three things in your project:

• prisma/schema.prisma - where you define your database models

• prisma.config.ts - Prisma configuration file

• .env - environment variables file (if it does not exist already)

Step 5 - Add Your Database Connection Strings

Open your .env file. You will see a DATABASE_URL placeholder already there. Remove everything in the file and replace it with the two connection strings from Supabase.

Go back to your Supabase tab where you selected Prisma as your ORM. Copy both DATABASE_URL and DIRECT_URL from there.

Paste both into your .env file:

DATABASE_URL="your-database-url-from-supabase"
DIRECT_URL="your-direct-url-from-supabase"

Now replace the [YOUR-PASSWORD] placeholder in both URLs with the database password you saved when creating the project.

Why two URLs? Supabase uses a connection pooler by default which is efficient for production traffic but does not support all Prisma features like migrations. DATABASE_URL points to the pooled connection - used by your application at runtime. DIRECT_URL points directly to the database - used by Prisma for migrations and seeding.

Step 6 - Configure prisma.config.ts

Open the prisma.config.ts file that Prisma generated. Update it to use DIRECT_URL for the datasource:

import "dotenv/config";
import { defineConfig } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
  },
  datasource: {
    url: process.env["DIRECT_URL"], // Use DIRECT_URL for direct connection to the database
  },
});

We are using DIRECT_URL here because prisma.config.ts is used for migrations - operations that need a direct connection, not a pooled one.

Step 7 - Define Your Database Schema

Open prisma/schema.prisma. This is where you define what your database tables look like. Prisma calls them models.

Replace the contents with this schema:

generator client {
  provider        = "prisma-client-js"
  output          = "../app/generated/prisma/client"
}

datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")
  directUrl = env("DIRECT_URL")
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

model Post {
  id        Int     @id @default(autoincrement())
  title     String
  content   String?
  published Boolean @default(false)
  authorId  Int
  author    User    @relation(fields: [authorId], references: [id])
}

Here is what each part means:

generator client - tells Prisma to generate a TypeScript client. The output path is where the generated client files will go - in this case inside your app/generated/prisma/client folder.

datasource db - tells Prisma it is talking to a PostgreSQL database and where to find the connection strings.

model User - creates a users table with:

• id - auto-incrementing integer, set as the primary key

• email - required unique string

• name - optional string (the ? means nullable)

• posts - a relation field showing this user can have many posts (does not create a column - it is just for Prisma's query API)

model Post - creates a posts table with:

• id - auto-incrementing primary key

• title - required string

• content - optional string

• published - boolean defaulting to false

• authorId - the foreign key linking to the User table

• author - the relation definition telling Prisma how the tables connect

This is a classic one-to-many relationship - one user can have many posts. Prisma handles the JOIN logic for you when you query.

Step 8 - Run Your First Migration

Now push this schema to your Supabase database by running:

npx prisma migrate dev

Prisma will ask you to name this migration. Give it something descriptive like init or create-users-and-posts.

This command does three things:

1. Compares your schema to the current state of the database

2. Generates a SQL migration file inside prisma/migrations

3. Runs that migration against your database

After it finishes, your users and posts tables exist in Supabase. You can open your Supabase dashboard and see them under the Table Editor.

It also generates the Prisma client code in app/generated/prisma/client based on your schema, so your TypeScript code gets full type safety when querying.

Step 9 - Seed Your Database

Seeding means inserting some initial data into your database. Prisma has built-in support for this.

Create a new file at prisma/seed.ts and paste this code:

import { PrismaClient, Prisma } from "../app/generated/prisma/client";
import { PrismaPg } from "@prisma/adapter-pg";
import "dotenv/config";

const adapter = new PrismaPg({
  connectionString: process.env.DATABASE_URL,
});

const prisma = new PrismaClient({
  adapter,
});

const userData: Prisma.UserCreateInput[] = [
  {
    name: "Sadie Sink",
    email: "ssadie0416@gmail.com",
    posts: {
      create: [
        {
          title: "Join the Prisma Discord",
          content: "https://pris.ly/discord",
          published: true,
        },
        {
          title: "Prisma on YouTube",
          content: "https://pris.ly/youtube",
        },
      ],
    },
  },
  {
    name: "Prince Vishwakarma",
    email: "prince.pv.14.2000@gmail.com",
    posts: {
      create: [
        {
          title: "Follow Prisma on Twitter",
          content: "https://www.twitter.com/prisma",
          published: true,
        },
      ],
    },
  },
];

export async function main() {
  for (const u of userData) {
    await prisma.user.create({ data: u });
  }
}

main();

A few things worth understanding here:

PrismaPg adapter - we initialize Prisma with the pg adapter and pass the DATABASE_URL (pooled connection) for seeding since it is a runtime operation, not a migration.

userData array - each object in this array is one user with their associated posts nested inside. Prisma's create API lets you create related records in a single call - no need to insert the user first, get their ID, then insert posts separately.

Prisma.UserCreateInput - this is a TypeScript type generated by Prisma based on your schema. It ensures your seed data matches exactly what the database expects.

Step 10 - Add Seed Script to prisma.config.ts

Now tell Prisma where to find the seed script. Open prisma.config.ts and add the seed line:

import "dotenv/config";
import { defineConfig } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
    seed: `tsx prisma/seed.ts`, // add this line to run the seed script
  },
  datasource: {
    url: process.env["DIRECT_URL"],
  },
});

Before running the seed, install tsx - a tool that lets Node.js run TypeScript files directly without compiling them first:

npm install --save-dev tsx

If you skip installing tsx and try to run the seed, you will get an error because Node.js cannot run .ts files directly by default.

Now run the seed:

npx prisma db seed

Step 11 - Verify Your Data

You have two ways to check that everything worked.

Option 1 - Check Supabase Dashboard

Open your Supabase project and go to the Table Editor. You should see your users and posts tables with the seed data inside them.

Option 2 - Use Prisma Studio

Prisma comes with a built-in GUI for browsing your database. Run:

npx prisma studio

It opens at http://localhost:5555 (or similar port) and shows you all your tables and data in a clean interface - no need to open Supabase at all.

Using Prisma in Your Next.js Code

Now that everything is connected, here is how you actually query your database in a Next.js Server Component:

import { PrismaClient } from "../generated/prisma/client";
import { PrismaPg } from "@prisma/adapter-pg";

const adapter = new PrismaPg({
  connectionString: process.env.DATABASE_URL,
});

const prisma = new PrismaClient({ adapter });

export default async function UsersPage() {
  const users = await prisma.user.findMany({
    include: {
      posts: true, // include related posts
    },
  });

  return (
    <div>
      {users.map(user => (
        <div key={user.id}>
          <h2>{user.name}</h2>
          <p>{user.email}</p>
          <p>{user.posts.length} posts</p>
        </div>
      ))}
    </div>
  );
}

Because this is a Server Component, the database query runs on the server before the page reaches the browser. No API route needed, no fetch call, no exposed credentials. Prisma handles the SQL, TypeScript handles the types, Next.js handles the rendering.

One important note for production: Create a single Prisma client instance and reuse it across your app instead of creating a new one in every file. A common pattern is to create a lib/prisma.ts file that exports a single instance. This prevents connection pool exhaustion in a serverless environment like Vercel.

// lib/prisma.ts
import { PrismaClient } from "../app/generated/prisma/client";
import { PrismaPg } from "@prisma/adapter-pg";
import "dotenv/config";

const adapter = new PrismaPg({
  connectionString: process.env.DATABASE_URL,
});

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined;
};

export const prisma =
  globalForPrisma.prisma ?? new PrismaClient({ adapter });

if (process.env.NODE_ENV !== "production") {
  globalForPrisma.prisma = prisma;
}

Import prisma from this file wherever you need it.

What You Have Now

At this point your setup is complete:

• Supabase is hosting your PostgreSQL database

• Prisma is managing your schema, migrations, and queries

• Your Next.js app can query the database directly from Server Components

• Your data is type-safe end to end - if your schema changes, TypeScript will catch anywhere your code breaks immediately

This is a solid foundation. From here you can add more models to your schema, write more complex queries using Prisma's API, or add API routes that use the same Prisma client for client-side data fetching.

Read full article on CodeKK

Read full article on CodeKK

If you have read the Promises blog and the Callbacks blog on codekk.dev, you already understand the problem JavaScript has been trying to solve. Async operations are everywhere, and writing clean code that handles them has always been harder than it should be.

Callbacks gave us a way to handle async results but turned into nested pyramids. Promises flattened that pyramid into a readable chain. Async/await takes it one step further - it makes async code look and feel like synchronous code, while still being completely non-blocking underneath.

This is the final piece of the JavaScript async series on codekk.dev. By the end of this blog, you will understand not just how to write async/await but what it is actually doing under the hood, why it behaves the way it does, and the mistakes that trip developers up in real projects.

What Async/Await Actually Is

Async/await is not a new async system. It is not replacing Promises or the event loop. It is syntax built directly on top of Promises that makes them easier to read and write.

Every async function returns a Promise. Every await expression pauses that function and waits for a Promise to settle. That is the entire model. Everything else follows from these two facts.

// This async function
async function greet() {
  return "Hello";
}

// Is exactly the same as this
function greet() {
  return Promise.resolve("Hello");
}

// Both are used the same way
greet().then(message => console.log(message)); // "Hello"

The async keyword before a function does one thing - it makes that function always return a Promise. If you return a plain value, it gets wrapped in Promise.resolve() automatically. If you throw an error, it gets wrapped in Promise.reject().

The await Keyword - What It Actually Does

await can only be used inside an async function. It pauses the execution of that function until the Promise it is waiting for settles, then resumes with the resolved value.

async function fetchUser() {
  const response = await fetch("https://api.example.com/users/1");
  const user = await response.json();
  console.log(user);
}

Here is what happens line by line:

1. fetch() is called - it returns a Promise immediately

2. await pauses fetchUser and hands control back to the caller

3. The event loop is free to do other work

4. When the fetch Promise resolves, fetchUser resumes with the response

5. response.json() is called - it also returns a Promise

6. await pauses again, event loop is free again

7. When the json Promise resolves, fetchUser resumes with the parsed data

8. console.log(user) runs

The function pauses twice. But the rest of your application keeps running during those pauses. This is not blocking - it is the event loop working exactly as we covered in the JavaScript Event Loop blog.

[IMAGE: Diagram showing async function execution - function starts, hits await, pauses and hands control to event loop (shown as circular arrow), event loop handles other tasks, Promise resolves, function resumes from where it paused. Labels: "Function pauses here" at await, "Resumes here" when Promise resolves]

Async/Await vs Promise Chains - The Same Thing Written Differently

The best way to understand async/await is to see it next to the equivalent Promise chain. They are doing exactly the same thing.

Promise chain version:

function loadDashboard(userId) {
  return fetchUser(userId)
    .then(user => {
      return fetchOrders(user.id)
        .then(orders => ({ user, orders }));
    })
    .then(({ user, orders }) => {
      return fetchRecommendations(user.preferences)
        .then(recommendations => ({ user, orders, recommendations }));
    })
    .then(({ user, orders, recommendations }) => {
      renderDashboard(user, orders, recommendations);
    })
    .catch(err => {
      console.error("Dashboard failed to load:", err);
    });
}

Async/await version:

async function loadDashboard(userId) {
  try {
    const user = await fetchUser(userId);
    const orders = await fetchOrders(user.id);
    const recommendations = await fetchRecommendations(user.preferences);
    renderDashboard(user, orders, recommendations);
  } catch (err) {
    console.error("Dashboard failed to load:", err);
  }
}

Same operations. Same order. Same error handling. The async/await version reads like a simple list of steps from top to bottom. No chaining, no nesting, no callbacks. This is the whole point.

Under the hood, the JavaScript engine converts the async/await version into something similar to the Promise chain. You are writing cleaner code - the engine handles the Promise machinery for you.

Error Handling With Try/Catch

In Promise chains, you use .catch() for error handling. With async/await, you use the standard JavaScript try/catch that you already know from synchronous code.

async function getUser(id) {
  try {
    const response = await fetch(`/api/users/${id}`);

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

    const user = await response.json();
    return user;
  } catch (err) {
    console.error("Failed to fetch user:", err.message);
    return null;
  }
}

When any await inside the try block rejects, execution jumps to the catch block. Exactly like a synchronous try/catch.

Handling errors for specific steps differently:

Sometimes you want to handle errors at individual steps rather than catching everything in one place:

async function processOrder(orderId) {
  let order;

  try {
    order = await fetchOrder(orderId);
  } catch (err) {
    // This specific error we can recover from
    console.log("Order not found, creating new one");
    order = await createDefaultOrder();
  }

  // This error we want to propagate up
  const payment = await processPayment(order.total);
  return payment;
}

You can nest try/catch blocks or use separate try/catch for each step when different errors need different handling.

Async/Await With Multiple Promises - Parallel vs Sequential

This is one of the most important things to understand with async/await, and a very common source of performance bugs.

Sequential - each waits for the previous:

async function loadData() {
  const users = await fetchUsers();       // waits ~300ms
  const products = await fetchProducts(); // waits ~300ms after users
  const orders = await fetchOrders();     // waits ~300ms after products
  // Total time: ~900ms
}

This is fine when each call depends on the result of the previous one. But if these three calls are completely independent of each other, you are making them wait in line for no reason.

Parallel - all start at the same time:

async function loadData() {
  const [users, products, orders] = await Promise.all([
    fetchUsers(),
    fetchProducts(),
    fetchOrders()
  ]);
  // Total time: ~300ms (waits for the slowest one)
}

Promise.all starts all three requests simultaneously. You await the combined Promise that resolves when all three finish. The total time is roughly equal to the slowest single request instead of the sum of all three.

This is one of the biggest performance wins you can get with very little code change. If you have multiple independent async operations, run them in parallel.

[IMAGE: Timeline diagram showing two approaches - top row shows sequential awaits as three blocks one after another totaling 900ms. Bottom row shows Promise.all as three overlapping blocks all starting at the same time totaling 300ms. Labels: "Sequential - 900ms total" and "Parallel with Promise.all - 300ms total"]

When to use sequential vs parallel:

// Sequential is correct here - second depends on first
const user = await fetchUser(userId);
const orders = await fetchOrders(user.id); // needs user.id

// Parallel is correct here - neither depends on the other
const [profile, settings] = await Promise.all([
  fetchProfile(userId),
  fetchSettings(userId)
]);

The rule is simple: if a request needs data from a previous request, run them sequentially. If they are independent, run them in parallel.

Async Functions in Different Contexts

Async/await works in regular functions, arrow functions, and methods. The syntax is slightly different in each case but the behavior is the same.

Regular function:

async function fetchData() {
  const data = await getData();
  return data;
}

Arrow function:

const fetchData = async () => {
  const data = await getData();
  return data;
};

Class method:

class UserService {
  async getUser(id) {
    const user = await db.users.findById(id);
    return user;
  }

  async createUser(data) {
    const user = await db.users.create(data);
    return user;
  }
}

In Next.js Server Components - which we covered in detail in the SSR, CSR, SSG, and ISR blog:

// Server Component - async works directly at the component level
export default async function ProductsPage() {
  const products = await fetch("https://api.example.com/products")
    .then(r => r.json());

  return (
    <div>
      {products.map(product => (
        <div key={product.id}>{product.name}</div>
      ))}
    </div>
  );
}

In Express route handlers - from the Node.js and Express blog:

app.get("/users/:id", async (req, res) => {
  try {
    const user = await db.users.findById(req.params.id);
    if (!user) return res.status(404).json({ error: "User not found" });
    res.json(user);
  } catch (err) {
    res.status(500).json({ error: "Internal server error" });
  }
});

Top Level Await

Traditionally, await could only be used inside an async function. If you tried to use it at the top level of a module, you would get a syntax error.

Modern JavaScript (ES2022) introduced top-level await which allows you to use await directly in ES modules without wrapping it in an async function.

// In an ES module (.mjs or with "type": "module" in package.json)
const data = await fetch("https://api.example.com/config").then(r => r.json());
console.log(data); // works at the top level

This is particularly useful in Node.js scripts and configuration files. In Next.js and most modern build setups, top-level await works out of the box.

Common Mistakes With Async/Await

Forgetting await:

async function getUser(id) {
  const user = fetchUser(id); // missing await
  console.log(user); // logs Promise { <pending> } not the actual user
  return user;
}

Without await, you get the Promise object itself, not the resolved value. TypeScript catches this in many cases - another reason to use TypeScript as we covered in the TypeScript vs JavaScript blog.

Using await inside forEach:

// This does NOT work as expected
async function processOrders(orders) {
  orders.forEach(async (order) => {
    await processOrder(order); // these all fire simultaneously and forEach doesn't wait
  });
  console.log("Done"); // runs before any orders are processed
}

// Use for...of instead
async function processOrders(orders) {
  for (const order of orders) {
    await processOrder(order); // waits for each one sequentially
  }
  console.log("Done"); // runs after all orders are processed
}

// Or if you want parallel processing
async function processOrders(orders) {
  await Promise.all(orders.map(order => processOrder(order)));
  console.log("Done"); // runs after all orders are processed in parallel
}

forEach does not care about Promises. It fires all the async callbacks and moves on. Use for...of for sequential processing or Promise.all with .map() for parallel processing.

Not handling errors:

// If this rejects, the error is swallowed silently
async function riskyOperation() {
  const data = await fetchSomething();
  return data;
}

// Always wrap in try/catch or handle at the call site
async function safeOperation() {
  try {
    const data = await fetchSomething();
    return data;
  } catch (err) {
    console.error("Operation failed:", err);
    return null;
  }
}

Async functions in useEffect - the wrong way:

// Wrong - useEffect callback cannot be async directly
useEffect(async () => {
  const data = await fetchData();
  setData(data);
}, []);

// Correct - define async function inside and call it
useEffect(() => {
  async function load() {
    const data = await fetchData();
    setData(data);
  }
  load();
}, []);

We covered useEffect in detail in the useEffect blog. The async function pattern inside useEffect is one of the most common React mistakes developers hit when they first learn async/await.

How Async/Await Connects to the Event Loop

If you read the JavaScript Event Loop blog, you know that .then() callbacks go into the Microtask Queue - the high priority queue that runs before setTimeout callbacks.

await works through the same mechanism. When a function hits await, it pauses and registers the rest of the function as a microtask to run when the awaited Promise resolves. This is why async/await code has the same priority as Promise chains - because it is Promise chains, just with different syntax.

async function example() {
  console.log("1 - Before await");
  await Promise.resolve();
  console.log("3 - After await");
}

example();
console.log("2 - After calling example");

// Output:
// 1 - Before await
// 2 - After calling example
// 3 - After await

When example() hits await, it pauses and the console.log("2 - After calling example") on the outer code runs first. Then the microtask queue runs and example() resumes with "3 - After await".

This is exactly the same behavior we traced through with .then() in the Promises blog - because the mechanism is identical.

Async/Await in Real Projects - Putting It All Together

Here is what a real-world async/await pattern looks like in a complete Node.js and Express API - combining everything from the backend series on codekk.dev:

// Utility function for reusable async error handling
const asyncHandler = (fn) => (req, res, next) => {
  Promise.resolve(fn(req, res, next)).catch(next);
};

// Route handler - clean, readable, no try/catch clutter
app.get("/users/:id", asyncHandler(async (req, res) => {
  const user = await db.user.findUnique({
    where: { id: req.params.id },
    include: { posts: true }
  });

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

  res.json(user);
}));

// Running multiple queries in parallel
app.get("/dashboard/:userId", asyncHandler(async (req, res) => {
  const { userId } = req.params;

  const [user, orders, notifications] = await Promise.all([
    db.user.findUnique({ where: { id: userId } }),
    db.order.findMany({ where: { userId }, take: 10 }),
    db.notification.findMany({ where: { userId, read: false } })
  ]);

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

  res.json({ user, orders, notifications });
}));

// Global error handler catches anything that slips through
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({ error: "Internal server error" });
});

The asyncHandler wrapper is a common pattern in Express - it wraps any async route handler and forwards any unhandled rejections to the next error handler. This removes the need for try/catch in every single route handler.

The Complete Picture - JavaScript Async From Start to Finish

Now that you have read through the entire async series on codekk.dev, here is how all the pieces fit together:

Callbacks - the original pattern. Functions passed to be called later. Still used everywhere for event listeners, array methods, and simple cases.

Promises - a cleaner API around callbacks. An object representing a future value. Chainable with .then() and .catch(). The foundation everything else builds on.

Async/Await - syntax sugar over Promises. Makes async code look synchronous. async functions always return Promises. await pauses execution until a Promise settles.

Event Loop - the underlying mechanism that makes all of this possible. Callbacks and microtasks get queued and run when the call stack is empty. None of this blocks - it all works through the queue system.

They are not competing concepts. They are layers of the same system, each one built on top of the previous, each one making async JavaScript a little cleaner to write.

[IMAGE: Layered architecture diagram showing four layers stacked - bottom layer "Event Loop" in blue, second layer "Callbacks" in orange, third layer "Promises" in yellow, top layer "Async/Await" in green. Arrow on the side labeled "Each layer builds on the one below it". This shows the complete async JavaScript picture]

Read full article on CodeKK

Every developer building a backend eventually hits this question. You have data to store, you need a database, and two names keep coming up - PostgreSQL and MongoDB. Someone in a tutorial uses one, someone on Reddit recommends the other, and you're left wondering which one you should actually learn and use.

This blog explains what each database actually is, how they store data differently, and gives you a clear way to think about which one fits your project. Not a "one is better" argument - because neither is universally better. Just an honest breakdown so you can make the right call.

If you've been following the backend series on codekk.dev, you've already covered Node.js and Express, JWT authentication, and CORS. The missing piece has been the database layer - this is it.

The Fundamental Difference - How They Think About Data

Before anything else, you need to understand that PostgreSQL and MongoDB are built on completely different ideas about what data looks like and how it should be stored.

PostgreSQL is a relational database. It stores data in tables - rows and columns, like a spreadsheet. Every row in a table follows the same structure. Relationships between different types of data are handled by linking tables together using keys.

MongoDB is a document database. It stores data as JSON-like documents inside collections. Each document can have a different structure. Related data can either be referenced or embedded directly inside the same document.

This isn't just a syntax difference. It's a fundamentally different way of thinking about your data, and it affects how you design your application from the start.

How PostgreSQL Stores Data

In PostgreSQL, before you store anything, you define a schema. A schema is a strict blueprint that says exactly what columns exist, what type of data each column holds, and which columns are required.

CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  name VARCHAR(100) NOT NULL,
  email VARCHAR(255) UNIQUE NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE orders (
  id SERIAL PRIMARY KEY,
  user_id INTEGER REFERENCES users(id),
  total_amount DECIMAL(10, 2) NOT NULL,
  status VARCHAR(50) DEFAULT 'pending',
  created_at TIMESTAMP DEFAULT NOW()
);

Every user stored in this table will have exactly these four fields - nothing more, nothing less. If you try to insert a user without an email, PostgreSQL rejects it. If you try to add a field that doesn't exist in the schema, PostgreSQL rejects it.

The orders table has a user_id column that references the users table. This is a foreign key - it creates a formal relationship between the two tables. PostgreSQL enforces this relationship. You cannot create an order for a user that doesn't exist. If you try to delete a user who has orders, PostgreSQL will either block you or cascade the deletion depending on how you configured it.

To get a user and all their orders together, you use a JOIN:

SELECT users.name, users.email, orders.total_amount, orders.status
FROM users
JOIN orders ON users.id = orders.user_id
WHERE users.id = 1;

This relational model is powerful when your data has clear relationships and you need to query across those relationships in complex ways. The strict schema means your data is always consistent and predictable.

How MongoDB Stores Data

In MongoDB, there's no schema to define upfront. You create a collection and start inserting documents immediately. A document is a JSON object and it can have whatever fields you want.

// A user document in MongoDB
{
  _id: ObjectId("64a7b3c2e1234567890abcde"),
  name: "Rahul",
  email: "rahul@example.com",
  createdAt: new Date("2024-01-15"),
  preferences: {
    theme: "dark",
    language: "en"
  },
  tags: ["developer", "react"]
}

Notice a few things here. The user document has nested data inside it - preferences is an object embedded directly in the user document. tags is an array. This is natural in MongoDB.

In a relational database, preferences and tags would typically live in separate tables with their own foreign key relationships. In MongoDB you just put them inside the document because they belong to the user.

For orders, you have a choice in MongoDB. You can reference the user by their ID (similar to how SQL does it):

// Order document with a reference to the user
{
  _id: ObjectId("64a7b3c2e1234567890abcdf"),
  userId: ObjectId("64a7b3c2e1234567890abcde"),
  totalAmount: 2499,
  status: "pending",
  items: [
    { productName: "Mechanical Keyboard", quantity: 1, price: 2499 }
  ],
  createdAt: new Date("2024-01-15")
}

Or, if orders are always accessed together with the user, you could embed them directly inside the user document:

// User document with orders embedded
{
  _id: ObjectId("64a7b3c2e1234567890abcde"),
  name: "Rahul",
  email: "rahul@example.com",
  orders: [
    {
      totalAmount: 2499,
      status: "pending",
      items: [{ productName: "Mechanical Keyboard", quantity: 1, price: 2499 }]
    }
  ]
}

[IMAGE: Diagram showing a MongoDB document with nested objects and arrays embedded inside it, contrasted with the same data spread across multiple SQL tables]

The decision between referencing and embedding in MongoDB depends entirely on how you access the data. If you always need the orders when you fetch a user, embedding saves you an extra query. If orders can grow very large or are accessed independently, referencing makes more sense.

Querying - SQL vs MongoDB Query Language

This is where the day-to-day developer experience differs most noticeably.

PostgreSQL uses SQL - Structured Query Language. It's been around since the 1970s and is one of the most widely known programming interfaces in software development.

-- Get all users who signed up in the last 30 days
SELECT id, name, email
FROM users
WHERE created_at >= NOW() - INTERVAL '30 days'
ORDER BY created_at DESC;

-- Get total revenue per user
SELECT users.name, SUM(orders.total_amount) as total_spent
FROM users
JOIN orders ON users.id = orders.user_id
GROUP BY users.id, users.name
ORDER BY total_spent DESC;

MongoDB has its own query language based on JavaScript objects:

// Get all users who signed up in the last 30 days
db.users.find({
  createdAt: { $gte: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000) }
}).sort({ createdAt: -1 });

// Get total spent per user (using aggregation pipeline)
db.orders.aggregate([
  {
    $group: {
      _id: "$userId",
      totalSpent: { $sum: "$totalAmount" }
    }
  },
  { $sort: { totalSpent: -1 } }
]);

SQL is more readable for complex queries involving multiple tables. MongoDB's aggregation pipeline is powerful but has a steeper learning curve for complex operations. For simple queries, both feel comparable.

Schema Flexibility - A Feature and a Risk

MongoDB's schema flexibility is often presented as a major advantage, and it genuinely can be. During early development when your data model is still changing, not having to write migrations every time you add a field is genuinely convenient.

But flexibility has a cost. Without a schema enforced at the database level, the responsibility for data consistency falls entirely on your application code. If one part of your code saves a user with an email field and another part accidentally saves with emailAddress, both are valid in MongoDB. Your database will happily store inconsistent data and you'll only discover the problem when your code breaks trying to read it.

PostgreSQL's strictness feels limiting at first. Adding a new column to a table requires a migration. Changing a column type requires careful planning. But this strictness is also what guarantees that every row in your table looks exactly the way you expect it to. Your data is consistent by definition.

[IMAGE: Split diagram - left side shows MongoDB collection with documents having inconsistent field names (email vs emailAddress vs e_mail) with a warning icon. Right side shows a PostgreSQL table where all rows have consistent columns with a checkmark icon]

Most teams working with MongoDB end up adding a schema validation layer in their application code anyway - using libraries like Mongoose which adds schemas on top of MongoDB. At that point you have the flexibility of MongoDB with schema enforcement added back in through your ORM. It works, but it's worth knowing you're solving a problem that PostgreSQL doesn't have in the first place.

Transactions - When They Matter

A transaction is a way to group multiple database operations so they either all succeed or all fail together. This matters enormously in certain situations.

Consider a bank transfer. You're moving money from Account A to Account B. That's two operations - deduct from A, add to B. If the first operation succeeds and then something fails before the second one completes, Account A lost money that never arrived in Account B. Without transactions, this is a real risk.

PostgreSQL has had full ACID transaction support since the beginning. Wrapping multiple operations in a transaction is straightforward:

BEGIN;
  UPDATE accounts SET balance = balance - 1000 WHERE id = 1;
  UPDATE accounts SET balance = balance + 1000 WHERE id = 2;
COMMIT;

If anything fails between BEGIN and COMMIT, the entire thing rolls back as if nothing happened.

MongoDB added multi-document transaction support in version 4.0, so it does support transactions now. But they come with performance overhead and are generally considered a workaround in MongoDB - if you find yourself needing frequent multi-document transactions, it often means your data model would work better in a relational database.

Performance - It Depends on What You're Doing

Neither database is faster in absolute terms. Performance depends heavily on your data access patterns.

MongoDB tends to perform well when you're reading and writing single documents that contain all the data you need. Because related data is often embedded, you're doing fewer queries. Reading a user with all their preferences and recent activity in one document query is fast.

PostgreSQL tends to perform well for complex queries across multiple tables, especially with proper indexing. Its query planner is sophisticated and can optimize JOINs and aggregations efficiently. For analytical queries or reporting where you're aggregating data across the whole database, PostgreSQL typically has an edge.

For most web applications, both will perform well within your expected load. The performance difference rarely matters until you're at significant scale, at which point you'll have enough engineering resources to address it properly. Don't make your database choice based on hypothetical future scale - make it based on your current data model and access patterns.

When PostgreSQL is the Right Choice

PostgreSQL makes sense when:

Your data has clear relationships that you need to query across. A user has orders, orders have items, items have products - that relational structure is exactly what PostgreSQL was designed for.

Data consistency is critical. Financial applications, healthcare data, anything where you cannot afford inconsistent or corrupt data belongs in a relational database with proper constraints and transactions.

You're doing complex reporting or analytics. SQL is genuinely excellent for aggregation, grouping, and cross-table queries. If your app needs to generate reports across your data, PostgreSQL will serve you better.

Your schema is stable and well-defined. If you know what your data looks like and it's not going to change dramatically, the strictness of PostgreSQL works in your favor.

When MongoDB is the Right Choice

MongoDB makes sense when:

Your data is naturally document-shaped. If you're storing things like product catalogs where each product has wildly different attributes, or user-generated content that varies in structure, the document model fits naturally.

You're prototyping or iterating quickly. During early development when your data model is still evolving, MongoDB lets you move fast without writing migrations constantly.

You're storing hierarchical or nested data. If your data has a lot of nesting and you always access it together, embedding in MongoDB is cleaner than managing multiple joined tables.

You're working with content-heavy applications like CMS platforms, blogs, or catalog systems where the content structure varies and relations are simple.

The Honest Summary

[IMAGE: Clean comparison table showing PostgreSQL vs MongoDB across key dimensions - data model, schema, transactions, query language, best for, and flexibility]

PostgreSQL is the safer default for most applications. It's been battle-tested for decades, has excellent tooling, enforces data integrity at the database level, and SQL is a skill that transfers everywhere. If you're not sure which one to pick, PostgreSQL is the lower-risk choice.

MongoDB is genuinely good for what it's designed for - flexible, document-shaped data where the structure varies and relations are simple. It's not a "beginner" database or a "worse" one, just a different tool for a different kind of problem.

The mistake most developers make is picking one based on which tutorial they happened to follow first. Pick based on your data. Sketch out what your data actually looks like and how you'll query it. If it naturally fits in tables with clear relationships, use PostgreSQL. If it naturally fits in nested documents with varying structure, use MongoDB.

Both are excellent databases. The decision matters a lot less than people make it out to be as long as you make it consciously.

Read full article on CodeKK

If you have read the callbacks blog on codekk.dev, you already know the problem. Sequential async operations with callbacks turn into deeply nested pyramids that are hard to read, hard to maintain, and painful to debug. Promises were created specifically to fix that.

But most developers learn just enough about Promises to use .then() and .catch() and move on. They do not really understand what a Promise object is, what states it goes through, how chaining actually works, or why error handling behaves the way it does.

This blog covers all of that properly. By the end, you will not just know how to use Promises - you will understand what they actually are and why they work the way they do. And when you get to async/await after this, it will make complete sense because async/await is just Promises with cleaner syntax underneath.

What a Promise Actually Is

A Promise is an object that represents the eventual result of an async operation. It is a placeholder for a value that does not exist yet but will exist at some point in the future - or will fail trying.

Think of it like ordering food at a restaurant. When you order, the waiter does not disappear and come back only when the food is ready while making you stand at the counter. They give you a token - a promise that your food will come. You go sit down and do other things. When the food is ready, it gets delivered to you.

In JavaScript terms:

• The token is the Promise object

• Sitting down and doing other things is your code continuing to run

• The food arriving is the Promise resolving

• The kitchen running out of ingredients is the Promise rejecting

const foodPromise = orderFood("Biryani"); // returns a Promise immediately

// You do not wait here - code continues
console.log("Sitting down...");
console.log("Checking phone...");

// When food is ready, this runs
foodPromise.then(food => {
  console.log("Food arrived:", food);
}).catch(err => {
  console.log("Order failed:", err.message);
});

The Promise object is returned immediately. The actual value comes later.

The Three States of a Promise

Every Promise is always in exactly one of three states. Understanding these states is the foundation of understanding how Promises work.

[IMAGE: Diagram showing three states of a Promise - "Pending" in yellow center circle with arrows pointing to "Fulfilled" in green on the right and "Rejected" in red on the left. One-way arrows showing you can only go from Pending to either Fulfilled or Rejected, never back. Labels: "resolve() called" on the arrow to Fulfilled, "reject() called" on the arrow to Rejected]

Pending - the initial state. The async operation has started but has not completed yet. The Promise is waiting.

Fulfilled - the operation completed successfully. The Promise now has a value. Your .then() callback runs.

Rejected - the operation failed. The Promise has a reason for failure. Your .catch() callback runs.

Once a Promise moves from Pending to either Fulfilled or Rejected, it is settled and can never change state again. A fulfilled Promise will always be fulfilled with the same value. A rejected Promise will always be rejected with the same reason.

const promise = new Promise((resolve, reject) => {
  setTimeout(() => {
    resolve("Success!"); // moves to Fulfilled
    resolve("Another value"); // ignored - already settled
    reject("Error"); // ignored - already settled
  }, 1000);
});

This immutability is important - it means you can safely pass a Promise around and attach multiple handlers to it without worrying about the state changing unexpectedly.

Creating a Promise - The Promise Constructor

You create a Promise using the new Promise() constructor. It takes one function as an argument - called the executor function. The executor runs immediately and receives two functions: resolve and reject.

const myPromise = new Promise((resolve, reject) => {
  // This runs immediately when the Promise is created

  const success = true;

  if (success) {
    resolve("Operation completed successfully"); // fulfills the Promise
  } else {
    reject(new Error("Something went wrong")); // rejects the Promise
  }
});

Call resolve(value) when the operation succeeds. Call reject(error) when it fails. Only the first call matters - any subsequent calls to either resolve or reject are ignored because the Promise is already settled.

A real async example - wrapping setTimeout in a Promise:

function delay(ms) {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve(`Done after ${ms}ms`);
    }, ms);
  });
}

delay(2000).then(message => {
  console.log(message); // "Done after 2000ms" - appears after 2 seconds
});

console.log("This runs immediately");

Wrapping a callback-based function in a Promise:

This is called promisification - converting an older callback-based API into a Promise-based one.

const fs = require("fs");

// Old callback style
function readFileCallback(path, callback) {
  fs.readFile(path, "utf8", callback);
}

// Promisified version
function readFilePromise(path) {
  return new Promise((resolve, reject) => {
    fs.readFile(path, "utf8", (err, data) => {
      if (err) {
        reject(err); // error goes to reject
      } else {
        resolve(data); // data goes to resolve
      }
    });
  });
}

// Now you can use it with .then() and .catch()
readFilePromise("users.txt")
  .then(data => console.log(data))
  .catch(err => console.error(err));

Node.js actually has a built-in utility for this called util.promisify that does exactly the same conversion automatically for any error-first callback function.

Using a Promise - then, catch, finally

Once you have a Promise, you use three methods to handle its outcome.

.then(onFulfilled, onRejected)

.then() takes up to two arguments - a function to run when the Promise fulfills and an optional function to run when it rejects.

fetchUser(1)
  .then(
    (user) => console.log("Got user:", user),   // runs on success
    (err) => console.error("Failed:", err)       // runs on failure
  );

In practice, most developers only pass the success handler to .then() and use .catch() separately for errors. It is cleaner.

.catch(onRejected)

.catch() handles rejections. It is shorthand for .then(undefined, onRejected).

fetchUser(1)
  .then(user => console.log("Got user:", user))
  .catch(err => console.error("Failed:", err));

.finally(onFinally)

.finally() runs no matter what - whether the Promise fulfilled or rejected. Useful for cleanup like hiding a loading spinner.

showLoadingSpinner();

fetchUser(1)
  .then(user => displayUser(user))
  .catch(err => showError(err))
  .finally(() => hideLoadingSpinner()); // always runs

.finally() receives no arguments - it does not know whether the Promise succeeded or failed. It just knows it is settled.

Promise Chaining - The Real Power

This is what makes Promises genuinely better than callbacks. When you return a value from a .then() callback, it gets wrapped in a new Promise. This lets you chain multiple async operations in a flat, readable sequence instead of nesting them.

fetchUser(1)
  .then(user => {
    console.log("Got user:", user.name);
    return fetchOrders(user.id); // return a new Promise
  })
  .then(orders => {
    console.log("Got orders:", orders.length);
    return sendEmail(orders);  // return another Promise
  })
  .then(result => {
    console.log("Email sent:", result);
  })
  .catch(err => {
    console.error("Something failed:", err); // catches errors from any step
  });

Compare this to the callback hell version from the callbacks blog. The logic is exactly the same but the structure is flat. You read it top to bottom like a series of steps. One .catch() at the end handles errors from any step in the chain.

[IMAGE: Side by side comparison - left shows callback hell pyramid (deeply nested, hard to read), right shows the same logic as a flat Promise chain (clean, readable top to bottom). Arrow between them labeled "Same logic, different structure"]

What gets passed through the chain:

Promise.resolve(1)
  .then(val => val + 1)     // receives 1, returns 2
  .then(val => val * 3)     // receives 2, returns 6
  .then(val => val - 1)     // receives 6, returns 5
  .then(val => console.log(val)); // receives 5, logs 5

Each .then() receives whatever the previous one returned. If you return a plain value, it gets passed directly. If you return a Promise, the next .then() waits for that Promise to resolve and receives its value.

Error Handling in Promise Chains

Errors in Promise chains deserve special attention because they behave differently from synchronous try/catch.

When any step in a chain throws an error or rejects, the chain skips all remaining .then() handlers and jumps straight to the next .catch().

fetchUser(1)
  .then(user => {
    throw new Error("Something broke here"); // this error is caught below
  })
  .then(orders => {
    console.log("This never runs");
  })
  .then(result => {
    console.log("This never runs either");
  })
  .catch(err => {
    console.error("Caught:", err.message); // "Caught: Something broke here"
  });

You can also recover from errors mid-chain by returning a value from .catch():

fetchUser(999) // user does not exist - will reject
  .then(user => fetchOrders(user.id))
  .catch(err => {
    console.log("User not found, using default");
    return { id: 0, orders: [] }; // recover with a default value
  })
  .then(data => {
    console.log("Continuing with:", data); // chain continues here
  });

When .catch() returns a value, the chain continues with that value as if nothing went wrong. This lets you handle specific errors gracefully and continue the chain instead of stopping entirely.

[IMAGE: Diagram showing Promise chain with an error - first .then() runs fine (green), second .then() throws error (red with lightning bolt), third and fourth .then() are skipped (gray with skip arrows), .catch() at the bottom catches it (orange). Label: "Error skips remaining .then() handlers and goes straight to .catch()"]

Promise.all - Running Multiple Promises in Parallel

Sometimes you have multiple async operations that do not depend on each other and you want to run them at the same time instead of one by one.

// Sequential - slow (waits for each one)
const user = await fetchUser(1);        // waits 300ms
const orders = await fetchOrders(1);    // then waits 300ms
const products = await fetchProducts(); // then waits 300ms
// Total: ~900ms

// Parallel with Promise.all - fast (all run at the same time)
const [user, orders, products] = await Promise.all([
  fetchUser(1),
  fetchOrders(1),
  fetchProducts()
]);
// Total: ~300ms (waits for the slowest one)

Promise.all takes an array of Promises and returns a new Promise that:

• Fulfills when ALL Promises in the array fulfill - with an array of their results in the same order

• Rejects immediately when ANY Promise in the array rejects - with that rejection reason

Promise.all([
  fetchUser(1),
  fetchOrders(1),
  fetchProducts()
])
  .then(([user, orders, products]) => {
    // all three are ready here
    console.log(user, orders, products);
  })
  .catch(err => {
    // if any one of them fails, we end up here
    console.error("One of the requests failed:", err);
  });

The "fail fast" behavior of Promise.all is important to know. If you have three requests and the second one fails, you immediately get the rejection. The third request might still be running but you will never get its result through this Promise.

Promise.allSettled - When You Want All Results Regardless

Sometimes you want all results even if some fail. Promise.allSettled waits for all Promises to settle (fulfill or reject) and gives you the outcome of each one.

Promise.allSettled([
  fetchUser(1),
  fetchUser(999),  // this one will fail - user does not exist
  fetchUser(2)
]).then(results => {
  results.forEach(result => {
    if (result.status === "fulfilled") {
      console.log("Success:", result.value);
    } else {
      console.log("Failed:", result.reason);
    }
  });
});

Each item in the results array has a status of either "fulfilled" or "rejected", and either a value (on success) or reason (on failure). No short-circuiting - you always get all results.

Promise.race - First One Wins

Promise.race takes an array of Promises and resolves or rejects as soon as the first one settles, with that Promise's value or reason.

// Useful for timeouts - reject if API takes too long
function fetchWithTimeout(url, timeoutMs) {
  const fetchPromise = fetch(url);

  const timeoutPromise = new Promise((_, reject) => {
    setTimeout(() => {
      reject(new Error(`Request timed out after ${timeoutMs}ms`));
    }, timeoutMs);
  });

  return Promise.race([fetchPromise, timeoutPromise]);
}

fetchWithTimeout("https://api.example.com/users", 3000)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(err => console.error(err.message));

If the fetch completes in under 3 seconds, fetchPromise wins the race and you get the response. If it takes longer, timeoutPromise wins and you get a timeout error.

Promise.any - First Successful One Wins

Promise.any is like Promise.race but it only cares about the first fulfillment, not the first settlement. It ignores rejections unless all Promises reject.

// Try multiple API endpoints - use whichever responds first successfully
Promise.any([
  fetch("https://api1.example.com/data"),
  fetch("https://api2.example.com/data"),
  fetch("https://api3.example.com/data")
])
  .then(response => response.json())
  .then(data => console.log("Got data from fastest server:", data))
  .catch(err => console.error("All servers failed:", err));

If the first two fail but the third succeeds, you get the third one's result. Only if all three fail do you get a rejection.

[IMAGE: Comparison table of Promise.all, Promise.allSettled, Promise.race, Promise.any - showing what each one does when promises succeed vs fail, and what it returns. Dark background table with color coded rows]

Promise.resolve and Promise.reject

These are shorthand ways to create already-settled Promises.

// Creates a Promise that is already fulfilled with this value
Promise.resolve("immediate value")
  .then(val => console.log(val)); // "immediate value"

// Creates a Promise that is already rejected with this error
Promise.reject(new Error("immediate failure"))
  .catch(err => console.error(err.message)); // "immediate failure"

These are useful when you need to return a Promise from a function but already have the value available synchronously:

function getUser(id) {
  // Check cache first
  if (cache.has(id)) {
    return Promise.resolve(cache.get(id)); // return immediately, but as a Promise
  }

  // Otherwise fetch from API
  return fetch(`/api/users/${id}`).then(r => r.json());
}

// Caller always gets a Promise, whether data was cached or not
getUser(1).then(user => console.log(user));

Common Mistakes With Promises

Forgetting to return inside .then():

// Bug - nothing is chained
fetchUser(1)
  .then(user => {
    fetchOrders(user.id); // forgot to return!
  })
  .then(orders => {
    console.log(orders); // undefined - the Promise was not returned
  });

// Correct
fetchUser(1)
  .then(user => {
    return fetchOrders(user.id); // return the Promise
  })
  .then(orders => {
    console.log(orders); // actual orders data
  });

If you forget return inside .then(), the next .then() receives undefined instead of the resolved value. This is one of the most common Promise bugs.

Not catching errors:

// Bug - if this rejects, you get an UnhandledPromiseRejection warning
fetchUser(1)
  .then(user => console.log(user));

// Always add .catch()
fetchUser(1)
  .then(user => console.log(user))
  .catch(err => console.error(err));

Unhandled Promise rejections will crash your Node.js server in newer versions. Always add a .catch() at the end of every Promise chain.

Creating unnecessary Promise wrappers:

// Unnecessary - fetch already returns a Promise
function getUser(id) {
  return new Promise((resolve, reject) => {
    fetch(`/api/users/${id}`)
      .then(r => r.json())
      .then(resolve)
      .catch(reject);
  });
}

// Just return the Promise directly
function getUser(id) {
  return fetch(`/api/users/${id}`).then(r => r.json());
}

Only use new Promise() when you are wrapping something that does not already return a Promise - like a callback-based function. If it already returns a Promise, just chain on it directly.

How Promises Connect to Async/Await

Every async function returns a Promise. Every await expression waits for a Promise to settle. Async/await is not a separate concept - it is syntax sugar built directly on top of Promises.

// Promise chain version
function loadUserData(id) {
  return fetchUser(id)
    .then(user => fetchOrders(user.id)
      .then(orders => ({ user, orders }))
    )
    .catch(err => console.error(err));
}

// Async/await version - same thing, more readable
async function loadUserData(id) {
  try {
    const user = await fetchUser(id);
    const orders = await fetchOrders(user.id);
    return { user, orders };
  } catch (err) {
    console.error(err);
  }
}

Under the hood, the async/await version is doing exactly what the Promise chain is doing. The JavaScript engine converts await into .then() calls. Knowing Promises properly means you understand what async/await is actually doing, which makes debugging async code significantly easier.

If you have read the event loop blog on codekk.dev, you also know that .then() callbacks go into the Microtask Queue - which is why Promise callbacks run before setTimeout callbacks even with zero delay. That same mechanism is what makes await work the way it does.

The Mental Model Worth Keeping

A Promise is a box that says "a value is coming." It starts empty (Pending), then either gets filled with a value (Fulfilled) or gets marked as failed (Rejected). Once it is one of those two, it never changes.

.then() says "when the box gets filled, do this with the value." .catch() says "when the box gets marked failed, do this." .finally() says "when the box is done either way, do this."

Chaining works because each .then() returns a new box. You are building a pipeline of boxes, each one waiting for the previous one to fill up before it starts.

Promises did not solve the fundamental challenge of async JavaScript - that is still handled by the event loop. What they solved is how you write code that deals with async results. Instead of nested callbacks, you get a flat pipeline. Same mechanics, much cleaner code.The yellow color for Promises connects intentionally to the "Pending" state which is the default starting state of every Promise. If your blog has syntax highlighting or callout boxes, using yellow for Promise-related terms, green for resolve/fulfill, and red for reject/error creates a color language that matches both the thumbnail and the mental model explained in the blog.

Read full article on CodeKK

If you have been writing JavaScript for any amount of time, you have used callback functions. Maybe without even realizing it. That addEventListener you wrote, that forEach loop, that setTimeout - all of them use callbacks. They are everywhere in JavaScript.

But most developers learn just enough about callbacks to use them and move on. They do not really understand what a callback is at the language level, why JavaScript uses them so heavily, or how they connect to everything else in async JavaScript.

This blog covers all of it. What callbacks are, how they work, where they come from, their limitations, and how they evolved into the patterns we use today. If you have read the synchronous and asynchronous Node.js blog or the JavaScript event loop blog on codekk.dev, this blog fills in an important piece of that picture.

What a Callback Function Actually Is

A callback function is just a function that you pass as an argument to another function, to be called later.

That is the entire definition. There is nothing magical about it. It is just a function being passed around like any other value.

function greet(name) {
  console.log(`Hello, ${name}`);
}

function processUser(name, callback) {
  console.log("Processing user...");
  callback(name); // calling the function that was passed in
}

processUser("Rahul", greet);

Output:

Processing user...
Hello, Rahul

Here greet is the callback. We did not call greet() ourselves - we passed it to processUser and let processUser call it when it was ready.

This is possible because in JavaScript, functions are first-class citizens. This means functions can be:

• Stored in variables

• Passed as arguments to other functions

• Returned from functions

• Stored in arrays or objects

// Storing a function in a variable
const sayHello = function(name) {
  console.log(`Hello, ${name}`);
};

// Storing functions in an object
const actions = {
  greet: function(name) { console.log(`Hi ${name}`); },
  farewell: function(name) { console.log(`Bye ${name}`); }
};

// Returning a function from a function
function multiplier(factor) {
  return function(number) {
    return number * factor;
  };
}

const double = multiplier(2);
console.log(double(5)); // 10
console.log(double(8)); // 16

This ability to treat functions as values is the foundation of callbacks. Without it, callbacks would not exist.

[IMAGE: Diagram showing a function being passed as an argument into another function, with an arrow showing the callback being called inside the receiving function. Label: "Function passed in → Called when ready"]

Two Ways to Write a Callback

You can pass a callback as a named function or as an anonymous function written inline. Both work the same way.

Named function as callback:

function handleClick() {
  console.log("Button was clicked");
}

document.getElementById("btn").addEventListener("click", handleClick);

Anonymous function as callback:

document.getElementById("btn").addEventListener("click", function() {
  console.log("Button was clicked");
});

Arrow function as callback (modern style):

document.getElementById("btn").addEventListener("click", () => {
  console.log("Button was clicked");
});

All three do exactly the same thing. The named function approach is cleaner when the callback logic is complex or when you need to reuse it. The anonymous and arrow function approach is cleaner for short, one-time callbacks.

Synchronous Callbacks

Not all callbacks are async. Some callbacks run immediately, right inside the function they are passed to. These are called synchronous callbacks.

The built-in array methods are the most common examples:

const numbers = [1, 2, 3, 4, 5];

// forEach - callback runs for each element, synchronously
numbers.forEach(function(num) {
  console.log(num);
});

console.log("This runs AFTER forEach finishes");

Output:

1
2
3
4
5
This runs AFTER forEach finishes

The callback passed to forEach runs synchronously - one by one, in order, before the next line runs. Same with map, filter, reduce, and sort:

// map - transforms each element using the callback
const doubled = numbers.map(num => num * 2);
console.log(doubled); // [2, 4, 6, 8, 10]

// filter - keeps elements where callback returns true
const evens = numbers.filter(num => num % 2 === 0);
console.log(evens); // [2, 4]

// reduce - accumulates a value using the callback
const sum = numbers.reduce((total, num) => total + num, 0);
console.log(sum); // 15

// sort - sorts based on callback comparison
const words = ["banana", "apple", "cherry"];
const sorted = words.sort((a, b) => a.localeCompare(b));
console.log(sorted); // ["apple", "banana", "cherry"]

These are all callbacks - functions passed as arguments to be called by the method. They just happen to run synchronously, one by one, right there in place.

[IMAGE: Diagram showing synchronous callback flow - main code runs line by line, forEach iterates and calls callback for each element in order, then continues to next line. All on the same call stack thread]

Asynchronous Callbacks

This is where callbacks become more interesting and where most of the confusion happens.

An asynchronous callback is a function that gets called later - after some async operation completes. The surrounding code does not wait for it. It moves on immediately.

console.log("1 - Start");

setTimeout(function() {
  console.log("3 - Inside timeout");
}, 2000);

console.log("2 - End");

Output:

1 - Start
2 - End
3 - Inside timeout  ← appears after 2 seconds

The callback inside setTimeout does not run immediately. It runs 2 seconds later, after the rest of the code has already finished. This is the async callback pattern.

If you read the JavaScript event loop blog, you already know why this happens - the setTimeout callback goes into the Callback Queue and only runs after the call stack is empty. This is exactly that mechanism at work.

Real world async callback - reading a file in Node.js:

const fs = require("fs");

console.log("1 - Before reading file");

fs.readFile("users.txt", "utf8", function(err, data) {
  if (err) {
    console.error("Error:", err);
    return;
  }
  console.log("3 - File contents:", data);
});

console.log("2 - After calling readFile");

Output:

1 - Before reading file
2 - After calling readFile
3 - File contents: (file data here)

readFile starts reading the file and immediately returns. The callback runs later when the file is ready. Your code keeps going in the meantime. This is exactly what we covered in the Node.js and Express blog - non-blocking I/O that keeps the server responsive.

Error-First Callbacks - The Node.js Convention

When you work with Node.js built-in modules, you'll notice all async callbacks follow a specific pattern - the first argument is always an error, and the second is the data.

fs.readFile("data.txt", "utf8", function(err, data) {
  // err comes first, always
  if (err) {
    console.error("Something went wrong:", err.message);
    return; // stop here if there's an error
  }
  // only use data if there's no error
  console.log(data);
});

This is called the error-first callback pattern (sometimes called Node-style callbacks or errbacks). The convention is:

• First argument: error object if something went wrong, null if everything is fine

• Second argument onwards: the actual result data

// Writing a function that follows the error-first pattern
function divideNumbers(a, b, callback) {
  if (b === 0) {
    callback(new Error("Cannot divide by zero"), null);
    return;
  }
  callback(null, a / b);
}

divideNumbers(10, 2, function(err, result) {
  if (err) {
    console.error("Error:", err.message);
    return;
  }
  console.log("Result:", result); // Result: 5
});

divideNumbers(10, 0, function(err, result) {
  if (err) {
    console.error("Error:", err.message); // Error: Cannot divide by zero
    return;
  }
  console.log("Result:", result);
});

Always check for the error first. Always. If you skip the error check and something went wrong, data will be undefined and your code will break in a confusing way further down.

Callback Hell - The Biggest Problem With Callbacks

Here is where callbacks start causing real pain.

Imagine you need to do several async operations in sequence - read a user from a file, then fetch their orders from a database, then send them an email. Each step depends on the result of the previous one.

With callbacks, this looks like:

fs.readFile("user.txt", "utf8", function(err, userId) {
  if (err) return console.error(err);

  database.getUser(userId, function(err, user) {
    if (err) return console.error(err);

    database.getOrders(user.id, function(err, orders) {
      if (err) return console.error(err);

      emailService.sendSummary(user.email, orders, function(err, result) {
        if (err) return console.error(err);

        console.log("Email sent successfully:", result);
      });
    });
  });
});

This is callback hell - also called the pyramid of doom because of the shape the indentation makes. Each operation nests inside the previous one, pushing the code further and further to the right.

[IMAGE: Visual representation of callback hell - code shown as a pyramid shape with increasing indentation at each level, each level labeled with the operation (read file, get user, get orders, send email). Arrow pointing to the shape saying "Pyramid of Doom"]

The problems with this pattern:

Hard to read - you have to trace through layers of nesting to follow the logic. By the time you reach the actual work being done, you are four levels deep.

Hard to maintain - adding a new step means adding another level of nesting. Removing a step means carefully unwrapping a layer.

Error handling is repetitive - notice how if (err) return console.error(err) appears at every single level. If you want consistent error handling, you write the same thing over and over.

Hard to debug - stack traces in deeply nested callbacks are confusing to read.

This is exactly the problem that Promises were created to solve - which we covered in detail in the synchronous and asynchronous Node.js blog.

How to Avoid Callback Hell - Even With Callbacks

Before Promises existed, developers came up with patterns to manage callback hell. Even if you use Promises today, knowing these patterns is useful.

Named functions instead of anonymous ones:

function handleUserId(err, userId) {
  if (err) return handleError(err);
  database.getUser(userId, handleUser);
}

function handleUser(err, user) {
  if (err) return handleError(err);
  database.getOrders(user.id, handleOrders.bind(null, user));
}

function handleOrders(user, err, orders) {
  if (err) return handleError(err);
  emailService.sendSummary(user.email, orders, handleEmailResult);
}

function handleEmailResult(err, result) {
  if (err) return handleError(err);
  console.log("Email sent:", result);
}

function handleError(err) {
  console.error("Error:", err.message);
}

// Now the main flow reads cleanly
fs.readFile("user.txt", "utf8", handleUserId);

The logic is the same but the nesting is gone. Each callback is a named function that clearly states what it handles. The main flow reads like a sequence of steps.

Modularizing into separate functions:

function readUserId(callback) {
  fs.readFile("user.txt", "utf8", callback);
}

function fetchUser(userId, callback) {
  database.getUser(userId, callback);
}

function fetchOrders(userId, callback) {
  database.getOrders(userId, callback);
}

function sendEmail(email, orders, callback) {
  emailService.sendSummary(email, orders, callback);
}

Breaking each async operation into its own named function makes the code testable, reusable, and much easier to read.

Callbacks vs Promises vs Async/Await

Callbacks are not wrong or outdated. But it is worth understanding how they relate to the newer patterns.

Callbacks - the original async pattern. Work fine for simple cases. Become messy with sequential async operations.

Promises - wrap the callback pattern in a cleaner API. Instead of passing a callback into a function, the function returns a Promise object and you chain .then() on it. Flat instead of nested.

Async/Await - syntax built on top of Promises. Makes async code look synchronous and is the most readable of the three.

Here is the same operation written all three ways:

// 1. Callback style
fs.readFile("user.txt", "utf8", function(err, data) {
  if (err) return console.error(err);
  console.log(data);
});

// 2. Promise style
fs.promises.readFile("user.txt", "utf8")
  .then(data => console.log(data))
  .catch(err => console.error(err));

// 3. Async/Await style
async function readUser() {
  try {
    const data = await fs.promises.readFile("user.txt", "utf8");
    console.log(data);
  } catch (err) {
    console.error(err);
  }
}

All three do exactly the same thing. Callbacks are not replaced by Promises - Promises are built on top of callbacks under the hood. When you call .then(callback), you are still passing a callback function. The API is just cleaner.

[IMAGE: Side by side comparison of the same async operation written in all three styles - callback (pyramid shape, nested), Promise (flat chain), async/await (looks synchronous). Arrows connecting them showing evolution]

Where You Still See Callbacks Today

Even though async/await is now the standard for most async code, callbacks are still used everywhere:

Event listeners - always use callbacks:

button.addEventListener("click", (event) => {
  console.log("Clicked:", event.target);
});

window.addEventListener("resize", () => {
  console.log("Window resized");
});

Array methods - always use synchronous callbacks:

const users = [
  { name: "Rahul", age: 25 },
  { name: "Priya", age: 22 },
  { name: "Arjun", age: 28 }
];

const adults = users.filter(user => user.age >= 18);
const names = users.map(user => user.name);
const oldest = users.reduce((max, user) => user.age > max.age ? user : max);

setTimeout and setInterval:

setTimeout(() => console.log("Runs once after 1 second"), 1000);

const interval = setInterval(() => console.log("Runs every 2 seconds"), 2000);
setTimeout(() => clearInterval(interval), 10000); // stop after 10 seconds

Express middleware and route handlers - these are callbacks:

// The function passed to app.get is a callback
app.get("/users", (req, res) => {
  res.json({ users: [] });
});

// Middleware is a callback with three parameters
app.use((req, res, next) => {
  console.log(`${req.method} ${req.url}`);
  next();
});

If you built anything with Express from our Node.js and Express blog, you have been writing callbacks the whole time - just without thinking of them that way.

Higher Order Functions - The Bigger Concept

When you understand callbacks, you also understand higher order functions - functions that take other functions as arguments or return functions.

forEach, map, filter, reduce, setTimeout, addEventListener - all of these are higher order functions. They accept a callback and do something with it.

You can write your own higher order functions too:

// A higher order function that runs a callback a given number of times
function repeat(times, callback) {
  for (let i = 0; i < times; i++) {
    callback(i);
  }
}

repeat(3, (i) => console.log(`Running iteration ${i}`));
// Running iteration 0
// Running iteration 1
// Running iteration 2

// A higher order function that adds logging to any function
function withLogging(fn) {
  return function(...args) {
    console.log(`Calling function with args:`, args);
    const result = fn(...args);
    console.log(`Function returned:`, result);
    return result;
  };
}

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

const loggedAdd = withLogging(add);
loggedAdd(3, 4);
// Calling function with args: [3, 4]
// Function returned: 7

This pattern - wrapping one function with another - is used everywhere in real codebases. Express middleware is this pattern. React's higher order components are this pattern. The withLogging example above is a simplified version of what logging libraries actually do.

Common Mistakes With Callbacks

Calling the callback instead of passing it:

// Wrong - greet() is called immediately, its return value (undefined) is passed
processUser("Rahul", greet());

// Correct - greet function reference is passed, to be called later
processUser("Rahul", greet);

This is one of the most common beginner mistakes. Adding () calls the function right there. Without (), you are passing the function itself.

Calling the callback more than once:

function doSomething(callback) {
  callback("first call");
  callback("second call"); // this is a bug - callback called twice
}

In most patterns, a callback should be called exactly once. Calling it multiple times causes unexpected behavior, especially in async code.

Forgetting to return after calling the callback in error cases:

// Bug - both branches run
function process(data, callback) {
  if (!data) {
    callback(new Error("No data"));
    // forgot return - code continues below
  }
  callback(null, data.toUpperCase()); // crashes because data is null
}

// Correct
function process(data, callback) {
  if (!data) {
    callback(new Error("No data"));
    return; // stop here
  }
  callback(null, data.toUpperCase());
}

Always return after calling the callback in an error branch. Without it, the function keeps running and the callback might get called a second time.

The Mental Model Worth Keeping

A callback is just a function you hand to someone else and say "call this when you are ready." That is it.

JavaScript uses callbacks heavily because it is single threaded and needs a way to say "do this thing, and when it is done, run this code" - without blocking everything while waiting. Callbacks were the original answer to that problem.

They are not outdated. They are still the right tool for event listeners, array methods, and simple async operations. For complex sequences of async operations, Promises and async/await are cleaner - but they are built on the same callback concept underneath.

Once callbacks click properly, Promises make more sense. And once Promises make sense, async/await becomes obvious. They are not separate concepts - they are the same idea, getting cleaner with each version.

Read full article on CodeKK

Read full article on CodeKK

If you've been writing JavaScript for a while, you've probably heard the phrase "JavaScript is single threaded." And if you've read our blog on synchronous and asynchronous in Node.js, you already know that JavaScript handles async tasks without blocking everything else.

But here's the question most tutorials stop short of answering: if JavaScript can only do one thing at a time, how does it handle a timer, a fetch call, and a user click all seemingly at the same time without freezing?

The answer is the Event Loop. And once you truly understand it, a lot of things about JavaScript that felt confusing or unpredictable will suddenly make complete sense.

The Problem the Event Loop Solves

Let's set the stage properly.

JavaScript runs on a single thread. That means it has one call stack, one piece of code running at any given moment. There's no parallel execution happening inside JavaScript itself.

But your browser or Node.js server needs to handle multiple things at the same time - responding to clicks, fetching data, running timers, handling multiple incoming requests. If JavaScript truly blocked on every slow operation, no web app would be usable.

The Event Loop is the mechanism that lets JavaScript appear to handle multiple things concurrently, even though it's technically doing one thing at a time. It does this by being very smart about how it manages waiting time.

The Moving Parts - What You Need to Know First

Before explaining how the event loop works, you need to know the pieces it works with. There are four of them.

The Call Stack

This is where your JavaScript code actually executes. Every time you call a function, it gets pushed onto the call stack. When that function returns, it gets popped off. JavaScript executes whatever is at the top of the stack.

function greet(name) {
  return `Hello, ${name}`;
}

function main() {
  const message = greet("Rahul");
  console.log(message);
}

main();

Here's what happens on the call stack step by step:

1. main() is pushed onto the stack
2. greet("Rahul") is pushed onto the stack
3. greet() returns "Hello, Rahul" and is popped off
4. console.log() is pushed onto the stack
5. console.log() finishes and is popped off
6. main() finishes and is popped off
7. Stack is empty

Simple, predictable, top to bottom. The issue is that some things take time - and if a slow operation sat on the call stack, nothing else could run until it finished.

Web APIs / Node.js APIs

These are capabilities provided by the environment JavaScript is running in, not by JavaScript itself. Things like setTimeout, fetch, file system operations, DOM event listeners - these are not part of the JavaScript language. They're provided by the browser or Node.js, and crucially, they run outside the call stack.

When JavaScript hits a setTimeout or a fetch, it hands that task off to the browser/Node.js API layer and immediately moves on. The API handles the waiting. JavaScript's call stack is free.

The Callback Queue (also called the Task Queue or Macrotask Queue)

When a Web API finishes its work - a timer fires, a fetch returns, a user clicks something - it doesn't immediately put code back on the call stack. Instead, it places the associated callback into the Callback Queue. It waits there until the call stack is empty.

The Microtask Queue

This is a separate, higher priority queue. Promises and certain other operations use this queue instead of the Callback Queue. The difference in priority is important - we'll get to that shortly.

How the Event Loop Ties All of This Together

The Event Loop has one job: check if the call stack is empty, and if it is, take something from one of the queues and push it onto the stack.

That's it. That's the event loop. It's a loop that keeps checking:

Is the call stack empty?
  - Yes: is there anything in the Microtask Queue? 
      - Yes: push it to the call stack and run it
      - No: is there anything in the Callback Queue?
          - Yes: push it to the call stack and run it
  - No: wait, check again

This loop runs continuously. It never stops. Every tick of this loop is one cycle - check the stack, check the queues, push something if available, repeat.

Seeing It in Action - setTimeout

Let's trace through a real example:

console.log("1 - Start");

setTimeout(() => {
  console.log("2 - Inside timeout");
}, 0);

console.log("3 - End");

Most beginners expect this to print 1, 2, 3 because they see a zero millisecond delay and think "that's instant." But the actual output is:

1 - Start
3 - End
2 - Inside timeout

Here's exactly what happens:

1. console.log("1 - Start") is pushed to the call stack, runs, logs "1 - Start", gets popped off

2. setTimeout(callback, 0) is pushed to the call stack. JavaScript sees it's a Web API call, hands the callback and the timer to the browser API layer, and immediately pops setTimeout off the stack

3. The browser starts a 0ms timer (it's nearly instant but still async)

4. console.log("3 - End") is pushed to the stack, runs, logs "3 - End", gets popped off

5. The call stack is now empty

6. The browser's timer finishes, puts the callback into the Callback Queue

7. The Event Loop sees the call stack is empty and the Callback Queue has something - it pushes the callback to the call stack

8. The callback runs, logs "2 - Inside timeout", gets popped off

The zero milliseconds doesn't mean "run immediately." It means "run as soon as possible after the current call stack is empty." That distinction matters a lot in practice.

The Microtask Queue - Why Promises Behave Differently

Now here's where it gets more interesting. Not all async callbacks go to the same queue.

Promises use the Microtask Queue, which has higher priority than the Callback Queue. After every task that runs on the call stack, the event loop completely drains the Microtask Queue before it even looks at the Callback Queue.

If you've read our blog on synchronous and asynchronous in Node.js and you've used Promises or async/await, this is why they behave the way they do under the hood.

console.log("1 - Start");

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

Promise.resolve().then(() => {
  console.log("3 - Promise");
});

console.log("4 - End");

Output:

1 - Start
4 - End
3 - Promise
2 - setTimeout

Let's trace through this:

1. console.log("1 - Start") runs immediately - call stack

2. setTimeout callback gets handed to the browser API, will go to the Callback Queue when timer fires

3. Promise.resolve().then(callback) - the promise is already resolved, so the callback goes straight to the Microtask Queue

4. console.log("4 - End") runs immediately - call stack

5. Call stack is now empty

6. Event Loop checks the Microtask Queue first - finds the Promise callback, runs it, logs "3 - Promise"

7. Microtask Queue is now empty

8. Event Loop checks the Callback Queue - finds the setTimeout callback, runs it, logs "2 - setTimeout"

The Promise ran before the setTimeout even though both were async. This isn't random - it's because of the queue priority. Microtasks always go before macrotasks (callback queue items).

Async/Await Is Just Promises in Disguise

If you use async/await (which we covered in detail in our sync and async Node.js blog), you're still dealing with the Microtask Queue. await is essentially Promise.then written in a more readable way.

async function fetchData() {
  console.log("1 - Before await");
  
  const result = await Promise.resolve("data");
  
  console.log("3 - After await:", result);
}

console.log("Start");
fetchData();
console.log("2 - After calling fetchData");

Output:

Start
1 - Before await
2 - After calling fetchData
3 - After await: data

When JavaScript hits the await keyword, the async function pauses and returns control to the caller. Whatever comes after await inside that function is essentially a .then() callback waiting in the Microtask Queue. The code outside the function ("2 - After calling fetchData") runs first because it's still on the main call stack. Once the call stack clears, the continuation of the async function runs from the Microtask Queue.

This is why in Next.js Server Components (which we covered in the SSR, CSR, SSG, and ISR blog), async components work the way they do - the await inside them pauses that component's execution while the rest of the rendering pipeline continues.

A More Complex Example - Putting It All Together

Here's an example that combines everything, the kind that shows up in JavaScript interviews and genuinely tests whether you understand the event loop:

console.log("1");

setTimeout(() => console.log("2"), 0);

Promise.resolve()
  .then(() => {
    console.log("3");
    setTimeout(() => console.log("4"), 0);
  })
  .then(() => console.log("5"));

setTimeout(() => console.log("6"), 0);

console.log("7");

Before reading the answer, take a moment and try to trace through it using what you know now.

Output:

1
7
3
5
2
6
4

Here's why:

• 1 and 7 run synchronously on the call stack first

• Two setTimeout callbacks (for 2 and 6) go to the Callback Queue

• The first Promise .then callback (for 3) goes to the Microtask Queue

• Call stack empties

• Microtask Queue runs first - 3 logs. Inside that callback, a new setTimeout for 4 is registered, going to the Callback Queue

• The .then(() => console.log("5")) chained on the same Promise goes to the Microtask Queue next

• Microtask Queue runs - 5 logs

• Microtask Queue is now empty

• Callback Queue runs - 2 then 6 then 4 in the order they were added

Notice that 4 comes after 6 even though the Promise that created the 4 setTimeout ran before 6's setTimeout was registered. By the time the Microtask Queue finished and we started draining the Callback Queue, 2 and 6 were already sitting there waiting, so they ran first.

Why This Matters in Node.js Specifically

In a browser, a blocked call stack means your UI freezes. In Node.js, a blocked call stack means your entire server stops responding to every other request while it waits.

This is why synchronous operations in request handlers are so dangerous in Node.js - something we explained in the Node.js and Express blog.

// This blocks the entire event loop
app.get("/users", (req, res) => {
  const data = fs.readFileSync("users.json"); // synchronous - blocks everything
  res.json(JSON.parse(data));
});

// This doesn't - the event loop stays free
app.get("/users", async (req, res) => {
  const data = await fs.promises.readFile("users.json"); // async - non-blocking
  res.json(JSON.parse(data));
});

When the synchronous version hits readFileSync, it sits on the call stack and blocks. No other request can be handled. No timers fire. Nothing moves until that file is read.

When the async version hits await, it hands the file reading to Node.js's underlying I/O layer, the function pauses and exits the call stack, and the event loop is free to handle other requests. When the file is ready, the continuation goes into the Microtask Queue and picks up where it left off.

This is why Node.js can handle thousands of concurrent connections on a single thread. It's not doing them all simultaneously - it's managing the waiting time so efficiently that it seems like it is.

One Thing That Can Still Break Everything - Blocking the Event Loop

Even with all of this in place, you can still accidentally block the event loop with pure JavaScript code that runs for too long.

// This blocks the event loop completely
app.get("/compute", (req, res) => {
  let sum = 0;
  for (let i = 0; i < 10_000_000_000; i++) {
    sum += i;
  }
  res.json({ sum });
});

This loop is pure synchronous JavaScript. There's no I/O, no async, no Web API to hand off to. It just runs on the call stack until it finishes - and nothing else can happen during that time. Every other request to your server is frozen while this runs.

This is why CPU-heavy work (like image processing, complex calculations, or large data transformations) in Node.js should be moved to worker threads or separate processes, not handled in the main event loop. The event loop is designed for I/O-heavy workloads where most of the time is spent waiting, not computing.

The Node.js Event Loop Has Extra Phases

The browser's event loop and Node.js's event loop are similar in concept but Node.js has additional phases built on top. Node.js uses a library called libuv under the hood, and its event loop has specific phases for things like:

• Timers (setTimeout, setInterval)

• I/O callbacks (file system, network)

• setImmediate callbacks (a Node.js specific API)

• Close callbacks (cleanup)

For most day to day Node.js development you don't need to know these phases in detail. But if you ever wonder why setImmediate fires before a setTimeout(fn, 0) in certain situations in Node.js, it's because of these phases running in a specific order. Worth knowing it exists even if you don't need to memorize the details.

The Mental Model Worth Keeping

After all of this, here's the simplest version you can hold in your head:

JavaScript has one call stack. Slow things get handed off to the environment (browser or Node.js) and come back later through queues. The event loop keeps checking: is the stack empty? Run microtasks first (Promises, await continuations), then macrotasks (setTimeout, setInterval, I/O callbacks).

Synchronous code always runs first. Microtasks run next, completely, before any macrotask gets a chance. Macrotasks run one at a time, with a full microtask drain between each one.

Once this clicks, JavaScript's async behavior stops feeling unpredictable. It starts feeling logical, because it is.

Read full article on CodeKK

If you've built any kind of API that needs authentication, you've probably used JWT or at least heard of it. Most developers know enough to copy a working example, generate a token on login, and verify it on protected routes. But if someone asked you to explain what's actually inside that token, how the verification works without a database call, or what happens if someone tries to tamper with it - could you answer that clearly?

This blog covers all of that. Not just how to implement JWT, but how it actually works underneath, so you can use it confidently and understand the security decisions you're making.

The Problem JWT Solves

Before getting into what JWT is, it helps to understand why it exists.

HTTP is stateless. Every request your server receives is completely independent - the server has no memory of previous requests by default. So when a user logs in and then makes a request to a protected route, the server has no built-in way to know that this request is coming from someone who already authenticated.

The traditional solution to this is sessions. When a user logs in, the server creates a session, stores it in memory or a database, and sends back a session ID in a cookie. On every subsequent request, the browser sends that cookie, the server looks up the session ID in storage, finds the user, and proceeds.

This works, but it has a real limitation. Every request requires a database lookup to validate the session. At scale, this adds up. It also gets complicated when you have multiple servers - if a user's session is stored on Server A, requests that hit Server B won't find it.

JWT takes a different approach. Instead of storing session data on the server, the server gives the client a token that contains the user information itself. The client sends this token on every request, and the server can verify it and read the user data from it - without touching a database at all.

What a JWT Actually Is

JWT stands for JSON Web Token. It's a string that looks like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiZW1haWwiOiJyYWh1bEBleGFtcGxlLmNvbSIsInJvbGUiOiJ1c2VyIiwiaWF0IjoxNzE2MDAwMDAwLCJleHAiOjE3MTYwODY0MDB9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

It looks like gibberish but it's actually three distinct parts separated by dots. Each part is Base64URL encoded - meaning it's just regular data encoded into a URL-safe string format. It's not encrypted. Anyone can decode it and read what's inside.

The three parts are the header, the payload, and the signature.

Part 1 - The Header

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

The header tells you what type of token this is and which algorithm was used to create the signature. HS256 means HMAC with SHA-256, which is the most common signing algorithm for JWTs.

Part 2 - The Payload

{
  "id": 1,
  "email": "rahul@example.com",
  "role": "user",
  "iat": 1716000000,
  "exp": 1716086400
}

This is the actual data. The fields you put here are called claims. Some are standard - iat is "issued at" (a Unix timestamp of when the token was created) and exp is "expires at" (when the token stops being valid). Everything else is custom data you add based on what your application needs.

iat and exp are Unix timestamps - seconds since January 1, 1970. The difference between those two timestamps above is 86400 seconds, which is exactly 24 hours. So this token is valid for one day.

Part 3 - The Signature

This is the part that makes JWT secure. The signature is created by taking the encoded header, the encoded payload, a secret key that only your server knows, and running them through the hashing algorithm specified in the header.

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  your-secret-key
)

The resulting signature is what gets appended as the third part of the token.

When your server receives a token, it takes the header and payload from that token, runs the same HMAC operation with its secret key, and compares the result to the signature in the token. If they match, the token is valid and hasn't been tampered with. If someone changed even a single character in the payload, the signature would no longer match.

This is the key insight: the server never needs to store the token or look it up in a database. It just needs its secret key to verify any token it receives. The math does the work.

The JWT Flow - How It Works in Practice

Here's the complete flow from login to accessing a protected route:

1. User sends email and password to POST /api/auth/login

2. Server checks credentials against the database
   - If wrong: return 401 Unauthorized
   - If correct: continue

3. Server creates a JWT containing the user's id, email, role
   Signs it with the secret key
   Sets an expiry time

4. Server sends the JWT back to the client

5. Client stores the token (localStorage or a cookie)
   Sends it in the Authorization header on future requests:
   Authorization: Bearer <token>

6. Server receives the request, extracts the token from the header
   Verifies the signature using the secret key
   Checks the expiry time
   If valid: reads the user data from the payload, processes the request
   If invalid or expired: return 401 Unauthorized

Notice that step 6 involves zero database calls for the verification itself. The server just does cryptographic verification. That's the performance advantage of JWT over session-based auth.

Building JWT Auth in Express - Step by Step

If you've set up an Express server following our Node.js and Express blog, this is how you add JWT authentication on top of it.

First install the jsonwebtoken package:

npm install jsonwebtoken bcryptjs

We're also installing bcryptjs because you should never store plain text passwords. We'll hash them before saving and compare hashes on login.

Setting up your secret key:

Your JWT secret key should be a long random string that only your server knows. Store it in an environment variable, never hardcode it.

JWT_SECRET=your-very-long-random-secret-key-here-make-it-at-least-32-characters

The login route - generating a token:

const express = require("express");
const jwt = require("jsonwebtoken");
const bcrypt = require("bcryptjs");
const router = express.Router();

// Simulated user database - in a real app this comes from your actual database
const users = [
  {
    id: 1,
    email: "rahul@example.com",
    // this is the bcrypt hash of "password123"
    password: "$2a$10$92IXUNpkjO0rOQ5byMi.Ye4oKoEa3Ro9llC/.og/at2.uheWG/igi"
  }
];

router.post("/login", async (req, res) => {
  try {
    const { email, password } = req.body;

    // find the user
    const user = users.find(u => u.email === email);
    if (!user) {
      return res.status(401).json({ error: "Invalid credentials" });
    }

    // compare the provided password with the stored hash
    const isPasswordValid = await bcrypt.compare(password, user.password);
    if (!isPasswordValid) {
      return res.status(401).json({ error: "Invalid credentials" });
    }

    // create the token
    const token = jwt.sign(
      {
        id: user.id,
        email: user.email
      },
      process.env.JWT_SECRET,
      { expiresIn: "24h" }
    );

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

  } catch (err) {
    res.status(500).json({ error: "Internal server error" });
  }
});

module.exports = router;

A few things worth explaining here. We return the same error message "Invalid credentials" whether the email doesn't exist or the password is wrong. This is intentional - if you returned different messages for each case, an attacker could use your login endpoint to figure out which emails are registered in your system. Keeping the error generic prevents that.

jwt.sign() takes three arguments - the payload (what to put in the token), the secret key, and options. The expiresIn option accepts a string like "24h", "7d", or "15m", or a number in seconds.

The authentication middleware:

This is what protects your routes. It runs before your route handler and either allows the request through or rejects it. If you want to understand middleware more deeply, we covered it in the Node.js and Express blog.

const jwt = require("jsonwebtoken");

function authenticate(req, res, next) {
  // get the token from the Authorization header
  const authHeader = req.headers.authorization;

  if (!authHeader || !authHeader.startsWith("Bearer ")) {
    return res.status(401).json({ error: "No token provided" });
  }

  const token = authHeader.split(" ")[1]; // extract the token after "Bearer "

  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded; // attach the decoded user data to the request
    next();
  } catch (err) {
    if (err.name === "TokenExpiredError") {
      return res.status(401).json({ error: "Token has expired" });
    }
    return res.status(401).json({ error: "Invalid token" });
  }
}

module.exports = authenticate;

jwt.verify() does two things at once - it verifies the signature and checks the expiry. If either fails, it throws an error. We catch that error and return an appropriate response. The TokenExpiredError check is useful because it lets the client know specifically that the token expired, so it can redirect to login rather than showing a generic error.

When verification succeeds, decoded contains the payload we put in the token - the user's id and email. We attach it to req.user so any route handler after this middleware can access it.

Using the middleware on protected routes:

const express = require("express");
const authenticate = require("../middleware/authenticate");
const router = express.Router();

// public route - no middleware
router.get("/public", (req, res) => {
  res.json({ message: "Anyone can see this" });
});

// protected route - requires valid token
router.get("/profile", authenticate, (req, res) => {
  // req.user is available here because authenticate attached it
  res.json({
    message: "This is your profile",
    user: req.user
  });
});

// protected route - only admins
router.delete("/users/:id", authenticate, authorizeAdmin, (req, res) => {
  res.json({ message: `User ${req.params.id} deleted` });
});

module.exports = router;

The authenticate middleware is passed directly as an argument before the route handler. Express calls them in order - first authenticate runs, and if it calls next(), then the route handler runs. If authenticate returns a 401, the route handler never runs at all.

Role-based authorization:

Authentication answers "who are you?" Authorization answers "what are you allowed to do?" They're different things. Here's a simple authorization middleware that checks for an admin role:

function authorizeAdmin(req, res, next) {
  if (req.user.role !== "admin") {
    return res.status(403).json({ error: "Admin access required" });
  }
  next();
}

Notice it returns 403 (Forbidden) not 401 (Unauthorized). The user is authenticated - we know who they are. They're just not permitted to do this specific thing. If you want a refresher on the difference between 401 and 403, we covered exactly this in the HTTP status codes blog.

Where to Store the Token on the Client Side

This is a security decision worth thinking about properly. You have two main options.

localStorage

Easy to use from JavaScript, persists across browser sessions. The downside is that it's accessible to any JavaScript running on your page. If your app has an XSS (Cross-Site Scripting) vulnerability - where an attacker can inject JavaScript into your page - they can steal tokens straight out of localStorage.

HttpOnly Cookies

Cookies with the HttpOnly flag cannot be accessed by JavaScript at all. They're automatically sent with every request to the same domain, and attackers cannot read them through XSS because JavaScript simply has no access to HttpOnly cookies. This makes them safer for storing auth tokens.

The tradeoff is that cookies require more setup and you need to handle CORS correctly - which we covered in detail in the CORS blog. Specifically, you need credentials: true in your CORS configuration and Access-Control-Allow-Credentials: true in your response headers for cookies to be sent on cross-origin requests.

For most applications, HttpOnly cookies are the more secure choice. For simpler APIs where XSS is well-controlled, localStorage is commonly used and works fine. Both have tradeoffs - the important thing is making the choice consciously, not just going with whatever the tutorial used.

Token Expiry and Refresh Tokens

Short-lived tokens are more secure. If a token gets stolen somehow, a 15-minute expiry means the attacker only has a 15-minute window to use it. But asking users to log in every 15 minutes is a bad experience.

The solution is a refresh token system. Here's how it works:

When a user logs in, the server issues two tokens:

1. An access token - short-lived (15 minutes to 1 hour), used for API requests

2. A refresh token - long-lived (7 to 30 days), used only to get new access tokens

The access token is what you send in the Authorization header on every request. When it expires, instead of redirecting to login, the client sends the refresh token to a special endpoint like POST /api/auth/refresh. The server validates the refresh token and issues a new access token.

router.post("/refresh", async (req, res) => {
  const { refreshToken } = req.body;

  if (!refreshToken) {
    return res.status(401).json({ error: "Refresh token required" });
  }

  try {
    const decoded = jwt.verify(refreshToken, process.env.JWT_REFRESH_SECRET);

    // issue a new short-lived access token
    const newAccessToken = jwt.sign(
      { id: decoded.id, email: decoded.email },
      process.env.JWT_SECRET,
      { expiresIn: "15m" }
    );

    res.json({ accessToken: newAccessToken });

  } catch (err) {
    return res.status(401).json({ error: "Invalid or expired refresh token" });
  }
});

Refresh tokens use a different secret key (JWT_REFRESH_SECRET) from access tokens. This way, even if one key is somehow compromised, the other isn't affected.

This pattern is used by most production authentication systems and gives you the security of short-lived tokens without constantly asking users to log in again.

What JWT Does Not Solve

JWT is not a complete authentication solution on its own and it's worth being clear about its limitations.

You cannot invalidate a JWT before it expires. This is the most cited limitation. Since the server doesn't store tokens, there's no way to say "this token is no longer valid" without waiting for it to expire naturally. If a user logs out, the token still technically works until it expires. If an account is compromised and you want to revoke access immediately, you can't without either maintaining a token blocklist (which adds back the database lookup you were trying to avoid) or using very short expiry times with refresh tokens.

The payload is readable by anyone. Base64URL encoding is not encryption. Anyone who has the token can decode and read its payload. Never put sensitive information in a JWT payload - no passwords, no credit card numbers, no private data. Only put what the server needs to identify and authorize the user.

The secret key must stay secret. If your JWT_SECRET is exposed, anyone can generate valid tokens for any user. Keep it in environment variables, rotate it if you think it's been compromised, and make it long and random.

Putting It All Together

Here's how your Express app structure looks with JWT auth added:

src/
- middleware/
    authenticate.js     (verifies token, adds req.user)
    authorizeAdmin.js   (checks role)
- routes/
    auth.js            (login, refresh)
    users.js           (protected routes using authenticate middleware)
- index.js             (main server file)

// index.js
const express = require("express");
const cors = require("cors");
const authRoutes = require("./routes/auth");
const userRoutes = require("./routes/users");

const app = express();

app.use(cors({ origin: "http://localhost:5173", credentials: true }));
app.use(express.json());

app.use("/api/auth", authRoutes);
app.use("/api/users", userRoutes);

app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({ error: "Internal server error" });
});

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

Clean, organized, and each piece has a clear job. The CORS setup here directly uses what we covered in the CORS blog - specific origin and credentials enabled for cookie support.

The Mental Model Worth Keeping

JWT works because of cryptographic signatures, not storage. The server signs a token with a secret key. Anyone can read the token, but nobody can change it without invalidating the signature. The server verifies that signature on every request using the same secret key.

That's the whole system. The header says what algorithm was used. The payload carries the data. The signature proves nothing was tampered with.

Use short expiry times. Store tokens in HttpOnly cookies when security matters. Never put sensitive data in the payload. Keep your secret key actually secret.

Once you understand the mechanism, JWT stops feeling like magic and starts feeling like a sensible solution to a straightforward problem.

Read full article on CodeKK

If you have been writing JavaScript or Node.js for any amount of time, you have come across words like async, await, callbacks, and Promises. Maybe you understood them well enough to get your code working. Maybe you just copied a pattern from Stack Overflow and moved on.

But if someone asked you to explain what asynchronous actually means, or why Node.js handles things differently from other languages - could you answer that clearly?

This blog is about building that understanding properly. Not just how to write async code, but why it works the way it does.

Start Here - What Synchronous Actually Means

Synchronous means one thing at a time, in order. Each line of code runs, finishes completely, and only then does the next line start.

console.log("First");
console.log("Second");
console.log("Third");

Output:

First
Second
Third

Simple. Predictable. Each line waits for the one before it.

Now here is where it becomes a problem. Some tasks take time - reading a file from disk, fetching data from an API, querying a database. If JavaScript ran these synchronously, it would stop everything and wait for each task to finish before moving to the next one.

// Imagine this is a synchronous database call
const users = database.getUsers(); // waits 500ms
const orders = database.getOrders(); // waits 500ms after users finishes
const products = database.getProducts(); // waits 500ms after orders finishes

console.log("Done"); // only runs after 1500ms total

In a server handling hundreds of requests, this would be a disaster. Every request would have to wait in line while the previous one finishes. One slow database query would block everything else.

This is exactly the problem Node.js was designed to solve.

JavaScript is Single Threaded - And That is Fine

Here is something that surprises a lot of developers: JavaScript runs on a single thread. It can only do one thing at a time.

But then how does it handle multiple requests without blocking? How does it run code after a delay without freezing everything?

The answer is the Event Loop - and understanding it changes how you think about asynchronous code entirely.

The Event Loop - The Heart of Node.js

Think of the event loop like a chef in a kitchen. The chef cannot cook two dishes at the exact same time with their own hands. But they can put something in the oven, set a timer, and while that is baking, start chopping vegetables. When the timer goes off, they go back to the oven.

The chef is single threaded. But they are not blocked waiting for the oven.

Node.js works the same way. When it hits a task that will take time - like a file read or a network request - it hands that task off to the operating system and moves on to the next thing. When the operating system finishes the task, it puts the result in a queue. The event loop keeps checking that queue and runs the callback when it is ready.

Your Code -> Hits async task -> Hands it off -> Moves to next line
                                     |
                        OS handles the slow task
                                     |
                        Task finishes -> Result goes into queue
                                     |
                        Event loop picks it up -> Runs your callback

This is why Node.js can handle thousands of concurrent connections without needing thousands of threads. It is not doing multiple things at once - it is managing its waiting time efficiently.

Synchronous Code in Node.js

Node.js has both synchronous and asynchronous versions of most built-in operations. The synchronous ones block everything until they finish.

const fs = require("fs");

// Synchronous - blocks everything until the file is read
const data = fs.readFileSync("users.txt", "utf8");
console.log(data);
console.log("This only runs after the file is fully read");

The Sync at the end of readFileSync is the signal. It means - stop here, wait for this to finish, then continue.

This is fine in some situations - like a startup script that reads a config file before your server starts. But inside a request handler that thousands of users hit? Never use synchronous file or network operations there. You will block every other user while one person's request is being handled.

Asynchronous Code - Three Ways to Write It

JavaScript has gone through three different patterns for writing async code. You will see all three in the wild so it is worth understanding each one.

1. Callbacks - The Original Way

A callback is a function you pass into another function, to be called when the async task finishes.

const fs = require("fs");

fs.readFile("users.txt", "utf8", function(err, data) {
  if (err) {
    console.error("Error reading file:", err);
    return;
  }
  console.log(data);
});

console.log("This runs immediately, before the file is read");

Output:

This runs immediately, before the file is read
(file contents appear here after the file is read)

The readFile call does not block. Node.js hands the file reading to the OS, moves to the next line, and when the file is ready, calls your callback function with the result.

The err parameter comes first - this is a Node.js convention called error-first callbacks. Always check for errors before using the data.

The problem with callbacks - Callback Hell:

When you need to do multiple async tasks in sequence, callbacks start nesting inside each other:

fs.readFile("users.txt", "utf8", function(err, users) {
  if (err) return console.error(err);

  fs.readFile("orders.txt", "utf8", function(err, orders) {
    if (err) return console.error(err);

    fs.readFile("products.txt", "utf8", function(err, products) {
      if (err) return console.error(err);

      // Finally do something with all three files
      console.log(users, orders, products);
    });
  });
});

This is called callback hell - code that keeps nesting deeper and deeper to the right. Hard to read, hard to maintain, hard to handle errors properly. This pattern led to Promises.

2. Promises - A Cleaner Way

A Promise is an object that represents a value that will be available in the future. It is either pending, resolved (success), or rejected (failure).

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

fs.readFile("users.txt", "utf8")
  .then(data => {
    console.log(data);
  })
  .catch(err => {
    console.error("Error:", err);
  });

console.log("This still runs immediately");

Promises let you chain .then() calls instead of nesting callbacks:

fs.readFile("users.txt", "utf8")
  .then(users => {
    console.log("Got users");
    return fs.readFile("orders.txt", "utf8"); // return next promise
  })
  .then(orders => {
    console.log("Got orders");
    return fs.readFile("products.txt", "utf8");
  })
  .then(products => {
    console.log("Got all three files");
  })
  .catch(err => {
    console.error("Something failed:", err);
  });

One .catch() at the end handles errors from any step in the chain. Much cleaner than nested callbacks.

Running multiple async tasks at the same time:

If the tasks do not depend on each other, you can run them in parallel using Promise.all:

Promise.all([
  fs.readFile("users.txt", "utf8"),
  fs.readFile("orders.txt", "utf8"),
  fs.readFile("products.txt", "utf8")
])
  .then(([users, orders, products]) => {
    console.log("All three files ready at the same time");
  })
  .catch(err => {
    console.error("One of them failed:", err);
  });

Instead of waiting 500ms + 500ms + 500ms in sequence, all three run at the same time and you wait for whichever takes the longest. Significantly faster.

3. Async/Await - The Modern Way

Async/await is built on top of Promises. It does not replace them - it is just a cleaner syntax for working with them. Code that uses async/await looks almost like synchronous code, which makes it much easier to read.

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

async function readFiles() {
  try {
    const users = await fs.readFile("users.txt", "utf8");
    console.log("Got users:", users);

    const orders = await fs.readFile("orders.txt", "utf8");
    console.log("Got orders:", orders);

    return { users, orders };
  } catch (err) {
    console.error("Something went wrong:", err);
  }
}

readFiles();
console.log("This still runs immediately - readFiles is async");

The await keyword pauses execution inside the async function until the Promise resolves - but it does not block the event loop. Other code can still run while this function is waiting.

The async keyword before a function means it always returns a Promise. You cannot use await inside a function that is not marked async.

Async/await with parallel execution:

You can still use Promise.all with async/await:

async function readAllFiles() {
  try {
    const [users, orders, products] = await Promise.all([
      fs.readFile("users.txt", "utf8"),
      fs.readFile("orders.txt", "utf8"),
      fs.readFile("products.txt", "utf8")
    ]);

    console.log("All files ready");
    return { users, orders, products };
  } catch (err) {
    console.error("Error:", err);
  }
}

Clean, readable, and all three files are fetched in parallel.

A Real Express Example - Async in Practice

This is what async/await looks like in a real Node.js and Express API. Imagine you are fetching a user from a database:

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

// Simulating a database call that takes time
function getUserFromDB(id) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (id === 1) {
        resolve({ id: 1, name: "Rahul", email: "rahul@example.com" });
      } else {
        reject(new Error("User not found"));
      }
    }, 300); // simulates 300ms database delay
  });
}

app.get("/users/:id", async (req, res) => {
  try {
    const user = await getUserFromDB(parseInt(req.params.id));
    res.json(user);
  } catch (err) {
    res.status(404).json({ error: err.message });
  }
});

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

While this route handler is waiting for the database, Node.js is free to handle other incoming requests. That is the event loop at work. No blocking, no waiting in line.

Common Mistakes With Async Code

Forgetting await

async function getUser() {
  const user = getUserFromDB(1); // missing await
  console.log(user); // logs Promise { <pending> } not the actual user
}

Without await, you get the Promise object itself, not the resolved value. Always check you have await in front of async calls.

Using await in a loop inefficiently

// Slow - each request waits for the previous one
async function getUsersSequentially(ids) {
  const users = [];
  for (const id of ids) {
    const user = await getUserFromDB(id); // waits for each one
    users.push(user);
  }
  return users;
}

// Fast - all requests run at the same time
async function getUsersInParallel(ids) {
  const users = await Promise.all(ids.map(id => getUserFromDB(id)));
  return users;
}

If the tasks inside a loop do not depend on each other, run them in parallel with Promise.all. The difference in speed can be significant with multiple database calls.

Not handling errors

// No error handling - if this fails, your server might crash
async function riskyOperation() {
  const data = await fetch("https://api.example.com/data").then(r => r.json());
  return data;
}

// Always wrap async operations in try/catch
async function safeOperation() {
  try {
    const data = await fetch("https://api.example.com/data").then(r => r.json());
    return data;
  } catch (err) {
    console.error("Fetch failed:", err);
    return null;
  }
}

Unhandled Promise rejections can crash your Node.js server. Always use try/catch in async functions.

Synchronous vs Asynchronous - When to Use Which

Use synchronous code when:

• Running setup tasks before your server starts (reading config files, checking environment variables)

• Writing simple scripts that run once and exit

• The task is instant and involves no I/O (calculations, string manipulation, array operations)

Use asynchronous code when:

• Reading or writing files during a request

• Making database queries

• Calling external APIs

• Anything that involves waiting for data from outside your application

The rule of thumb: if it involves the network, the file system, or a database - make it async.

The Mental Model Worth Keeping

Synchronous code runs line by line and blocks everything while waiting.

Asynchronous code starts a task, moves on, and comes back when the result is ready - without blocking anything else.

Node.js is built around this model. The event loop is what makes it work. Callbacks, Promises, and async/await are just different ways of writing code that works with this model - each one cleaner than the one before it.

If you are writing Node.js today, async/await is the pattern to default to. It is the most readable, the easiest to debug, and the one you will see in most modern codebases. Just remember it is still Promises underneath - and knowing that will help you when things get more complex.

Read full article on CodeKK

If you've been writing React for a while, you've used useEffect. Probably a lot. But if someone asked you to explain exactly when it runs, why it sometimes runs twice, or when you should avoid it entirely - could you answer confidently?

Most developers can't. And that's not because they're bad developers. It's because useEffect is one of those things that's easy to use but genuinely tricky to understand. You can build a lot of stuff with it while still having a fuzzy mental model of what's actually happening.

This blog is about fixing that.

Start Here - What useEffect Is Actually For

React components have one job: take some data (props and state) and return UI. That's it. The function runs, returns JSX, done.

But real apps need to do things beyond just rendering UI. Fetching data from an API. Setting up an event listener. Starting a timer. Connecting to a WebSocket. These are called side effects - things that happen outside of the normal render flow and interact with the world beyond your component.

useEffect is React's way of saying: "run this code after the render, as a side effect."

import { useEffect } from "react";

function ProfilePage({ userId }) {
  useEffect(() => {
    console.log("Component rendered");
  });

  return <div>Profile Page</div>;
}

This effect runs after every render. But that's rarely what you want, which brings us to the dependency array.

The Dependency Array - The Part Everyone Gets Wrong

useEffect takes two arguments. The first is the function you want to run. The second is the dependency array - and this is where most of the confusion lives.

useEffect(() => {
  // your effect code
}, [dependency1, dependency2]);

The dependency array tells React when to re-run the effect. There are three cases:

No dependency array - runs after every render:

useEffect(() => {
  console.log("Runs after every single render");
});

Every time your component re-renders for any reason - state change, parent re-render, anything - this effect runs. This is almost never what you want.

Empty dependency array - runs only once after the first render:

useEffect(() => {
  console.log("Runs once when component mounts");
}, []);

This runs exactly once - right after the component first appears on the screen. Common use case: fetching initial data.

With dependencies - runs when those specific values change:

useEffect(() => {
  console.log("userId changed, fetching new profile");
  fetchUserProfile(userId);
}, [userId]);

This runs after the first render and then again any time userId changes. If userId stays the same between renders, the effect is skipped.

The mental model worth keeping: React compares the current dependency values with the previous ones. If any of them changed, the effect runs again.

The Cleanup Function - Most Developers Skip This

Here's something a lot of developers don't know: useEffect can return a function. That returned function is the cleanup function and React calls it before running the effect again and when the component unmounts.

useEffect(() => {
  const intervalId = setInterval(() => {
    console.log("tick");
  }, 1000);

  // This is the cleanup function
  return () => {
    clearInterval(intervalId);
  };
}, []);

Without the cleanup here, every time this component mounts a new interval starts - and when the component unmounts, the interval keeps running in the background. Memory leak.

Another classic example with event listeners:

useEffect(() => {
  function handleResize() {
    setWindowWidth(window.innerWidth);
  }

  window.addEventListener("resize", handleResize);

  return () => {
    window.removeEventListener("resize", handleResize);
  };
}, []);

If you add an event listener inside useEffect and don't remove it in the cleanup, you end up with multiple listeners stacking up every time the component mounts. The cleanup function is not optional when you're working with timers, listeners, or subscriptions.

Why Does useEffect Run Twice in Development?

This catches almost every React developer off guard the first time they see it.

You write a useEffect with an empty dependency array. You expect it to run once. But in development, you check the console and it runs twice. What's going on?

This is intentional behavior introduced in React 18. In development mode, React's Strict Mode deliberately mounts your component, unmounts it, and mounts it again. The purpose is to help you find bugs - specifically, effects that don't clean up properly.

React is essentially doing this on purpose: "Let's simulate what happens if this component mounts, unmounts, and mounts again. Does the app still work correctly?"

If your effect breaks when run twice, that's a signal that you're missing a cleanup function.

// This will cause issues if run twice
useEffect(() => {
  fetchUserData(); // called twice in dev - not ideal but usually fine
}, []);

// This will definitely cause issues if run twice
useEffect(() => {
  const socket = connectToWebSocket();
  // No cleanup - two connections open in dev
}, []);

// This is correct
useEffect(() => {
  const socket = connectToWebSocket();
  return () => socket.disconnect(); // cleaned up properly
}, []);

This double-invocation only happens in development. In production, effects run exactly once when the dependency array is empty. So if your app behaves differently in prod vs dev, check your cleanup functions.

The Mistakes Developers Actually Make

1. Fetching Data Without Handling Cleanup

This is probably the most common one:

// Problematic version
useEffect(() => {
  fetch(`/api/users/${userId}`)
    .then(res => res.json())
    .then(data => setUser(data)); // can cause "state update on unmounted component" warning
}, [userId]);

If the user navigates away before the fetch completes, the component unmounts. But the fetch is still running and when it finishes, it tries to call setUser on a component that no longer exists.

The fix is to use an abort controller:

useEffect(() => {
  const controller = new AbortController();

  fetch(`/api/users/${userId}`, { signal: controller.signal })
    .then(res => res.json())
    .then(data => setUser(data))
    .catch(err => {
      if (err.name === "AbortError") return; // ignore aborted requests
      console.error(err);
    });

  return () => controller.abort();
}, [userId]);

Now when the component unmounts, the fetch is cancelled cleanly.

2. Missing Dependencies

React has an ESLint rule called exhaustive-deps that warns you when you're using a value inside useEffect but not including it in the dependency array. A lot of developers ignore or suppress this warning - which often causes subtle bugs.

// Bug waiting to happen
useEffect(() => {
  document.title = `Hello, ${userName}`; // uses userName
}, []); // but userName is not in the dependency array

// If userName changes, the title never updates

// Correct
useEffect(() => {
  document.title = `Hello, ${userName}`;
}, [userName]); // now it updates whenever userName changes

Don't ignore the exhaustive-deps warning. It exists for a reason.

3. Putting Everything in useEffect

This one is more of a design problem. A lot of developers reach for useEffect as the default place to "do stuff" - but a lot of things that end up in useEffect don't need to be there at all.

Transforming data for display? Do it during render, not in an effect.

// Unnecessary effect
const [fullName, setFullName] = useState("");

useEffect(() => {
  setFullName(`${firstName} ${lastName}`);
}, [firstName, lastName]);

// Just do this instead
const fullName = `${firstName} ${lastName}`;

Calculating derived state from existing state is not a side effect. Effects are for interacting with things outside React - APIs, the DOM, browser APIs, subscriptions.

4. Infinite Loops

This one causes the most panic:

// Infinite loop
const [count, setCount] = useState(0);

useEffect(() => {
  setCount(count + 1); // triggers re-render, effect runs again, triggers re-render...
}, [count]);

Every time count changes the effect runs, which changes count, which runs the effect again. If you ever see your app freezing or a "too many re-renders" error, check if you're updating state inside an effect that depends on that same state.

When You Should Not Use useEffect

The React team themselves have said this clearly in their documentation: a lot of useEffect usage is unnecessary and makes code harder to understand.

Here are cases where you should skip useEffect:

Transforming data for rendering - Just compute it directly in the component body.

Handling user events - Use event handlers, not effects. If you're writing useEffect that reacts to a button click, something is off.

Initializing app-level state - If you need something to run once when the app loads, put it outside the component entirely, not inside an effect.

The honest rule is: if you find yourself writing useEffect and thinking "this feels complicated", stop and ask whether it actually needs to be an effect at all.

A Clean useEffect Looks Like This

When you do need useEffect, here's what a clean, correct implementation looks like:

function UserProfile({ userId }) {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const controller = new AbortController();
    setLoading(true);

    fetch(`/api/users/${userId}`, { signal: controller.signal })
      .then(res => res.json())
      .then(data => {
        setUser(data);
        setLoading(false);
      })
      .catch(err => {
        if (err.name === "AbortError") return;
        setLoading(false);
      });

    return () => controller.abort();
  }, [userId]);

  if (loading) return <p>Loading...</p>;
  if (!user) return <p>User not found</p>;

  return <h1>{user.name}</h1>;
}

Clear dependency array. Cleanup function. Error handling. Aborts stale requests. This is what using useEffect correctly actually looks like.

The Mental Model Worth Keeping

After all of this, here's the simplest way to think about useEffect:

• It runs after the render, not during

• The dependency array controls when it runs again

• Always ask: does this need to be cleaned up?

• If you don't need to interact with something outside React, you probably don't need useEffect at all

Once these four things are second nature, you'll write fewer bugs, your components will be easier to reason about, and you'll stop reaching for useEffect as the solution to every problem.

Read full article on CodeKK

Read full article on CodeKK

Read full article on CodeKK

Read full article on CodeKK

Read full article on CodeKK

If you've built a frontend app that talks to a backend API, you've probably seen this error at some point:

Access to fetch at 'http://localhost:3000/api/users' from origin 
'http://localhost:5173' has been blocked by CORS policy: No 
'Access-Control-Allow-Origin' header is present on the requested resource.

Most developers at this point Google "how to fix CORS", find a Stack Overflow answer, copy a few lines of code, and move on. The error goes away and they never really understand what just happened or why.

That's a problem - because CORS errors show up again in production in ways that are harder to debug, and if you don't understand the mechanism, you end up either breaking things trying to fix them or making your API insecure without realizing it.

This blog explains what CORS actually is, why browsers enforce it, what happens under the hood when a request gets blocked, and how to handle it correctly in an Express API.

Start Here - What is an Origin

Before understanding CORS you need to understand what an "origin" is, because that's the core concept everything else builds on.

An origin is the combination of three things: the protocol, the domain, and the port.

http://localhost:5173

protocol: http
domain:   localhost
port:     5173

Two URLs have the same origin only if all three of these match exactly. If any one of them is different, they are considered different origins.

http://localhost:5173   and   http://localhost:3000   -> different origins (different port)
http://localhost:5173   and   https://localhost:5173  -> different origins (different protocol)
http://localhost:5173   and   http://codekk.dev       -> different origins (different domain)
http://localhost:5173   and   http://localhost:5173   -> same origin

This distinction matters because of something called the Same-Origin Policy.

The Same-Origin Policy - Why This Exists at All

Browsers have a built-in security rule called the Same-Origin Policy. It says that JavaScript running on one origin cannot read responses from a different origin by default.

This is not a bug or an accident. It is a deliberate security feature and understanding why it exists makes everything else make sense.

Imagine you are logged into your bank at https://mybank.com. Your browser has a session cookie stored for that bank. Now imagine you visit a malicious website at https://evil.com. That site has JavaScript that silently makes a request to https://mybank.com/api/transfer-money using your cookies - because your browser automatically sends cookies for any domain they belong to.

Without the Same-Origin Policy, that request would succeed and the bank's API would process it as if you made it yourself, because your cookies are attached. The malicious site's JavaScript could then read the response and steal your data.

The Same-Origin Policy prevents this. It blocks https://evil.com's JavaScript from reading responses from https://mybank.com. The request might go through, but the browser refuses to give the response to the JavaScript that made it if the origins don't match.

So CORS errors are not the browser being annoying. The browser is actively protecting users from a real class of attacks.

So What is CORS Then

CORS stands for Cross-Origin Resource Sharing. It is a mechanism that lets servers tell browsers "it's okay, this other origin is allowed to read my responses."

It works through HTTP headers. When a browser makes a cross-origin request, the server can include special headers in its response that say which origins, methods, and headers are permitted. If those headers are present and allow the requesting origin, the browser lets the JavaScript read the response. If they're not present or don't allow the requesting origin, the browser blocks it.

CORS is not a restriction added by the server. It's a relaxation of the browser's default restriction, controlled by the server.

That's an important distinction. The server decides who gets to talk to it across origins. The browser enforces that decision.

Why Your Localhost Setup Triggers CORS

This is the most common scenario. You have a React or Vite frontend running on http://localhost:5173 - if you read our blog on dark and light mode in React Vite, you know Vite runs on port 5173 by default.

Your Express backend is running on http://localhost:3000 - as we set up in the Node.js and Express blog.

Even though both are on localhost, they're on different ports. Different ports mean different origins. So when your frontend tries to call your backend API, the browser sees a cross-origin request and checks if the server allows it. If your Express server doesn't send back CORS headers, the browser blocks the response.

The request actually reaches your server. Your server processes it and sends a response. But the browser intercepts that response and refuses to give it to your JavaScript because the CORS headers are missing. This is why you'll sometimes see the request in your server logs even when the browser shows a CORS error.

Simple Requests vs Preflight Requests

Not all cross-origin requests work the same way. There are two types you need to know about.

Simple Requests

Some requests are considered "simple" and the browser just makes them directly. A simple request is a GET or POST with basic content types like text/plain or application/x-www-form-urlencoded, with no custom headers.

The browser makes the request, the server responds, and the browser checks the CORS headers. If they're missing or wrong, the browser blocks the JavaScript from reading the response.

Preflight Requests

For anything more complex - like a POST with Content-Type: application/json, a PUT, a DELETE, or a request with custom headers like Authorization - the browser first sends a preliminary request using the HTTP OPTIONS method. This is called a preflight request.

The browser is essentially asking the server: "Before I send this actual request, is this kind of request allowed from this origin?"

OPTIONS /api/users HTTP/1.1
Origin: http://localhost:5173
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Content-Type, Authorization

The server needs to respond to this preflight with the appropriate CORS headers saying what's allowed. Only if the preflight response says "yes, that's allowed" will the browser then send the actual request.

This is why sometimes a single API call in your browser's network tab shows two requests - an OPTIONS request followed by the actual one. That's the preflight happening.

If your server doesn't handle the OPTIONS method, the preflight fails, and your actual request never goes through. This trips up a lot of developers who handle GET and POST in their Express routes but forget about OPTIONS.

What the CORS Headers Actually Mean

Let's look at the headers involved so you know what you're actually configuring.

Access-Control-Allow-Origin

This is the most important one. It tells the browser which origin is allowed to read responses.

Access-Control-Allow-Origin: http://localhost:5173

This allows only your frontend origin. Or you can use a wildcard:

Access-Control-Allow-Origin: *

This allows any origin. Convenient for public APIs, but you should never use this for APIs that handle authenticated requests or sensitive data - because the wildcard cannot be combined with Access-Control-Allow-Credentials: true.

Access-Control-Allow-Methods

Tells the browser which HTTP methods are permitted.

Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS

Access-Control-Allow-Headers

Tells the browser which request headers are permitted.

Access-Control-Allow-Headers: Content-Type, Authorization

If you're sending a JSON body (Content-Type: application/json) or an auth token (Authorization: Bearer ...), these headers need to be listed here.

Access-Control-Allow-Credentials

This one is specifically for requests that include cookies or HTTP authentication. If you set this to true, the browser will include cookies in cross-origin requests and allow the JavaScript to read responses to those requests.

Access-Control-Allow-Credentials: true

Important: when Access-Control-Allow-Credentials is true, you cannot use * for Access-Control-Allow-Origin. You must specify the exact origin. This is a browser security rule that cannot be bypassed.

Access-Control-Max-Age

Tells the browser how long it can cache the preflight response, in seconds. This avoids sending an OPTIONS request before every single API call.

Access-Control-Max-Age: 86400

Fixing CORS in Express - The Right Way

Now that you understand what's happening, let's fix it properly. If you've set up an Express server following our Node.js and Express blog, this is where you add CORS support.

The standard approach is to use the cors npm package, which handles all the header setting for you.

npm install cors

Basic setup - allow all origins:

const express = require("express");
const cors = require("cors");

const app = express();

app.use(cors());

app.get("/api/users", (req, res) => {
  res.json({ users: [] });
});

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

app.use(cors()) with no configuration allows all origins. This is fine for a public API that has no authentication and serves non-sensitive data. Do not use this for authenticated APIs.

Specific origin - the correct approach for most apps:

const corsOptions = {
  origin: "http://localhost:5173",
  methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
  allowedHeaders: ["Content-Type", "Authorization"],
  credentials: true,
  maxAge: 86400
};

app.use(cors(corsOptions));

This locks CORS down to exactly your frontend origin, permits the methods and headers you actually need, and allows credentials if you're using cookies or auth tokens.

Multiple allowed origins:

In real projects you often have more than one frontend - a local development URL, a staging URL, and a production URL. Here's how to handle that:

const allowedOrigins = [
  "http://localhost:5173",
  "https://staging.codekk.dev",
  "https://codekk.dev"
];

const corsOptions = {
  origin: function (origin, callback) {
    // allow requests with no origin (like mobile apps or Postman)
    if (!origin) return callback(null, true);

    if (allowedOrigins.includes(origin)) {
      callback(null, true);
    } else {
      callback(new Error(`CORS policy: origin ${origin} is not allowed`));
    }
  },
  methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
  allowedHeaders: ["Content-Type", "Authorization"],
  credentials: true
};

app.use(cors(corsOptions));

The origin option here takes a function instead of a string. The function receives the incoming origin and a callback. If the origin is in the allowed list, you call callback(null, true) to allow it. If not, you call callback(new Error(...)) to reject it.

The !origin check handles tools like Postman, curl, or mobile app clients that don't send an Origin header. Without this, those requests would also get blocked.

Handling preflight requests explicitly:

The cors() middleware handles OPTIONS requests automatically when you use app.use(cors()). But if you're applying CORS to specific routes only and have complex routing, you might need to handle OPTIONS explicitly:

app.options("*", cors(corsOptions)); // handle preflight for all routes
app.use(cors(corsOptions));

The app.options("*", cors()) line tells Express to respond to OPTIONS requests on any route using the CORS middleware. This makes sure preflight requests get proper responses.

Doing It Without the cors Package

It's worth knowing how to set these headers manually, so you understand what the package is doing under the hood. This is also useful for situations where you're writing middleware yourself, similar to what we covered in the Node.js and Express blog.

app.use((req, res, next) => {
  res.setHeader("Access-Control-Allow-Origin", "http://localhost:5173");
  res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
  res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
  res.setHeader("Access-Control-Allow-Credentials", "true");

  // handle preflight
  if (req.method === "OPTIONS") {
    return res.status(200).end();
  }

  next();
});

This does exactly what the cors package does - sets the headers on every response and returns a 200 for OPTIONS preflight requests. Using the package is cleaner and handles edge cases for you, but knowing this manual version means you're never confused about what CORS middleware is actually doing.

Common Mistakes That Keep the Error Coming Back

Putting CORS after your routes

Middleware order matters in Express. If you register your routes before app.use(cors()), the CORS headers won't be on those responses. Always put app.use(cors()) before your route definitions.

// Wrong
app.get("/api/users", handler);
app.use(cors()); // too late

// Correct
app.use(cors()); // before routes
app.get("/api/users", handler);

Using wildcard with credentials

// This will not work - browser will throw an error
app.use(cors({
  origin: "*",
  credentials: true
}));

When credentials are involved, the browser requires a specific origin, not a wildcard. This is a hard browser rule. Specify the exact origin instead.

Forgetting to allow the Authorization header

If you're sending a JWT token in your request headers like Authorization: Bearer <token>, and you haven't listed Authorization in allowedHeaders, the preflight will fail and your request won't go through.

Only fixing the frontend

CORS is a server-side fix. You cannot solve CORS errors by changing your frontend code. The headers have to come from the server. If you see someone suggesting you add a proxy or change fetch options to fix CORS, that's a workaround for development only - not a real fix for production.

CORS in Production is Different From Development

In development, your frontend and backend are both on localhost with different ports. In production, they might be on completely different domains - your frontend on https://codekk.dev and your API on https://api.codekk.dev.

Make sure your production Express server's allowed origins list includes your actual production frontend URL, not just localhost. A common mistake is fixing CORS for development and then forgetting to update the configuration for production, which leads to a working local app and a broken production app.

Using environment variables for your allowed origins is the clean way to handle this:

const allowedOrigins = process.env.ALLOWED_ORIGINS
  ? process.env.ALLOWED_ORIGINS.split(",")
  : ["http://localhost:5173"];

const corsOptions = {
  origin: function (origin, callback) {
    if (!origin || allowedOrigins.includes(origin)) {
      callback(null, true);
    } else {
      callback(new Error("Not allowed by CORS"));
    }
  },
  credentials: true
};

Set ALLOWED_ORIGINS=https://codekk.dev in your production environment and http://localhost:5173 locally. No code changes needed between environments.

The One Line Summary

CORS errors happen because your browser's Same-Origin Policy blocked a cross-origin response. You fix them by having your server send the right headers telling the browser which origins, methods, and headers are allowed. The cors package in Express handles this cleanly, but knowing the manual version means you understand what's actually happening and can debug it confidently when things go wrong.

Next time you see that red CORS error in the console, you'll know exactly what caused it, exactly what the browser is protecting you from, and exactly what to change on the server to fix it properly.

Read full article on CodeKK

I searched a lot before writing this. Almost every tutorial out there either skips the reasoning and just hands you a code dump, or explains the theory without showing you a working result. You end up copying code that works, but you still don't actually understand why it works.

So this blog is built differently. Every step explains what we're doing and why we're doing it that way, not just what to type. By the end, you won't just have a dark mode toggle - you'll understand exactly how it works under the hood, and you'll be able to build it again from memory without copying anything.

Let's go.

What We're Actually Building

A simple product card component that switches between light and dark themes, with a toggle button that remembers your choice even after you refresh the page. We'll use React with Vite, TypeScript, and Tailwind CSS v4.

Before writing a single line of code, it helps to understand what "dark mode" actually means technically. It's not magic - it's just CSS classes changing based on a condition, and that condition being remembered somewhere. That's the entire concept. Everything else is just implementation detail.

Step 1: Setting Up the Project

Start by creating a new Vite project. We're using TypeScript here, but if you prefer plain JavaScript, the same logic applies - just remove the type annotations.

npm create vite@latest

Choose React as the framework and TypeScript as the variant. Once it's created, move into the folder and install dependencies as usual.

Why Vite instead of Create React App? Vite is significantly faster during development because it doesn't bundle your entire app every time you save a file. It uses native ES modules in the browser during development, so changes show up almost instantly. For a small project like this, you'll notice the speed difference immediately.

Step 2: Installing Tailwind CSS

This part trips a lot of people up because Tailwind changed how it integrates with Vite in version 4. If you've used Tailwind before through tailwind.config.js and PostCSS, this is different.

npm install tailwindcss @tailwindcss/vite

This installs Tailwind itself, along with a dedicated Vite plugin built specifically for Tailwind v4. This plugin handles the CSS processing directly inside Vite's build pipeline instead of going through a separate PostCSS configuration step like before.

Why does this matter? In older Tailwind setups, you needed a tailwind.config.js file, a postcss.config.js file, and content paths configured manually so Tailwind knew which files to scan for class names. With the Vite plugin approach in v4, a lot of that configuration overhead goes away. Vite and Tailwind talk to each other directly.

Step 3: Connecting Tailwind to Vite

Open vite.config.ts and add the Tailwind plugin alongside the React plugin.

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite"; // add this line

// https://vite.dev/config/
export default defineConfig({
  plugins: [
    tailwindcss(), // this too
    react()
  ], 
});

Why does the order or presence of these plugins matter? Vite plugins process your code in a pipeline. The Tailwind plugin needs to be registered so Vite knows to process Tailwind's CSS directives during build and development. Without this, Tailwind classes in your components simply won't generate any actual CSS - your className="text-lg" would just be a string with no styling behind it.

Step 4: Importing Tailwind in Your CSS

Open src/index.css, delete whatever default styles Vite generated, and replace it with just this one line:

@import "tailwindcss";

That's it. In older Tailwind versions you'd write three separate @tailwind directives for base, components, and utilities. Version 4 simplified this into a single import.

Why does this single line matter so much? This import is what actually pulls in Tailwind's entire utility class system into your project. Without it, none of your bg-white, dark:bg-gray-800, or any other Tailwind class will do anything - they'll just be unrecognized strings sitting in your JSX.

Run your dev server now to confirm everything is wired correctly:

npm run dev

If Tailwind classes are working in a quick test component, you're ready to move to the actual dark mode logic.

Step 5: Understanding How Dark Mode Actually Works in Tailwind

Before writing the toggle logic, you need to understand the mechanism Tailwind uses for dark mode. This is the part most tutorials skip past too quickly.

Tailwind's dark mode works through a special class prefix: dark:. When you write something like:

<div className="bg-white dark:bg-gray-800">

This tells Tailwind: "use bg-white normally, but if dark mode is active, use bg-gray-800 instead."

But here's the important part - how does Tailwind know if dark mode is active? By default, Tailwind checks if the <html> element has a class called dark on it. If that class exists, every dark: variant in your app activates. If it doesn't exist, your app shows the light mode styles.

So the entire dark mode system comes down to one simple question: is there a class called dark on the html tag or not?

That's the whole mechanism. Everything we build from here is just about adding and removing that one class, and remembering the user's choice.

Step 6: Building the Theme Context

This is the core logic of the whole tutorial. We need a way to:

1. Store the current theme (light or dark) somewhere accessible to the whole app

2. Provide a function to toggle between them

3. Apply the actual dark class to the html element when the theme changes

4. Remember the user's choice even after they close and reopen the browser

Why use Context API instead of just useState in the App component? If you only used useState in your top-level App component, you'd have to pass theme and toggleTheme down as props to every component that needs them. If your ToggleTheme button is three components deep, you'd be passing props through every layer in between just to reach it. This is called prop drilling, and it gets messy fast.

Context API solves this by letting any component in your app access the theme value directly, no matter how deeply nested it is, without passing props through every layer.

Create a file at src/context/ThemeContext.tsx:

import { createContext, useContext, useEffect, useState } from "react";

type Theme = "light" | "dark";

type ThemeContextType = {
  theme: Theme;
  toggleTheme: () => void;
};

const ThemeContext = createContext<ThemeContextType | null>(null);

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = useState<Theme>(() => {
    const storedTheme = localStorage.getItem("theme");

    return storedTheme === "dark" ? "dark" : "light";
  });

  useEffect(() => {
    const html = document.documentElement;

    if (theme === "dark") {
      html.classList.add("dark");
    } else {
      html.classList.remove("dark");
    }

    localStorage.setItem("theme", theme);
  }, [theme]);

  const toggleTheme = () => {
    setTheme((prev) => (prev === "dark" ? "light" : "dark"));
  };

  return (
    <ThemeContext.Provider
      value={{
        theme,
        toggleTheme,
      }}
    >
      {children}
    </ThemeContext.Provider>
  );
}

export function useTheme() {
  const context = useContext(ThemeContext);

  if (!context) {
    throw new Error("useTheme must be used inside ThemeProvider");
  }

  return context;
}

Let's go through this piece by piece because every part here is doing something specific.

The type definitions at the top:

type Theme = "light" | "dark";

This is a TypeScript union type. It says theme can only ever be exactly one of these two string values, nothing else. If you accidentally typed "Dark" with a capital D somewhere later in your code, TypeScript would catch that mistake immediately because it doesn't match either allowed value.

The initial state with a function:

const [theme, setTheme] = useState<Theme>(() => {
  const storedTheme = localStorage.getItem("theme");
  return storedTheme === "dark" ? "dark" : "light";
});

Notice that we're passing a function into useState, not a direct value. This matters. If we wrote useState(localStorage.getItem("theme")) directly, that localStorage.getItem call would run on every single re-render of this component, even though we only need it once when the component first mounts. By wrapping it in a function, React only runs this logic once, during the initial render. This is called lazy initial state, and it's a small but meaningful performance habit.

The logic itself checks if anything was previously saved in localStorage. If the user had picked dark mode before, that string "dark" is still sitting there from their last visit, and we restore it. If nothing is saved, we default to light mode.

The useEffect that does the actual work:

useEffect(() => {
  const html = document.documentElement;

  if (theme === "dark") {
    html.classList.add("dark");
  } else {
    html.classList.remove("dark");
  }

  localStorage.setItem("theme", theme);
}, [theme]);

This effect runs every time theme changes. Remember what we learned in step 5 - Tailwind's entire dark mode system depends on whether the html element has a class called dark. This is exactly what's happening here. document.documentElement refers to the actual <html> tag in your page. When theme becomes "dark", we add the dark class to it. When it becomes "light", we remove that class.

The moment that class gets added or removed, every single dark: variant across your entire app instantly responds, because Tailwind is constantly watching for that class to exist or not exist on the html tag.

The last line, localStorage.setItem("theme", theme), saves the current choice to the browser's local storage. This is what makes the theme persist - so if the user refreshes the page or comes back tomorrow, their preference is still there waiting to be read back in step one.

The toggle function:

const toggleTheme = () => {
  setTheme((prev) => (prev === "dark" ? "light" : "dark"));
};

This simply flips the current value. If it was dark, make it light. If it was light, make it dark. We're using the functional form of setTheme here (passing a function instead of a direct value) because it guarantees we're always working with the most current state value, rather than a potentially stale one from a previous render.

The custom hook at the bottom:

export function useTheme() {
  const context = useContext(ThemeContext);

  if (!context) {
    throw new Error("useTheme must be used inside ThemeProvider");
  }

  return context;
}

This wraps useContext in a custom hook. Why bother with this extra step instead of just calling useContext(ThemeContext) directly wherever needed? Two reasons. First, it's shorter to write useTheme() everywhere instead of repeating useContext(ThemeContext). Second, and more importantly, it adds a safety check. If somehow a component tries to use this hook outside of where ThemeProvider actually wraps the app, it throws a clear error immediately telling you exactly what went wrong, instead of silently failing or giving you a confusing undefined error somewhere else.

Step 7: Wrapping the App With the Provider

Context only works for components that are nested inside the Provider component. So we need to wrap our whole app with ThemeProvider. Open src/main.tsx and wrap your App component:

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App.tsx";
import { ThemeProvider } from "./context/ThemeContext.tsx";
import "./index.css";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <ThemeProvider>
      <App />
    </ThemeProvider>
  </StrictMode>,
);

Why wrap it here at the very top level? Because now every single component anywhere inside App - no matter how deeply nested - can call useTheme() and get access to the current theme and the toggle function. This is the entire point of using Context in the first place.

Step 8: Building the Toggle Button

Now we build the actual UI piece the user interacts with. Create src/components/ui/ToggleTheme.tsx:

import { Moon, SunDim } from "lucide-react";
import { useTheme } from "../../context/ThemeContext";
import { motion, AnimatePresence } from "framer-motion";

export default function ToggleTheme() {
  const { theme, toggleTheme } = useTheme();

  return (
    <button
      onClick={toggleTheme}
      className={`
        flex items-center gap-2 px-4 py-2 rounded-lg border cursor-pointer
        transition-colors duration-200
        ${
          theme === "dark"
            ? "bg-white text-black border-gray-200"
            : "bg-black/80 text-white border-black/90"
        }
      `}
    >
      <AnimatePresence mode="wait" initial={false}>
        <motion.div
          key={theme}
          className="flex items-center gap-2"
          initial={{ opacity: 0, scale: 0.9 }}
          animate={{ opacity: 1, scale: 1 }}
          exit={{ opacity: 0, scale: 0.9 }}
          transition={{ duration: 0.15 }}
        >
          {theme === "dark" ? (
            <SunDim className="w-4 h-4" />
          ) : (
            <Moon className="w-4 h-4" />
          )}
          <span className="text-sm font-medium">
            {theme === "dark" ? "Light Mode" : "Dark Mode"}
          </span>
        </motion.div>
      </AnimatePresence>
    </button>
  );
}

Why is this button's own background flipped opposite to the theme? Look closely - when theme === "dark", the button itself becomes white with black text. When the theme is light, the button becomes dark. This is an intentional design choice, not a bug. It makes the button stand out clearly against the page background in both modes, since the page itself goes dark when theme is dark, and the button does the opposite to maintain contrast.

Why use lucide-react for the icons? We're showing a sun icon when in dark mode (suggesting "click to switch to light") and a moon icon when in light mode (suggesting "click to switch to dark"). This is a common UX pattern - the icon represents what will happen when clicked, not the current state.

What is the AnimatePresence and motion.div doing here? This comes from Framer Motion, an animation library. Without it, the icon and text would just instantly swap when you click, which feels abrupt. With AnimatePresence, when the theme value changes, the key={theme} on the motion div changes too, which tells Framer Motion "this is a different element now, animate the transition." The old icon and text fade and shrink out, the new ones fade and grow in. The mode="wait" ensures the exit animation finishes before the next one starts, so they don't overlap awkwardly.

This isn't required for dark mode to function - it's a polish detail. If you want to skip Framer Motion entirely, you can remove AnimatePresence and motion.div and just keep the plain conditional icon and text. The toggle will still work exactly the same, just without the smooth transition.

Step 9: Building a Component That Actually Uses the Theme

A toggle button is pointless without something on the page that visibly changes. Create src/components/card/Card.tsx:

export default function Card() {
  return (
    <>
      <div className="max-w-md p-4 bg-white dark:bg-gray-800 shadow-md rounded-lg">
        <figure className="max-w-sm">
          <img
            src="https://www.apple.com/assets-www/en_IN/watch/product_tile/large/u3_6b7e98fe2_2x.png"
            alt="Apple Watch Ultra 3"
            className="w-full h-auto object-cover rounded-lg"
          />
        </figure>
        <div className="mt-4">
          <h2 className="text-lg font-bold text-gray-800 dark:text-white">
            Apple watch ultra 3
          </h2>
          <p className="text-sm text-gray-600 dark:text-gray-300">
            Black strap, medium
          </p>

          <div className="mt-4 flex items-center space-x-4">
            <p className="text-base font-semibold text-gray-800 dark:text-white">
              ₹ 85,999
            </p>
            <p className="text-sm font-semibold text-gray-800 dark:text-white line-through">
              ₹ 89,999
            </p>
            <p className="text-xs font-semibold text-green-500">4% off</p>
          </div>
        </div>
      </div>
    </>
  );
}

Notice something important here. This component does not import useTheme at all. It doesn't know or care whether the theme is light or dark. It just has Tailwind classes like bg-white dark:bg-gray-800 written directly in the JSX.

This is the actual payoff of everything we set up earlier. Because the dark mode mechanism works purely through the dark class on the html tag, any component anywhere in your app can simply write dark: variants in its className and it will automatically respond to theme changes - without ever needing to know about Context, state, or any toggle logic at all. The component just declares "here's what I look like in light mode, here's what I look like in dark mode," and the rest is handled globally.

This is a powerful separation. Your UI components stay simple and focused only on appearance. The theme logic lives in one place - the Context - and everything else just reacts to it through CSS classes.

Step 10: Putting It All Together

Now bring everything into App.tsx:

import "./App.css";
import Card from "./components/card/Card";
import ToggleTheme from "./components/ui/ToggleTheme";

function App() {
  return (
    <main className="flex flex-col items-center justify-center min-h-screen gap-4">
      <Card />
      <ToggleTheme />
    </main>
  );
}

export default App;

At this point, run your dev server and test it:

npm run dev

Click the toggle button. You should see the card background switch between white and dark gray, the text colors invert, and the button itself swap appearance with a smooth animation. Refresh the page after toggling - the theme you picked should still be there. That's the localStorage persistence working correctly.

What's Actually Happening When You Click the Button

Let's trace through the entire flow one more time, now that every piece is built, so the full picture is clear.

You click the button. This calls toggleTheme(), which flips the theme state from "light" to "dark" (or vice versa) inside ThemeContext. Because state changed, React re-renders any component using useTheme().

At the same time, the useEffect inside ThemeProvider detects that theme changed, and runs its logic - it either adds or removes the dark class on document.documentElement, and saves the new theme value into localStorage.

The moment that dark class appears or disappears on the html tag, every dark: prefixed Tailwind class across your entire app responds instantly, because that's literally how Tailwind's dark mode variant works under the hood. No component needs to manually re-check anything - it's pure CSS responding to a class change.

Next time the page loads, the useState initializer reads back whatever was saved in localStorage, and the correct theme is restored before the user even sees anything.

That's the complete system. Five moving parts, all of them simple on their own, working together.

Why This Approach and Not Just CSS Media Queries

You might be wondering - CSS already has a prefers-color-scheme media query that detects if the user's operating system is set to dark mode. Why not just use that instead of building all this?

The honest answer is that media queries only detect the system preference - they don't let the user manually override it inside your app. If someone's OS is set to dark mode but they want your specific website in light mode, a pure CSS media query approach can't give them that choice. The Context and class-based approach we built here gives the user full control, independent of their system settings, and remembers their specific choice for your site.

If you wanted to be extra thorough, you could combine both - default to the system preference on first visit using the media query, then let the user override it with the toggle, which is exactly what localStorage allows for after that first choice is made.

A Quick Note on Folder Structure

Notice how the project separates concerns into folders - context for state logic, components/ui for reusable interface pieces like buttons, and components/card for feature-specific pieces. This isn't required for a small project like this one to work, but it's a habit worth building early. As your app grows, having theme logic, UI primitives, and feature components clearly separated makes it much easier to find things and avoid one giant messy file holding everything.

The Bottom Line

Dark mode isn't complicated once you see what's actually happening underneath. It's one class on the html tag, a place to store and read that choice, and Tailwind's dark: variants reacting to whether that class exists. Everything else - Context API, the toggle button, the animation - is just making that one simple mechanism convenient and pleasant to use.

If you understood every step here, you didn't just copy a dark mode toggle. You understand exactly how to build theme switching into any future project, with or without Tailwind, because you know the actual mechanism instead of just the code that happened to work.

Read full article on CodeKK