DEV Community: Munna Thakur

🧠 How to Think Like a Problem Solver: Choosing the Right Data Structure

Munna Thakur — Wed, 01 Apr 2026 06:59:30 +0000

"Good programmers don't memorize solutions — they recognize patterns."

The Real Skill Nobody Teaches You

Most beginners learn data structures and algorithms in isolation. They memorize syntax, copy solutions, and wonder why interviews still feel hard.

The missing skill is pattern recognition — the ability to look at a new problem and say:
"I've seen this shape before. I know what to reach for."

This article gives you a mental framework to develop exactly that skill — and shows you how it applies to real life, not just LeetCode.

Step 1: Stop Asking "Which DS?" — Start Asking "What Kind of Problem?"

When you read a problem, your first question should never be:

❌ "Which data structure should I use?"

Instead, ask:

✅ "What is this problem actually trying to do?"

Here's a simple decision map:

What the Problem Wants	Likely Approach
Count the number of ways	Dynamic Programming
Find the shortest/fastest path	BFS / Dijkstra
Search through sorted data	Binary Search
Check if something was seen before	HashMap / HashSet
Process relationships between things	Graph / Tree
Avoid recomputing the same thing	DP / Memoization

Step 2: Learn to Read Keyword Clues

Problems speak to you if you know how to listen. Certain keywords are strong signals.

🔑 High-Signal Keywords

Keyword	What It Hints
"How many ways"	Dynamic Programming
"Shortest path"	BFS or Dijkstra
"Top K" / "Largest K"	Heap / Priority Queue
"Longest subarray"	Sliding Window
"Duplicate" / "Seen before"	HashMap or HashSet
"Sum between L and R"	Prefix Sum
"All combinations"	Backtracking
"Connected" / "Grouped"	Union-Find or Graph
"Starts with" / "Prefix"	Trie
"Next greater element"	Monotonic Stack

Real Example: Climbing Stairs (LeetCode #70)

"You can climb 1 or 2 steps. How many distinct ways to reach the top?"

Keywords spotted:

"How many ways" → think DP
"choices at each step" → overlapping subproblems
"depends on previous" → build from smaller results

This is Dynamic Programming — a Fibonacci-style pattern.

Step 3: The 25 Core DSA Patterns

Think of this as your mental toolbox. When you encounter a problem, you're matching it to one of these shapes.

🔢 Foundation Patterns

1. Array / Basic Traversal

Use when: sequential data, index access, find max/min/sum
Real life: processing a list of transactions, finding the highest sale

2. Two Pointers

Use when: sorted array, pair-finding, working from both ends
Real life: matching buyers and sellers in a marketplace by budget

3. Sliding Window

Use when: continuous subarray/substring, "longest" or "smallest" range
Real life: finding the best 7-day average temperature in weather data

4. Binary Search

Use when: sorted data, monotonic answer space
Real life: finding a word in a dictionary, finding the minimum viable price

5. HashMap / HashSet

Use when: fast lookup, frequency count, duplicate detection
Real life: tracking which users have visited a page, finding anagrams

6. Prefix Sum

Use when: range sum queries
Real life: calculating sales between two dates from a running total

🔁 Recursion-Based Patterns

7. Recursion

Use when: try all possibilities, divide into subproblems
Real life: exploring all routes on a map

8. Backtracking

Use when: constraint-based generation, exhaustive valid combos
Real life: scheduling meetings with constraints, solving a Sudoku

9. Dynamic Programming (DP)

Use when: overlapping subproblems, optimize over choices
Real life: finding the cheapest flight with layovers, inventory stocking decisions

10. Greedy

Use when: local best leads to global best
Real life: choosing the earliest finishing meeting to fit the most into a day

🧱 Linear Structure Patterns

11. Stack (LIFO)

Use when: undo operations, nested structure checking
Real life: browser back button, undo history in a text editor

12. Queue (FIFO)

Use when: level-by-level processing, task scheduling
Real life: customer support ticket queue, printer job queue

13. Deque (Double-ended)

Use when: insert/remove from both ends
Real life: task scheduling with priority at both ends

14. Linked List

Use when: frequent insertions/deletions, no random access needed
Real life: music playlist (easy to insert/delete songs)

🌳 Tree-Based Patterns

15. Binary Tree / BST

Use when: hierarchical data, fast search/insert
Real life: file system (folders inside folders), org chart

16. Tree DFS/BFS Traversal

Use when: explore all nodes, find depth/path
Real life: crawling a website starting from the homepage

17. Heap / Priority Queue

Use when: repeatedly need min or max
Real life: hospital triage (most urgent patient first), top trending posts

18. Trie

Use when: prefix-based search, autocomplete
Real life: search box suggestions, phone contact search

🌐 Graph-Based Patterns

19. Graph DFS / BFS

Use when: connected nodes, path finding, island counting
Real life: social network (friends-of-friends), city road connectivity

20. Shortest Path (Dijkstra / BFS)

Use when: minimum cost/distance path
Real life: Google Maps routing, network packet routing

21. Union-Find (Disjoint Set)

Use when: grouping, merging connected components
Real life: detecting if two people are in the same social circle

22. Topological Sort

Use when: dependency ordering
Real life: build systems (compile A before B), course prerequisites

🔧 Specialized Patterns

23. Monotonic Stack / Queue

Use when: next greater/smaller element, range queries
Real life: stock price span problem, nearest taller building

24. Bit Manipulation

Use when: binary operations, single unique number
Real life: permission flags (read/write/execute), XOR encryption

25. Matrix / Grid Traversal

Use when: 2D grid, region finding, shortest path in a grid
Real life: game board pathfinding, image flood fill, GPS grid maps

Step 4: How This Maps to Real Life

Data structures aren't just for interviews. They're how every application around you works.

Real-World Scenario	Pattern Used
Google Maps finds your fastest route	Dijkstra (Shortest Path)
Instagram shows you trending posts	Heap / Priority Queue
Ctrl+Z undoes your last action	Stack
Google autocompletes your search	Trie
Amazon recommends "people also bought"	Graph (collaborative filtering)
Git tracks your code history	Linked List + Tree
WhatsApp delivers messages in order	Queue
Spotify builds your Discover Weekly	Graph + DP
URL shortener (bit.ly) stores links	HashMap
File system on your computer	Tree (directory structure)

💡 Every app you use daily is built on these same 25 patterns.

Step 5: Your 3-Question Framework

When you see any problem, ask these three questions in order:

Question 1: What is the structure of the data?

Is it a list? → Array / Linked List
Is it key-value pairs? → HashMap
Is it hierarchical? → Tree
Is it a network of connections? → Graph

Question 2: What operation is repeated or expensive?

Searching → Binary Search or HashMap
Min/Max → Heap
Prefix calculation → Prefix Sum
Same subproblem again and again → DP / Memoization

Question 3: What does the output look like?

One number (count/cost/max) → DP or Greedy
A specific path or sequence → BFS/DFS
All valid combinations → Backtracking
Sorted or ranked output → Heap

The 8 Patterns to Master First

You don't need to master all 25 at once. Focus on these 8 high-frequency patterns first:

Array — the foundation of everything
HashMap / HashSet — used in 60%+ of problems
Two Pointers — elegant O(n) solutions
Sliding Window — subarray mastery
Binary Search — logarithmic efficiency
Recursion — the base of all tree/graph thinking
Dynamic Programming — optimization powerhouse
BFS / DFS — traversal of almost any structure

Master these 8 → you can solve 70% of interview problems.

How to Build This Intuition (The Right Practice Method)

Don't just solve problems. Analyze them.

After every problem you solve, ask:

What pattern was this?
Why did this approach work?
What keyword gave it away?
Where else could I use this exact pattern?

After 30–50 problems with this reflection habit, pattern recognition becomes automatic.

Suggested Practice Progression

Week 1–2: Array, HashMap, Two Pointers

Week 3–4: Sliding Window, Binary Search, Stack/Queue

Week 5–6: Recursion, Tree DFS/BFS

Week 7–8: Graph, DP basics

Week 9–10: Heap, Backtracking, advanced DP

Summary: The Mental Model

See a problem
     ↓
What type of problem is it?
     ↓
Spot the keywords → Match the pattern
     ↓
Choose the right data structure
     ↓
Write clean, confident code

The goal is not to memorize 1000 solutions.

The goal is to recognize 25 patterns so deeply that any new problem feels familiar.

Start with one pattern. Solve 3–5 problems. Then move to the next. Consistency beats intensity — every time.

SOLID Principles in React: The Complete Guide Nobody Told You About

Munna Thakur — Sun, 29 Mar 2026 10:31:43 +0000

You've heard "write clean code." You've heard "follow best practices." But nobody sat down and told you — concretely — what that actually means when you're staring at a 400-line React component at 11pm. This article is that conversation.

What is SOLID and Why Should You Care?
S — Single Responsibility Principle
O — Open/Closed Principle
L — Liskov Substitution Principle
I — Interface Segregation Principle
D — Dependency Inversion Principle
SOLID vs MVC vs Feature-Based Architecture
Advantages and Drawbacks
When to Use — When to Skip
Key Takeaways

What is SOLID and Why Should You Care?

SOLID is a set of 5 design principles that make your code easier to maintain, test, extend, and understand.

Letter	Principle	One Line
S	Single Responsibility	One class, one job
O	Open/Closed	Extend without modifying
L	Liskov Substitution	Replace without breaking
I	Interface Segregation	Give only what's needed
D	Dependency Inversion	Depend on abstractions

These aren't React-specific rules. They're universal software design principles — but they apply beautifully to React's component and hook model.

SOLID is NOT a replacement for MVC or Feature-Based Architecture

Think of it like three layers:

Feature-Based Architecture  →  How you organize folders
MVC / MVVM Pattern          →  How you split code inside each feature
SOLID Principles            →  How you write code inside each file

They work together. SOLID is the innermost layer — the rules that govern the quality of your code at the line-by-line level.

S — Single Responsibility Principle

The Rule

A class, component, or function should have only one reason to change.

The Restaurant Analogy

In a good restaurant, the chef cooks. The waiter serves. The billing desk handles payments. Nobody does anyone else's job.

Now imagine a chef who also takes orders, handles billing, cleans tables, and manages suppliers. He's overwhelmed, makes mistakes, and when the billing system changes — the chef has to stop cooking to deal with it.

That chef is your Fat Component.

The Problem: What a Fat Component Looks Like

// ❌ UserProfile.jsx — the "monster" file
function UserProfile({ userId }) {

  // 1. Fetching data — not this component's job
  const [user, setUser] = useState(null);
  useEffect(() => {
    fetch(`/api/users/${userId}`)
      .then(r => r.json())
      .then(setUser);
  }, [userId]);

  // 2. Validation logic — not this component's job
  const isValidEmail = (email) => email.includes('@') && email.includes('.');

  // 3. Date formatting — not this component's job
  const formatDate = (date) => new Date(date).toLocaleDateString('en-IN');

  // 4. Business rule — not this component's job
  const isPremium = user?.plan === 'premium';

  // 5. Analytics — definitely not this component's job
  useEffect(() => {
    analytics.track('profile_viewed', { userId });
  }, [userId]);

  // 6. Finally, the actual rendering
  return (
    <div>
      <h2>{user?.name}</h2>
      <p>{formatDate(user?.createdAt)}</p>
      {isPremium && <span>Premium Member</span>}
    </div>
  );
}

This component does six things. Changing the API URL, the date format, the analytics SDK, or the UI — all require opening the same file. One change can break five unrelated things.

The Fix: One File, One Job

Split it across four focused files:

userApi.js — only HTTP calls

export const userApi = {
  getById: (id) =>
    fetch(`/api/users/${id}`).then(res => {
      if (!res.ok) throw new Error('User not found');
      return res.json();
    }),
};

formatters.js — only formatting

export const formatDate = (dateStr) =>
  new Date(dateStr).toLocaleDateString('en-IN');

export const isValidEmail = (email) =>
  email.includes('@') && email.includes('.');

useUser.js — only state and side effects

import { userApi } from '../api/userApi';
import { formatDate } from '../utils/formatters';

export function useUser(userId) {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    userApi.getById(userId)
      .then(setUser)
      .catch(e => setError(e.message))
      .finally(() => setLoading(false));

    analytics.track('profile_viewed', { userId });
  }, [userId]);

  return { user, loading, error };
}

UserProfile.jsx — only rendering

import { useUser } from '../hooks/useUser';
import { formatDate } from '../utils/formatters';

function UserProfile({ userId }) {
  const { user, loading, error } = useUser(userId);

  if (loading) return <Spinner />;
  if (error) return <ErrorMessage message={error} />;

  return (
    <div>
      <h2>{user.name}</h2>
      <p>{formatDate(user.createdAt)}</p>
      {user.plan === 'premium' && <span>Premium Member</span>}
    </div>
  );
}

Now if the API changes — only userApi.js. Date format changes — only formatters.js. UI redesign — only UserProfile.jsx. Nothing else is touched.

The "AND" Test

If you need the word "AND" to describe what a file does — SRP is broken.

"This file fetches data AND validates it AND formats it AND renders it"

Every "AND" is a signal to split.

Testing Becomes Trivial

// Test formatters in isolation — no component, no API, no mocks
import { isValidEmail, formatDate } from './formatters';

test('validates email correctly', () => {
  expect(isValidEmail('test@gmail.com')).toBe(true);
  expect(isValidEmail('notanemail')).toBe(false);
});

Three lines. No setup. No mocking. No React rendering. That's the power of SRP.

O — Open/Closed Principle

The Rule

Software should be open for extension, but closed for modification.

Add new features without changing existing, working code.

The Smartphone Analogy

You can install new apps on your phone without modifying the OS. The OS is closed for modification (you can't change the core), but open for extension (you can add apps).

The Problem: The Never-Ending if-else

// ❌ Every new button type means opening this file and editing it
function Button({ type, label }) {
  if (type === 'primary') {
    return <button style={{ background: 'blue' }}>{label}</button>;
  }
  if (type === 'danger') {
    return <button style={{ background: 'red' }}>{label}</button>;
  }
  if (type === 'success') {
    return <button style={{ background: 'green' }}>{label}</button>;
  }
  // Adding "warning"? Open this file again. Risk breaking primary/danger/success.
}

Every new type means touching tested, working code. One typo breaks everything.

The Fix: Configuration Over Conditions

// ✅ New type = add one line to the config object. Component never changes.
const buttonStyles = {
  primary: { background: '#185FA5', color: '#fff' },
  danger:  { background: '#A32D2D', color: '#fff' },
  success: { background: '#3B6D11', color: '#fff' },
  warning: { background: '#854F0B', color: '#fff' },
  // Add "ghost" tomorrow? Just add it here. Button component stays closed.
};

function Button({ type = 'primary', label, onClick }) {
  return (
    <button style={buttonStyles[type]} onClick={onClick}>
      {label}
    </button>
  );
}

Real Production Example: Payment System

// ❌ OCP violation — every new payment method opens this function
function processPayment(type, data) {
  if (type === 'card') { return handleCard(data); }
  if (type === 'upi') { return handleUpi(data); }
  if (type === 'paypal') { return handlePaypal(data); }
  // Adding crypto? Open this file. Risk breaking card/UPI/PayPal.
}

// ✅ OCP followed — new payment method = new entry in the map
const paymentHandlers = {
  card:   handleCard,
  upi:    handleUpi,
  paypal: handlePaypal,
};

function processPayment(type, data) {
  const handler = paymentHandlers[type];
  if (!handler) throw new Error(`Unknown payment type: ${type}`);
  return handler(data);
}

// Adding crypto tomorrow:
paymentHandlers.crypto = handleCrypto;
// processPayment() function never touched. ✅

The Golden Rule for OCP

"If you find yourself opening the same file again and again to add new features — you are violating OCP."

L — Liskov Substitution Principle

The Rule

If S is a subtype of T, objects of type T may be replaced with objects of type S without breaking the program.

In plain language: replace a parent with its child — nothing should break.

The Vehicle Analogy

A car has start() and stop(). A taxi is a car — it also has start() and stop() with the same behavior. You can swap a car for a taxi in any system that expects a car.

But a bicycle doesn't have an engine. If you try to call start() on a bicycle where a car is expected — it breaks. That's an LSP violation.

The Problem: Broken Contract

// ❌ LSP violation — GraphQL service changes the method signature
class RestUserService {
  getUser(id) {
    return fetch(`/api/users/${id}`).then(r => r.json());
  }
}

class GraphQLUserService {
  getUser(id, authToken) { // ← Extra parameter! Contract is broken.
    return graphqlClient.query(USER_QUERY, { id, authToken });
  }
}

// Now the component must know WHICH service it's using:
service.getUser(id);          // Works for REST
service.getUser(id, token);   // Needed for GraphQL
// You can't swap them — LSP is violated.

The Fix: Same Contract, Different Implementation

// ✅ Both services honor the same interface
class RestUserService {
  getUser(id) {
    return fetch(`/api/users/${id}`).then(r => r.json());
  }
}

class GraphQLUserService {
  getUser(id) {
    // Auth is handled internally — not leaked to the caller
    return graphqlClient.query(USER_QUERY, { id });
  }
}

// The hook doesn't care which service it gets — both are interchangeable
function useUser(id, service) {
  const [user, setUser] = useState(null);

  useEffect(() => {
    service.getUser(id).then(setUser);
  }, [id]);

  return user;
}

// Both work without changing a single line in the hook or component:
const user1 = useUser(1, new RestUserService());
const user2 = useUser(1, new GraphQLUserService());

Real Use Case: Environment-Based Switching

// Development uses mock data. Production uses real API.
// The component never knows the difference.

const userService =
  process.env.NODE_ENV === 'development'
    ? new MockUserService()   // returns fake data instantly
    : new ApiUserService();   // real network calls

// Inject it — the component doesn't care which one it gets
function App() {
  return <UserList service={userService} />;
}

LSP Violation Checklist

Your code violates LSP if a child/subtype:

Requires extra parameters the parent didn't
Returns a different shape of data
Throws errors the parent never threw
Ignores props/methods the parent relied on

I — Interface Segregation Principle

The Rule

Clients should not be forced to depend on interfaces they do not use.

In React: don't give a component more than it needs.

The Waiter Analogy

A waiter needs to know the menu and how to take orders. They do NOT need to know the kitchen's inventory, the supplier's delivery schedule, or the owner's bank account.

Give people exactly what they need. Nothing more.

The Problem: The "Full Object" Trap

// ❌ UserCard receives the entire user object
function UserCard({ user }) {
  // Only uses name and email
  return <div>{user.name} — {user.email}</div>;
}

// The full user object that gets passed:
// {
//   id, name, email, password, billingInfo,
//   adminNotes, tokens, createdAt, updatedAt,
//   preferences, internalScore, ...
// }

<UserCard user={entireUserObject} /> // ❌

Three real problems this causes:

1. Unnecessary re-renders

React re-renders UserCard whenever user changes. If user.password or user.billingInfo changes — the card re-renders even though it doesn't use those fields.

2. Security risk

password and tokens are now in the component's props. Any logging, debugging, or prop-spreading could expose them.

3. Tight coupling

If the user object structure changes — even fields UserCard doesn't use — you might break the component.

The Fix: Pass Only What's Needed

// ✅ UserCard receives only what it actually uses
function UserCard({ name, email }) {
  return <div>{name} — {email}</div>;
}

// Clear, safe, minimal
<UserCard name={user.name} email={user.email} /> // ✅

Now UserCard only re-renders when name or email change. It never sees password. If the user object grows 50 more fields — this component is completely unaffected.

ISP with Hooks: Return Only What's Needed

// ❌ Bad hook — returns everything
function useUser() {
  return {
    name: 'Munna',
    email: 'munna@example.com',
    posts: [],           // ← ProfilePage needs this
    followers: [],       // ← FollowersPage needs this
    billingInfo: {},     // ← BillingPage needs this
    settings: {},        // ← SettingsPage needs this
  };
}

// UserCard only needs name — but gets everything
const user = useUser();
return <p>{user.name}</p>;

// ✅ Better — targeted hooks
function useUserBasic() {
  return { name: 'Munna', email: 'munna@example.com' };
}

function useUserPosts(userId) {
  // fetches only posts
}

function useUserFollowers(userId) {
  // fetches only followers
}

The Selector Pattern (Production Level)

When using Zustand or Redux, selectors are ISP in action:

// ❌ Component gets the entire store slice
const { name, email, posts, followers, billing } = useUserStore();

// ✅ Component gets exactly what it needs
const name = useUserStore(state => state.name);

D — Dependency Inversion Principle

The Rule

High-level modules should not depend on low-level modules. Both should depend on abstractions.

The Phone Charger Analogy

Your phone doesn't connect directly to the power plant. There's a charger, a cable, and a socket — all abstractions between them.

You can change the charger (USB-C to MagSafe). You can travel to a different country (different socket). Your phone works every time because it depends on the abstraction (power delivery), not the implementation (specific power plant).

The Problem: Direct Dependency

// ❌ Component directly depends on fetch
function UserList() {
  const [users, setUsers] = useState([]);

  useEffect(() => {
    fetch('/api/users')  // ← direct dependency on the network layer
      .then(r => r.json())
      .then(setUsers);
  }, []);

  return users.map(u => <p key={u.id}>{u.name}</p>);
}

Problems:

To test this, you must mock fetch globally — a messy, fragile approach
Want to switch from REST to GraphQL? Modify this component
Want to add caching? Modify this component
Want to use mock data in dev? Modify this component

Every external change forces a component change.

The Fix: Depend on an Abstraction (Hook)

// Step 1: Abstraction — the hook
function useUsers() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetch('/api/users')
      .then(r => r.json())
      .then(setUsers)
      .finally(() => setLoading(false));
  }, []);

  return { users, loading };
}

// Step 2: Component depends on the hook (abstraction), not fetch (implementation)
function UserList() {
  const { users, loading } = useUsers(); // ← depends on abstraction ✅

  if (loading) return <p>Loading...</p>;
  return users.map(u => <p key={u.id}>{u.name}</p>);
}

Making It Testable with Injection

// The hook is injected as a prop with a default value
function UserList({ useUsersHook = useUsers }) {
  const { users, loading } = useUsersHook();

  if (loading) return <p>Loading...</p>;
  return users.map(u => <p key={u.id}>{u.name}</p>);
}

// In production — uses real hook automatically
<UserList />

// In tests — inject mock, no network calls
<UserList useUsersHook={() => ({ users: [{ id: 1, name: 'Munna' }], loading: false })} />

Full Service Layer (Advanced DIP)

For larger projects, add a service layer between the hook and the API:

// Low-level: API layer (implementation detail)
class ApiUserService {
  getUsers() {
    return fetch('/api/users').then(r => r.json());
  }
}

class GraphQLUserService {
  getUsers() {
    return graphqlClient.query(USERS_QUERY);
  }
}

class MockUserService {
  getUsers() {
    return Promise.resolve([{ id: 1, name: 'Test User' }]);
  }
}

// Mid-level: Hook depends on service (abstraction)
function useUsers(service) {
  const [users, setUsers] = useState([]);

  useEffect(() => {
    service.getUsers().then(setUsers);
  }, []);

  return users;
}

// High-level: Component depends on hook (abstraction)
function UserList() {
  const service = new ApiUserService(); // swap this without touching UserList
  const users = useUsers(service);

  return users.map(u => <p key={u.id}>{u.name}</p>);
}

Switch from REST to GraphQL? Change one line — new ApiUserService() → new GraphQLUserService(). UserList never knows.

SOLID vs MVC vs Feature-Based Architecture

These three are often confused. They're not competing — they operate at different levels:

┌─────────────────────────────────────────────────────────┐
│  Feature-Based Architecture                              │
│  (How folders are organized)                             │
│  /features/auth, /features/todos, /shared               │
│                                                          │
│  ┌───────────────────────────────────────────────────┐   │
│  │  MVC / MVVM Pattern                               │   │
│  │  (How code is split inside each feature)          │   │
│  │  API → Service → Hook → Component                 │   │
│  │                                                   │   │
│  │  ┌─────────────────────────────────────────────┐  │   │
│  │  │  SOLID Principles                           │  │   │
│  │  │  (How code is written inside each file)     │  │   │
│  │  │  SRP, OCP, LSP, ISP, DIP                   │  │   │
│  │  └─────────────────────────────────────────────┘  │   │
│  └───────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

	What it answers
Feature-Based	Where do files live?
MVC/MVVM	How is logic split within a feature?
SOLID	How is each individual file written?

You don't choose between them. You use all three together.

Advantages and Drawbacks

Advantages

1. Testability
Each unit has a single, clear job. Testing is isolated, fast, and doesn't require complex setup.

2. Maintainability
Bug in email validation? Look in formatters.js. Bug in data fetching? Look in the API layer. The blast radius of any problem is contained.

3. Reusability
A formatDate function written with SRP can be used in 20 components. An ApiUserService written with DIP can be swapped for a mock in tests.

4. Scalability
Add new features (OCP), swap implementations (LSP), inject dependencies (DIP) — without touching working code.

5. Team-friendliness
New developer joins? File names tell them exactly where everything lives. No archaeology required.

Drawbacks (Being Honest)

1. More files
A component that was one file becomes five. For small projects, this feels like overkill.

2. Navigation overhead
"Where is that function?" now requires jumping between files instead of scrolling.

3. Learning curve
Teams new to these principles need time to understand the patterns before they can move fast.

4. Risk of over-engineering
Applied too early or too aggressively, SOLID creates complexity without benefit. A todo app doesn't need a UserServiceFactory.

5. Boilerplate
Service classes, interfaces, injection patterns — they add lines before they save lines.

When to Use — When to Skip

Use SOLID when:

Your team has 2+ developers
The project will last more than 3 months
Multiple features share the same logic
Testing is a priority
The codebase is already starting to feel painful to change

Skip SOLID (for now) when:

You're building a quick MVP or prototype
You're working solo on a 2-3 page app
The deadline is tomorrow
The feature is genuinely one-off with no reuse
The team isn't familiar with the patterns yet — introduce one principle at a time

The Rule of Three

A good practical rule: the first time you write something, just write it. The second time you write something similar, note it. The third time, refactor to a shared abstraction.

Don't apply SOLID to code you've written once. Apply it when pain becomes real.

Key Takeaways

S — Single Responsibility: One file, one job. If you need "AND" to describe it — split it.

O — Open/Closed: Use configuration maps instead of growing if-else chains. Adding features shouldn't mean editing working code.

L — Liskov Substitution: Keep the same contract across implementations. If you can swap REST for GraphQL without changing the component — you're doing it right.

I — Interface Segregation: Pass only what's needed. More props doesn't mean more flexibility — it means more coupling and more re-renders.

D — Dependency Inversion: Components should depend on hooks. Hooks should depend on services. Services should depend on the API layer. Never jump levels.

One Paragraph to Remember

MVC tells you to split code into layers. Feature-Based Architecture tells you to organize those layers by feature. SOLID tells you how to write the code inside each layer so it's clean, testable, and changeable. They're not alternatives — they're nested levels of the same discipline. Master all three, and the 600-line "Monster" component becomes a memory.

What's Next?

If this article helped, the logical next read is:

BFF (Backend For Frontend) — how to stop the frontend from making 5 API calls where 1 would do
React Testing Library + SOLID — how clean architecture makes testing feel effortless
Zustand + DIP — how modern state management is just Dependency Inversion with a nicer API

Found this useful? Drop a comment with which principle clicked for you — or which one you're still confused about. I read every one.

Tags: #react #javascript #webdev #cleancode #architecture #solid #frontend #beginners #programming #softwaredevelopment

MVC in React: Why We Use It, Why It Breaks, and What Production Apps Do Instead

Munna Thakur — Sat, 28 Mar 2026 08:26:48 +0000

You start a React project. Everything goes into one component. Three months later, nobody wants to touch that file — not even you. This article is about how that happens, why MVC was supposed to fix it, why it still breaks, and what actually works in production.

Why Do We Even Need Architecture?
What is MVC?
MVC in React (With Real Code)
The Fat MVC Problem
How Fat MVC Happens (Step by Step)
MVC vs MVVM vs Flux (Redux)
Feature-Based Architecture: The Production Solution
Full Production Example (Todo App)
Common Mistakes to Avoid
Which Architecture Should You Choose?
Key Takeaways

Why Do We Even Need Architecture?

Let's start with a story.

You're building a Todo app. Day 1, you write this:

function App() {
  const [todos, setTodos] = useState([]);

  useEffect(() => {
    fetch('/api/todos').then(r => r.json()).then(setTodos);
  }, []);

  const deleteTodo = (id) => {
    fetch(`/api/todos/${id}`, { method: 'DELETE' });
    setTodos(todos.filter(t => t.id !== id));
  };

  return (
    <div>
      {todos.map(todo => (
        <div key={todo.id}>
          {todo.title}
          <button onClick={() => deleteTodo(todo.id)}>Delete</button>
        </div>
      ))}
    </div>
  );
}

This works. It's clean. You're happy.

Day 30: You add filtering, sorting, auth, pagination, error handling, loading states, form validation...

That same file is now 400 lines long. A new developer joins the team. They open the file and immediately close it.

This is why architecture matters. Not for day 1. For day 30, day 100, and when you're a team of 10.

What is MVC?

MVC stands for Model + View + Controller.

It's a way to split your code into three clear responsibilities so no single piece does too much.

The Restaurant Analogy 🍽️

Imagine a restaurant:

MVC Part	Restaurant	Responsibility
Model	Kitchen	Stores data, handles business logic
View	Waiter	Shows things to the user
Controller	Manager	Coordinates between kitchen and waiter

The flow:

Customer (User)
    ↓
Waiter shows menu (View)
    ↓
Customer places order (User Action)
    ↓
Manager takes order (Controller)
    ↓
Manager tells kitchen what to cook (Model)
    ↓
Food comes back to customer through waiter (View updates)

Nobody in a restaurant expects the waiter to cook. Nobody expects the chef to serve food. Separation of responsibility.

The Core Idea

User does something
      ↓
View captures it
      ↓
Controller decides what to do
      ↓
Model updates the data
      ↓
View re-renders with new data

MVC in React (With Real Code)

React is not an MVC framework. It's a view library. But you can structure your code in MVC style.

Here's how each part maps:

MVC	React Equivalent
Model	API calls, State (Redux/Context), backend data
View	Components (JSX)
Controller	Custom Hooks, Event Handlers

Example: A Clean Todo App in MVC Style

Model — the data layer

// services/todoService.js
export const fetchTodos = async () => {
  const res = await fetch('/api/todos');
  return res.json();
};

export const deleteTodoById = async (id) => {
  await fetch(`/api/todos/${id}`, { method: 'DELETE' });
};

This file only knows about data. It has no idea what the UI looks like.

Controller — the logic layer

// hooks/useTodoController.js
import { useState, useEffect } from 'react';
import { fetchTodos, deleteTodoById } from '../services/todoService';

export const useTodoController = () => {
  const [todos, setTodos] = useState([]);

  useEffect(() => {
    fetchTodos().then(setTodos);
  }, []);

  const deleteTodo = async (id) => {
    await deleteTodoById(id);
    setTodos(prev => prev.filter(t => t.id !== id));
  };

  return { todos, deleteTodo };
};

This hook handles logic and coordination. It doesn't care about what the button looks like.

View — the UI layer

// components/TodoList.jsx
const TodoList = ({ todos, onDelete }) => {
  return (
    <ul>
      {todos.map(todo => (
        <li key={todo.id}>
          {todo.title}
          <button onClick={() => onDelete(todo.id)}>Delete</button>
        </li>
      ))}
    </ul>
  );
};

This component only renders. No API calls. No business logic. Just display.

Putting it together

// pages/TodoPage.jsx
import { useTodoController } from '../hooks/useTodoController';
import TodoList from '../components/TodoList';

const TodoPage = () => {
  const { todos, deleteTodo } = useTodoController();
  return <TodoList todos={todos} onDelete={deleteTodo} />;
};

This is clean MVC. Three files, three responsibilities, nothing overlapping.

The Fat MVC Problem

Here's where it goes wrong.

Imagine your restaurant manager (Controller) starts:

Taking orders ✅ (his job)
Cooking food ❌ (not his job)
Doing billing ❌ (not his job)
Cleaning tables ❌ (not his job)
Ordering supplies ❌ (not his job)

He's overloaded. He makes mistakes. He's slow. When he quits, the whole restaurant collapses because only he knew how everything worked.

This is Fat MVC.

What Fat MVC Looks Like in Code

// ❌ Fat Component — everything dumped in one place
const TodoPage = () => {
  const [todos, setTodos]       = useState([]);
  const [loading, setLoading]   = useState(false);
  const [error, setError]       = useState(null);
  const [filter, setFilter]     = useState('all');
  const [searchQuery, setSearch] = useState('');
  const [user, setUser]          = useState(null);

  // API call mixed with UI logic
  useEffect(() => {
    setLoading(true);
    fetch('/api/todos')
      .then(res => {
        if (!res.ok) throw new Error('Failed');
        return res.json();
      })
      .then(data => {
        // Business logic inside component
        const filtered = data.filter(t => !t.deleted && t.userId === user?.id);
        setTodos(filtered);
      })
      .catch(setError)
      .finally(() => setLoading(false));
  }, [user]);

  // Validation logic mixed in
  const deleteTodo = async (id) => {
    if (!id || typeof id !== 'number') return;
    if (!window.confirm('Are you sure?')) return;

    try {
      await fetch(`/api/todos/${id}`, { method: 'DELETE' });
      setTodos(prev => prev.filter(t => t.id !== id));
    } catch {
      setError('Delete failed');
    }
  };

  // Filtering logic inside component
  const filteredTodos = todos.filter(todo => {
    if (filter === 'completed') return todo.completed;
    if (filter === 'active') return !todo.completed;
    return todo.title.includes(searchQuery);
  });

  // Auth check mixed in
  if (!user) return <Login />;
  if (loading) return <Spinner />;
  if (error) return <ErrorBox message={error} />;

  return (
    <div>
      {/* ... all the UI ... */}
    </div>
  );
};

This is a real file from a real codebase somewhere. It has:

State management
API calls
Business validation
Filtering logic
Error handling
Auth checks
UI rendering

All in one component. 😵

Why Fat MVC is Dangerous

1. You can't test it

To test the deleteTodo logic, you have to render the entire component, mock the API, fake the user state, and simulate a button click. That's insane for a simple delete function.

2. You can't reuse it

Need the same delete logic in another component? Copy-paste. Now you have two bugs instead of one.

3. One change breaks everything

You change the API endpoint. Now you have to hunt through 300 lines to find every place that uses it.

4. New developers can't understand it

The fastest way to lose a new teammate is to point at a 500-line component and say "just figure it out."

5. It grows without stopping

Fat components attract more fat. "Oh this file already has everything, let me just add this one thing here..." Three months later it's 800 lines.

How Fat MVC Happens (Step by Step)

Understanding how this happens is just as important as knowing what to do about it.

Stage 1: The Innocent Start (Day 1)

// Simple, clean, totally fine
function TodoApp() {
  const [todos, setTodos] = useState([]);
  useEffect(() => {
    fetch('/api/todos').then(r => r.json()).then(setTodos);
  }, []);
  return <TodoList todos={todos} />;
}

100 lines. Easy to read. No problem.

Stage 2: Feature Creep (Week 3)

The client wants filters. And search. And pagination.

// Still manageable... but growing
function TodoApp() {
  const [todos, setTodos] = useState([]);
  const [filter, setFilter] = useState('all');
  const [page, setPage] = useState(1);
  const [search, setSearch] = useState('');

  // ... 50 more lines of logic
}

200 lines. A bit long, but okay.

Stage 3: The Collapse (Month 2)

Authentication. Error boundaries. User preferences. Notifications. Bulk delete. Analytics tracking.

// 😱 No one will ever refactor this
function TodoApp() {
  // 15 useState hooks
  // 5 useEffect hooks
  // 20 handler functions
  // 200 lines of JSX
}

600 lines. Nobody touches it. The Fat MVC problem is complete.

The lesson: Fat MVC doesn't happen in one bad decision. It happens through a hundred small "just this once" decisions.

MVC vs MVVM vs Flux (Redux)

Before we get to the solution, let's understand the three main architecture patterns — because modern React doesn't use pure MVC at all.

The Same Restaurant, Three Management Styles

MVC — The Traditional Manager

Customer → Waiter → Manager → Kitchen → Waiter → Customer

The manager (controller) manually coordinates everything. Explicit but can become overwhelming.

MVVM — The Digital Self-Service Kiosk

Customer ↔ Kiosk Screen ↔ Order System ↔ Kitchen

The screen (View) is directly connected to the order system (ViewModel). When you change your order, the screen updates automatically. No manager needed — it's reactive.

Flux/Redux — The Central Command System

Customer → Places Order Form → Central System → Updates All Screens → Customer sees update

All actions go through ONE central place. Nothing updates directly. Everything is tracked. Predictable but formal.

The Technical Comparison

Feature	MVC	MVVM	Flux (Redux)
Data Flow	Bidirectional	Two-way binding	One-way only
State Location	Scattered	In ViewModel	Centralized store
Complexity	Medium	Medium	High
Debugging	Tricky	Medium	Easy (time travel!)
Boilerplate	Low	Low	High
Best For	Small/medium apps	Most React apps	Large, complex apps

React's Reality

React actually behaves like MVVM by default:

// This IS MVVM — you just don't call it that
function Counter() {
  const [count, setCount] = useState(0); // ← ViewModel (state + logic)

  return (
    // ↓ View (automatically updates when state changes)
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
}

useState = ViewModel
JSX = View
The two-way binding = React's reactivity

For large apps, teams add Redux (Flux) on top:

Component (View)
    ↓
dispatch(action)        ← User action
    ↓
Reducer                 ← Handles the action
    ↓
Store                   ← Central state
    ↓
Component re-renders    ← View updates

Feature-Based Architecture: The Production Solution

Pure MVC breaks at scale. MVVM is what React naturally does. Flux/Redux solves global state. But none of these tell you how to organize your folders.

The real answer to Fat MVC in production is: Feature-Based Architecture with proper layering.

The Core Idea

Instead of organizing by type (all components together, all services together):

❌ Type-Based (Breaks at scale)
src/
├── components/    ← ALL components from ALL features
├── services/      ← ALL services from ALL features
├── hooks/         ← ALL hooks from ALL features

You organize by feature (everything for one feature lives together):

✅ Feature-Based (Scales well)
src/
├── features/
│   ├── todos/          ← Everything for the todo feature
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   └── api/
│   ├── auth/           ← Everything for auth
│   └── dashboard/      ← Everything for dashboard
├── shared/             ← Shared across features
│   ├── components/     ← Buttons, Inputs, Modal...
│   └── utils/
└── pages/              ← Just composition

The Four Layers (Inside Each Feature)

Every feature has four layers. Each layer has ONE job:

┌─────────────────────────────┐
│  Layer 1: API               │  ← Only HTTP calls. Nothing else.
├─────────────────────────────┤
│  Layer 2: Service           │  ← Business logic + data transformation
├─────────────────────────────┤
│  Layer 3: Hook (Controller) │  ← State management + side effects
├─────────────────────────────┤
│  Layer 4: Component (View)  │  ← Only renders JSX
└─────────────────────────────┘

Full Production Example (Todo App)

Let's build the same Todo app — but production-grade this time.

Layer 1: API (Pure Network Calls)

// features/todos/api/todoApi.js

const BASE_URL = '/api/todos';

export const todoApi = {
  getAll: () =>
    fetch(BASE_URL).then(res => {
      if (!res.ok) throw new Error('Failed to fetch todos');
      return res.json();
    }),

  delete: (id) =>
    fetch(`${BASE_URL}/${id}`, { method: 'DELETE' }).then(res => {
      if (!res.ok) throw new Error('Failed to delete todo');
    }),

  create: (todo) =>
    fetch(BASE_URL, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(todo),
    }).then(res => res.json()),
};

Rules for this layer:

Only HTTP calls
No business logic
No state
No UI knowledge

Layer 2: Service (Business Logic)

// features/todos/services/todoService.js

import { todoApi } from '../api/todoApi';

export const todoService = {
  // Business rule: only return non-deleted, non-archived todos
  getActiveTodos: async () => {
    const todos = await todoApi.getAll();
    return todos.filter(t => !t.deleted && !t.archived);
  },

  // Business rule: title must be non-empty before deleting
  deleteTodo: async (id) => {
    if (!id || typeof id !== 'number') {
      throw new Error('Invalid todo ID');
    }
    await todoApi.delete(id);
  },

  // Business rule: enforce max title length
  createTodo: async (title) => {
    if (!title.trim()) throw new Error('Title cannot be empty');
    if (title.length > 200) throw new Error('Title too long');

    return todoApi.create({ title: title.trim() });
  },
};

Rules for this layer:

Business logic and validation only
Calls the API layer
No state management
No React code

Layer 3: Hook (Controller / State)

// features/todos/hooks/useTodos.js

import { useState, useEffect, useCallback } from 'react';
import { todoService } from '../services/todoService';

export const useTodos = () => {
  const [todos, setTodos]     = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError]     = useState(null);

  // Load todos on mount
  useEffect(() => {
    todoService.getActiveTodos()
      .then(setTodos)
      .catch(err => setError(err.message))
      .finally(() => setLoading(false));
  }, []);

  // Delete handler
  const deleteTodo = useCallback(async (id) => {
    try {
      await todoService.deleteTodo(id);
      setTodos(prev => prev.filter(t => t.id !== id));
    } catch (err) {
      setError(err.message);
    }
  }, []);

  // Create handler
  const createTodo = useCallback(async (title) => {
    try {
      const newTodo = await todoService.createTodo(title);
      setTodos(prev => [...prev, newTodo]);
    } catch (err) {
      setError(err.message);
    }
  }, []);

  return { todos, loading, error, deleteTodo, createTodo };
};

Rules for this layer:

Manages component state
Calls the service layer
Returns clean data and functions to the view
No JSX

Layer 4: Component (View)

// features/todos/components/TodoList.jsx

const TodoList = ({ todos, onDelete }) => {
  return (
    <ul className="todo-list">
      {todos.map(todo => (
        <li key={todo.id} className="todo-item">
          <span>{todo.title}</span>
          <button
            onClick={() => onDelete(todo.id)}
            aria-label={`Delete ${todo.title}`}
          >
            Delete
          </button>
        </li>
      ))}
    </ul>
  );
};

export default TodoList;

// features/todos/components/CreateTodoForm.jsx

import { useState } from 'react';

const CreateTodoForm = ({ onCreate }) => {
  const [title, setTitle] = useState('');

  const handleSubmit = (e) => {
    e.preventDefault();
    onCreate(title);
    setTitle('');
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={title}
        onChange={e => setTitle(e.target.value)}
        placeholder="New todo..."
      />
      <button type="submit">Add</button>
    </form>
  );
};

export default CreateTodoForm;

Rules for this layer:

Only JSX and styling
No API calls
No business logic
Receives everything through props

The Page (Composition Only)

// pages/TodoPage.jsx

import { useTodos } from '../features/todos/hooks/useTodos';
import TodoList from '../features/todos/components/TodoList';
import CreateTodoForm from '../features/todos/components/CreateTodoForm';

const TodoPage = () => {
  const { todos, loading, error, deleteTodo, createTodo } = useTodos();

  if (loading) return <p>Loading...</p>;
  if (error)   return <p>Error: {error}</p>;

  return (
    <div>
      <h1>My Todos</h1>
      <CreateTodoForm onCreate={createTodo} />
      <TodoList todos={todos} onDelete={deleteTodo} />
    </div>
  );
};

export default TodoPage;

This page has zero business logic. It just composes pieces together.

Adding Global State (When You Need It)

For state shared across multiple features (like logged-in user, cart, notifications), use Zustand (modern) or Redux:

// store/todoStore.js (Zustand)
import { create } from 'zustand';

export const useTodoStore = create((set) => ({
  todos: [],
  setTodos: (todos) => set({ todos }),
  removeTodo: (id) => set(state => ({
    todos: state.todos.filter(t => t.id !== id)
  })),
}));

Now any component anywhere in the app can access or update todos without prop drilling.

The Full Folder Structure

src/
├── features/
│   ├── todos/
│   │   ├── api/
│   │   │   └── todoApi.js         ← HTTP only
│   │   ├── services/
│   │   │   └── todoService.js     ← Business logic
│   │   ├── hooks/
│   │   │   └── useTodos.js        ← State + controller
│   │   └── components/
│   │       ├── TodoList.jsx       ← Display list
│   │       └── CreateTodoForm.jsx ← Form
│   │
│   ├── auth/
│   │   ├── api/
│   │   ├── services/
│   │   ├── hooks/
│   │   └── components/
│   │
│   └── dashboard/
│       └── ...
│
├── shared/
│   ├── components/
│   │   ├── Button.jsx
│   │   ├── Input.jsx
│   │   └── Modal.jsx
│   ├── utils/
│   │   └── formatDate.js
│   └── constants/
│       └── config.js
│
├── store/
│   └── todoStore.js               ← Global state (Zustand/Redux)
│
└── pages/
    └── TodoPage.jsx               ← Composition only

Common Mistakes to Avoid

❌ Mistake 1: API calls inside components

// ❌ Don't do this
function TodoList() {
  useEffect(() => {
    fetch('/api/todos').then(...) // API call in component
  }, []);
}

// ✅ Do this — call through hook
function TodoList() {
  const { todos } = useTodos(); // clean
}

❌ Mistake 2: Business logic in JSX

// ❌ Don't do this — logic in the view
<button onClick={() => {
  if (todo.id && typeof todo.id === 'number') {
    fetch(`/api/${todo.id}`, { method: 'DELETE' });
    setTodos(todos.filter(t => t.id !== todo.id));
  }
}}>
  Delete
</button>

// ✅ Do this — clean handler from hook
<button onClick={() => deleteTodo(todo.id)}>
  Delete
</button>

❌ Mistake 3: Huge useEffect blocks

// ❌ Don't mix concerns in one effect
useEffect(() => {
  fetch('/api/todos').then(setTodos);
  fetch('/api/user').then(setUser);
  document.title = 'Todos';
  analytics.track('page_view');
}, []);

// ✅ Separate effects for separate concerns
useEffect(() => { fetchTodos(); }, []);
useEffect(() => { fetchUser(); }, []);
useEffect(() => { document.title = 'Todos'; }, []);

❌ Mistake 4: Prop drilling through 5 layers

// ❌ Passing props 4 levels deep is painful
<Page user={user}>
  <Layout user={user}>
    <Sidebar user={user}>
      <UserMenu user={user} />
    </Sidebar>
  </Layout>
</Page>

// ✅ Use Context or Zustand for shared data
const { user } = useAuthStore(); // accessed directly wherever needed

Which Architecture Should You Choose?

Here's a simple decision guide:

Is your app simple? (1-3 pages, 1 developer)
    → Just use components + hooks. No special architecture needed.

Is your app medium size? (5-15 pages, small team)
    → Feature-based structure + MVVM (hooks as ViewModel).

Is your app large? (15+ pages, multiple teams, complex state)
    → Feature-based + Redux/Zustand + strict layering.

Do different clients (web, mobile) share the same backend?
    → Add BFF layer in front of microservices.

The Golden Rule

Start simple. Add structure when the pain is real — not before.

Don't build a 10-layer architecture for a 5-page app. But don't build a 50-page app without layers either. Match the architecture to the actual complexity.

Key Takeaways

MVC separates your app into Model (data), View (UI), and Controller (logic). This is a good idea that prevents everything from mixing together.
React is not MVC. It's closest to MVVM — where hooks act as the ViewModel and JSX is the View.
Fat MVC happens slowly. One small shortcut at a time, until nobody can work with the code anymore.
Fat MVC symptoms: Giant components, business logic in JSX, API calls in the view, copy-pasted code everywhere.
The production solution is Feature-Based Architecture with four clear layers: API → Service → Hook → Component.
Each layer has ONE job. API layer does HTTP. Service does business logic. Hook manages state. Component renders UI.
For global state, use Zustand (simple) or Redux (complex apps). Don't prop drill through more than 2-3 levels.
Don't over-engineer early. Add structure as your app grows, not before.

One Paragraph to Remember

MVC was created to stop everything from mixing together. In React, we naturally end up with MVVM through hooks. But the real danger is Fat MVC — when one file ends up doing everything. The solution isn't a new pattern name. It's discipline: one layer for HTTP, one for business logic, one for state, one for UI. Feature-based folders keep related code together. That's it. That's the whole thing.

Found this useful? Share it with a teammate who still puts fetch calls directly inside components. You might just save their next code review.

Tags: #react #webdev #javascript #architecture #beginners #programming #frontend #systemdesign #cleancode

BFF (Backend For Frontend): The Middle Layer That Makes Your App Fast and Clean

Munna Thakur — Sat, 28 Mar 2026 08:17:45 +0000

You have a React app. It's calling 5 APIs. Your UI is slow, your code is messy, and your users are leaving. There's a pattern that solves all of this — and it's called BFF.

What is BFF?
Why Does It Exist?
The Problem Without BFF
How BFF Solves It
When Should You Use BFF?
How to Build a BFF (With Code)
BFF vs API Gateway
Real Companies Using BFF
Tradeoffs: Is BFF Always Good?
Key Takeaways

What is BFF?

BFF = Backend For Frontend

It is a server layer that sits between your frontend and your backend services.

Frontend (React / Mobile App)
           ↓
     BFF Layer (Node.js / GraphQL)
           ↓
  Backend Microservices + Databases

Think of it like this:

You go to a restaurant. You don't walk into the kitchen and talk to the chef, the prep cook, the dishwasher, and the manager separately. You talk to one waiter. The waiter goes to the kitchen, coordinates everything, and brings your food.

The waiter = BFF. The kitchen staff = your backend services.

Why Does It Exist?

Modern apps are built with microservices. Instead of one big server, you have many small ones:

User Service
Product Service
Recommendation Service
Payment Service
Notification Service

This is great for the backend team. But it creates a big problem for the frontend.

The Problem Without BFF

Let's say you're building a Netflix-style homepage. Your frontend needs to show:

Trending movies
Top-rated shows
Personalized recommendations
Continue watching list
New releases

Without BFF, your React app calls all these APIs separately:

// 😵 Messy Frontend Code
useEffect(() => {
  const trending     = fetch('/api/trending');
  const topRated     = fetch('/api/top-rated');
  const recommended  = fetch('/api/recommended');
  const continueWatching = fetch('/api/continue-watching');
  const newReleases  = fetch('/api/new-releases');

  Promise.all([trending, topRated, recommended, continueWatching, newReleases])
    .then(responses => Promise.all(responses.map(r => r.json())))
    .then(([t, tr, r, c, n]) => {
      setTrending(t);
      setTopRated(tr);
      setRecommended(r);
      setContinueWatching(c);
      setNewReleases(n);
    });
}, []);

Problems This Creates

1. Too Many Network Requests

Every request has a cost:

DNS lookup (finding the server's address)
TCP connection (opening a line of communication)
TLS handshake (security check for HTTPS)
Sending headers
Waiting for response

5 API calls = 5x that overhead. On a slow mobile connection, this kills your app.

2. Browser Connection Limits

Browsers allow only ~6 parallel connections per domain. If you make 10 API calls to the same domain, 4 of them are forced to wait in a queue.

API 1  ✅ Running
API 2  ✅ Running
API 3  ✅ Running
API 4  ✅ Running
API 5  ✅ Running
API 6  ✅ Running
API 7  ⏳ Waiting in queue...
API 8  ⏳ Waiting in queue...

3. Over-fetching Data

Your User Service returns 30 fields. Your frontend only needs 3. You're downloading data you'll never use — wasting bandwidth on every single request.

// ❌ What backend returns (too much)
{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "createdAt": "2020-01-01",
  "updatedAt": "2024-06-01",
  "internalScore": 98,
  "adminNotes": "...",
  "billingInfo": { ... },
  "preferences": { ... }
}

// ✅ What frontend actually needs
{
  "name": "John Doe",
  "email": "john@example.com"
}

4. Heavy, Complex Frontend Code

Your React component is now responsible for:

Fetching 5 APIs
Waiting for all of them
Handling each one's errors
Combining the data
Feeding it to the UI

That's too much responsibility for a component whose job is to display things.

5. Multiple Re-renders

In React, every setState() call triggers a re-render. 5 API calls = potentially 5 re-renders = janky UI.

How BFF Solves It

With a BFF, your frontend makes one single request:

// ✅ Clean Frontend Code
useEffect(() => {
  fetch('/api/homepage')
    .then(res => res.json())
    .then(data => setPageData(data));
}, []);

And your BFF server handles all the complexity:

// BFF Layer (Node.js + Express)
app.get('/api/homepage', async (req, res) => {

  // Call all backend services IN PARALLEL on the server
  const [trending, topRated, recommended, continueWatching, newReleases] =
    await Promise.all([
      getTrending(),
      getTopRated(),
      getRecommended(req.user.id),
      getContinueWatching(req.user.id),
      getNewReleases()
    ]);

  // Shape the data — only send what the UI needs
  res.json({
    hero: trending[0],
    rows: [
      { title: "Trending Now",      items: trending.map(pick(['id', 'title', 'thumbnail'])) },
      { title: "Top Rated",         items: topRated.map(pick(['id', 'title', 'thumbnail'])) },
      { title: "Recommended",       items: recommended.map(pick(['id', 'title', 'thumbnail'])) },
      { title: "Continue Watching", items: continueWatching.map(pick(['id', 'title', 'progress'])) },
      { title: "New Releases",      items: newReleases.map(pick(['id', 'title', 'thumbnail'])) },
    ]
  });
});

Why is This Faster?

Factor	Without BFF	With BFF
Requests from browser	5 requests	1 request
Network overhead	5× DNS, TCP, TLS	1× DNS, TCP, TLS
Browser queue bottleneck	Yes (can happen)	No
Data payload	Over-fetched	Exactly what's needed
React re-renders	5 (one per API)	1
Frontend complexity	High	Low

Server-side aggregation is faster because:

Servers have faster internal networks than public internet
No browser connection limits on the server
Parallel calls on the server complete in max(t1, t2, t3...) not t1 + t2 + t3

When Should You Use BFF?

Use BFF when you have one or more of these situations:

✅ Use BFF When:

1. Multiple clients with different data needs

Your web app, iOS app, and Android app all need different data shapes from the same backend. Instead of changing your backend for each, create a BFF per client:

Web Frontend  →  Web BFF   →  |               |
iOS App       →  iOS BFF   →  | Microservices |
Android App   →  Android BFF→ |               |

2. Too many API calls from the frontend

If your page loads need 4+ API calls to render, BFF reduces that to 1.

3. You have microservices

BFF is the perfect companion to a microservices architecture. It handles the "orchestration" so frontends don't have to.

4. Your frontend is too complex

If your React components have 100+ lines just for fetching and combining data, BFF can clean that up dramatically.

5. Performance matters

BFF enables caching on the server side. Once you fetch and shape the homepage data, you can cache it for 60 seconds. Every user in that window gets a near-instant response.

// Caching in BFF
app.get('/api/homepage', async (req, res) => {
  const cacheKey = 'homepage-data';

  // Check cache first
  const cached = await redis.get(cacheKey);
  if (cached) return res.json(JSON.parse(cached));

  // Fetch, shape, cache, respond
  const data = await fetchAndShapeHomepageData();
  await redis.set(cacheKey, JSON.stringify(data), 'EX', 60); // 60 second cache
  res.json(data);
});

❌ Skip BFF When:

You have a simple app with 1–2 API calls
You have a single client (web only, no mobile)
Your backend already returns perfectly shaped data
You don't have a team to maintain the extra service

How to Build a BFF (With Code)

Here's a minimal working BFF for a product page:

Folder Structure

project/
├── frontend/          → React App
│   └── src/
│       └── HomePage.jsx
├── bff/               → BFF Server
│   ├── index.js
│   ├── routes/
│   │   └── homepage.js
│   └── services/
│       ├── productService.js
│       ├── reviewService.js
│       └── userService.js
└── backend/           → Microservices (separate repos ideally)

BFF Server (`bff/index.js`)

const express = require('express');
const homepageRouter = require('./routes/homepage');

const app = express();
app.use(express.json());
app.use('/api', homepageRouter);

app.listen(4000, () => console.log('BFF running on port 4000'));

Route Handler (`bff/routes/homepage.js`)

const { getProducts }     = require('../services/productService');
const { getReviews }      = require('../services/reviewService');
const { getUser }         = require('../services/userService');

router.get('/homepage', async (req, res) => {
  try {
    // All calls run in PARALLEL
    const [products, reviews, user] = await Promise.all([
      getProducts(),
      getReviews(),
      getUser(req.headers['user-id'])
    ]);

    // Shape for the UI
    res.json({
      greeting: `Welcome back, ${user.firstName}!`,
      featured: products.slice(0, 5).map(p => ({
        id: p.id,
        name: p.name,
        price: p.price,
        image: p.thumbnailUrl   // only what we need, not all 20 fields
      })),
      topReviews: reviews.filter(r => r.rating >= 4).slice(0, 3)
    });

  } catch (err) {
    console.error(err);
    res.status(500).json({ error: 'Something went wrong' });
  }
});

React Frontend (`frontend/src/HomePage.jsx`)

// ✅ Super clean — no business logic here
function HomePage() {
  const [data, setData] = useState(null);

  useEffect(() => {
    fetch('http://localhost:4000/api/homepage')
      .then(res => res.json())
      .then(setData);
  }, []);

  if (!data) return <Skeleton />;

  return (
    <div>
      <h1>{data.greeting}</h1>
      <ProductRow items={data.featured} />
      <ReviewSection reviews={data.topReviews} />
    </div>
  );
}

Notice how clean the component is. It has one job: display what the BFF gives it.

BFF vs API Gateway

These are often confused. Here's the clear difference:

	API Gateway	BFF
Purpose	Routing, auth, rate limiting	UI-specific data shaping
Who uses it	All clients (web, mobile, 3rd party)	One specific client
Knows about UI?	No	Yes
Data shaping	Minimal	Heavy
Example tools	Kong, AWS API Gateway	Node.js, GraphQL/Apollo

In large systems, you often have both:

Client → API Gateway (auth + routing) → BFF (data shaping) → Microservices

Real Companies Using BFF

Netflix

Netflix has separate BFF layers for different devices (TV, browser, mobile). Each device needs different data, thumbnail sizes, and video quality options. A single backend can't know all of that — so each device gets its own BFF.

Meta (Facebook)

Meta uses GraphQL — which is essentially a supercharged BFF. The frontend queries exactly the data it needs, and the GraphQL layer resolves it from multiple backend services.

SoundCloud

SoundCloud was one of the first companies to formally describe the BFF pattern in 2015. They created separate backends for their web and mobile clients because the data needs were so different.

Tradeoffs: Is BFF Always Good?

No pattern is perfect. Here's the honest picture:

✅ Pros

Cleaner, simpler frontend code
Faster perceived performance (fewer round trips)
Easy to cache at the BFF layer
Each team (web, mobile) can own their BFF
Better security (hide internal service structure)

⚠️ Cons

One more service to deploy and maintain
One more thing that can fail (your BFF can become a bottleneck)
Can lead to code duplication if web BFF and mobile BFF share logic
Adds latency if done wrong (if BFF calls are sequential, not parallel)

The key rule: always call backend services in parallel inside your BFF using Promise.all(). Never await them one by one.

// ❌ BAD — Sequential, slow
const products = await getProducts();        // wait 200ms
const reviews  = await getReviews();         // wait 150ms
const user     = await getUser(id);          // wait 100ms
// Total: 450ms

// ✅ GOOD — Parallel, fast
const [products, reviews, user] = await Promise.all([
  getProducts(),    // \
  getReviews(),     //  > all run at the same time
  getUser(id)       // /
]);
// Total: 200ms (just the slowest one)

Key Takeaways

BFF is a server that lives between your frontend and your backend services. It's your frontend's dedicated helper.
It reduces API calls from many to one. Your browser makes 1 request, BFF handles the rest.
It shapes data for your UI. Send only what you need, nothing extra.
It enables server-side caching. Repeated requests can be served instantly.
It's not API Gateway. API Gateway is a generic router. BFF is UI-aware.
Always call services in parallel. Promise.all() is your best friend inside BFF.
Use it when you have multiple clients or complex data aggregation. Skip it for simple apps.

One-Line to Remember

BFF = One smart server that talks to many backend services, so your frontend doesn't have to.

If this helped you, consider sharing it. If you have questions, drop them in the comments below — happy to go deeper on any section!

Tags: #webdev #systemdesign #javascript #react #node #architecture #backend #frontend #performance

WebRTC, DRM & Netflix System Design: The Complete Guide (2026)

Munna Thakur — Wed, 18 Mar 2026 02:16:12 +0000

What you'll learn: How Netflix streams video to 230 million users without buffering. How DRM actually protects content (and why it's still not perfect). How WebRTC works peer-to-peer. Why you need LiveKit instead of raw WebRTC. And how to design all of it in a system design interview. Written in plain English with real architecture decisions.

The Core Problem — Why All This Exists
Netflix End-to-End Pipeline
Video Encoding & Adaptive Streaming
DRM — How Content Protection Actually Works
CDN — Why Playback Feels Instant
WebRTC — Real-Time Video from Scratch
WebRTC vs Socket.IO — When to Use What
LiveKit — Why You Should Not Build Raw WebRTC
Mini Netflix System Design (Interview Ready)
Real Challenges Engineers Face
Architecture Decision Guide
Interview Answers

1. The Core Problem — Why All This Exists

Every piece of technology in this article exists to solve a specific, painful problem.

What "just serving a video file" looks like

Imagine you're YouTube in 2005. You put a .mp4 file on a server. Users download it. Simple.

Now scale to 230 million users across every device, internet speed, and geography. Suddenly you have:

Problem	What happens without a solution
High latency	Users wait 10–30 seconds before video starts
Bandwidth variation	HD video freezes on slow connections
Piracy	Anyone can download and redistribute your paid content
Global delivery	A server in the US is slow for users in India
Real-time interaction	Standard HTTP can't do live two-way video
Scale	One server cannot handle a million concurrent viewers

The solutions:

Adaptive Streaming (HLS/DASH) → handles bandwidth variation
CDN → solves global delivery and scale
DRM → solves piracy
WebRTC → solves real-time interaction
LiveKit / SFU → solves WebRTC at scale

Each technology solves exactly one problem. That's why they all exist together in a modern streaming system.

2. Netflix End-to-End Pipeline

Before diving into individual components, here's the complete journey a video takes from creation to your screen:

Creator uploads raw video
         ↓
[Encoding Service]
  Convert to multiple resolutions (240p → 4K)
  Convert to streaming formats (HLS, DASH)
         ↓
[DRM Service]
  Encrypt every video segment
  Store encryption keys in Key Management System
         ↓
[Object Storage — S3]
  Store all encoded, encrypted segments
         ↓
[CDN — Cloudflare / Akamai]
  Cache segments at edge servers globally
         ↓
[User clicks Play]
         ↓
[Backend API]
  Authenticate user
  Return CDN URL for video
  Return license server URL
         ↓
[Video Player]
  Fetch .m3u8 manifest (HLS) from CDN
  Request DRM license (decryption key)
  Fetch encrypted video segments from CDN
  Decrypt segments → decode → render frames
         ↓
[User watches video]

Every step in this pipeline is solving a specific problem. Let's break each one down.

3. Video Encoding & Adaptive Streaming

Why raw video cannot be served directly

A raw 4K video file is enormous — often 50–100GB for a 2-hour movie. You cannot stream that over the internet. You need to:

Compress it — reduce file size while keeping acceptable quality
Create multiple versions — serve different quality based on available bandwidth
Chunk it — break it into small segments so streaming can start immediately

How encoding works

Tools like FFmpeg take the raw video and produce multiple renditions:

# FFmpeg command to create multiple quality levels from one source
ffmpeg -i original_movie.mp4 \
  -vf scale=426:240   -b:v 400k  output_240p.mp4 \
  -vf scale=854:480   -b:v 1000k output_480p.mp4 \
  -vf scale=1280:720  -b:v 2500k output_720p.mp4 \
  -vf scale=1920:1080 -b:v 5000k output_1080p.mp4

Each resolution is then cut into 2–6 second segments — small chunks that can be fetched independently.

HLS (HTTP Live Streaming) — The format that makes Netflix work

HLS is Apple's streaming protocol, now universally supported. It works like this:

Step 1 — The manifest file (.m3u8)

#EXTM3U
#EXT-X-VERSION:3

# Available quality levels
#EXT-X-STREAM-INF:BANDWIDTH=400000,RESOLUTION=426x240
/video/240p/playlist.m3u8

#EXT-X-STREAM-INF:BANDWIDTH=1000000,RESOLUTION=854x480
/video/480p/playlist.m3u8

#EXT-X-STREAM-INF:BANDWIDTH=2500000,RESOLUTION=1280x720
/video/720p/playlist.m3u8

#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080
/video/1080p/playlist.m3u8

Step 2 — Quality-specific playlist

#EXTM3U
#EXT-X-TARGETDURATION:6
#EXT-X-VERSION:3

#EXTINF:6.0,
/video/720p/segment_001.ts

#EXTINF:6.0,
/video/720p/segment_002.ts

#EXTINF:6.0,
/video/720p/segment_003.ts

Step 3 — The player reads bandwidth and switches quality

// This is what the video player does internally
// HLS.js does this automatically for you
const hls = new Hls({
  autoLevelEnabled: true,      // auto switch quality based on bandwidth
  startLevel: -1,              // -1 means auto-detect best starting quality
  abrBandWidthFactor: 0.95,    // use 95% of measured bandwidth for safety margin
});

hls.loadSource("https://cdn.netflix.com/videos/movie123/master.m3u8");
hls.attachMedia(videoElement);

hls.on(Hls.Events.LEVEL_SWITCHED, (event, data) => {
  console.log(`Quality switched to level ${data.level}`);
  // Level 0 = 240p, Level 1 = 480p, Level 2 = 720p, Level 3 = 1080p
});

This is Adaptive Bitrate Streaming (ABR) — the player constantly monitors download speed and switches quality in real time. Your internet slows down → player quietly drops to 480p. It speeds up → player bumps back to 1080p. No buffering, no interruption.

4. DRM — How Content Protection Actually Works

DRM (Digital Rights Management) is the system that prevents you from downloading and redistributing Netflix content. Understanding how it actually works (not just "it encrypts the video") is what separates junior devs from senior ones.

The Three Major DRM Systems

DRM System	Created By	Used On
Widevine	Google	Chrome, Android, most browsers
FairPlay	Apple	Safari, iOS, macOS
PlayReady	Microsoft	Edge, Windows, Xbox

Netflix uses all three — which browser/device you're on determines which DRM system is used.

How DRM Actually Works (Step by Step)

Video before DRM:
[Raw segment data — anyone can play this]

Video after DRM encryption:
[Encrypted segment — looks like garbage without the key]

The key never travels with the video.
The key only comes from the License Server after authorization.

The complete DRM flow:

1. Studio delivers movie to Netflix

2. Netflix encrypts every video segment with AES-128 encryption
   - A unique content key (CEK) is generated
   - CEK is stored in a Key Management System (KMS) — NOT in the video

3. Encrypted segments uploaded to CDN

4. User signs up, pays for subscription

5. User clicks Play

6. Player sends License Request to DRM License Server:
   {
     userId: "user_123",
     contentId: "movie_abc",
     sessionToken: "jwt_...",
     deviceFingerprint: "browser_xyz"
   }

7. License Server checks:
   ✓ Is user subscribed?
   ✓ Is this content available in user's region?
   ✓ Is device authorized?
   ✓ Has concurrent stream limit been exceeded?

8. If all checks pass, License Server returns:
   {
     contentKey: "AES_KEY_encrypted_for_this_device",
     expiresAt: "2026-01-01T12:00:00Z",
     allowOffline: false,
     hdcpRequired: true    // requires HDCP-compliant monitor for 4K
   }

9. Player decrypts segments in memory using the content key
   (key never written to disk)

10. Decoded frames rendered to screen
    (OS-level protection prevents screen capture in Widevine L1)

DRM Security Levels — Why Netflix is 1080p on Chrome but 4K on the App

Widevine Security Levels:

L1 — Highest security
  - Decryption happens in hardware (TEE — Trusted Execution Environment)
  - Screen capture blocked at hardware level
  - 4K + HDR content allowed
  - Available on: Android apps, Netflix Windows app, Chromecast

L2 — Medium security
  - Rarely used

L3 — Software only
  - Decryption in software (can be intercepted in theory)
  - Netflix limits to 1080p
  - Available on: Chrome, Firefox, Edge browsers

This is why you can watch 4K on the Netflix app but the same show is only 1080p in Chrome. It's not a technical limitation — it's a content protection policy based on security level.

What DRM Cannot Prevent

Here's the honest truth that every developer should know:

DRM prevents:             DRM cannot prevent:
✅ Direct file download   ❌ Screen recording (at L3)
✅ HTTP segment download  ❌ Analog capture (HDMI splitter)
✅ URL sharing            ❌ Camcorder pointed at screen
✅ Unauthorized players   ❌ A determined attacker with hardware

DRM's real goal is not to make piracy impossible.
It's to make piracy hard enough that casual users don't bother,
and to satisfy the legal requirements of content studios.

DRM Frontend Integration

// Encrypted Media Extensions (EME) — the browser API for DRM
const video = document.querySelector("video");

// Configuration tells browser which DRM systems you support
const config = [{
  initDataTypes: ["cenc"],
  videoCapabilities: [{
    contentType: 'video/mp4; codecs="avc1.42E01E"',
    robustness: "SW_SECURE_CRYPTO",   // Widevine L3 (browser)
  }],
}];

// Request access to DRM system
const access = await navigator.requestMediaKeySystemAccess(
  "com.widevine.alpha",   // Widevine
  config
);

const mediaKeys = await access.createMediaKeys();
await video.setMediaKeys(mediaKeys);

// When video encounters encrypted segments, this fires
video.addEventListener("encrypted", async (event) => {
  const session = mediaKeys.createSession();

  // Send license request to YOUR license server
  session.addEventListener("message", async (msgEvent) => {
    const licenseResponse = await fetch("/api/drm/license", {
      method: "POST",
      headers: {
        "Content-Type": "application/octet-stream",
        "Authorization": `Bearer ${userToken}`,
      },
      body: msgEvent.message,   // Widevine license request blob
    });

    const license = await licenseResponse.arrayBuffer();
    await session.update(license);  // Give key to player
  });

  await session.generateRequest(event.initDataType, event.initData);
});

In practice, you would use Shaka Player or Video.js with DRM plugins rather than writing EME code directly — but understanding what happens underneath is what counts in an interview.

5. CDN — Why Playback Feels Instant

The Geography Problem

Netflix's servers are in the US. You're in Mumbai. Without a CDN, every video request crosses the Pacific Ocean — adding ~300ms of network latency to every segment fetch. With 6-second segments, that adds noticeable buffering.

How CDN Works

Without CDN:
User in Mumbai → Request → Netflix Server (Virginia, USA)
                            ~300ms round trip per request
                            Video starts after 3-5 seconds

With CDN:
User in Mumbai → Request → CDN Edge Server (Mumbai)
                            ~10ms round trip
                            Video starts in < 1 second

How CDN caches video segments:

First user in Mumbai plays Movie X (720p, segment 001):
1. Player requests segment_001.ts from CDN
2. CDN edge (Mumbai) doesn't have it → fetches from Netflix origin
3. CDN caches segment_001.ts in Mumbai edge
4. Delivers to user

1000th user in Mumbai plays Movie X (720p, segment 001):
1. Player requests segment_001.ts from CDN
2. CDN edge (Mumbai) has it cached → delivers instantly
3. Zero load on Netflix origin servers

Popular video segments (new releases, trending shows) are cached at hundreds of edge locations worldwide. Netflix actually pre-positions content they predict will be popular before it's released — pushing it to CDN nodes in advance.

CDN Cache-Control headers for video:
Cache-Control: public, max-age=86400     # Static segments → cache 24 hours
Cache-Control: no-cache                  # Manifest (.m3u8) → always re-fetch
                                          (because quality levels may change)

6. WebRTC — Real-Time Video from Scratch

Why WebRTC Was Invented

Before WebRTC (pre-2012), doing a video call in a browser required Flash or a plugin. Video data traveled: User A → Server → User B. This added latency at both hops and put enormous load on servers.

WebRTC was designed to enable browser-to-browser direct video/audio with no plugins and no server in the data path. The result: sub-100ms latency, no server bandwidth costs for video data, and true peer-to-peer communication.

How WebRTC Establishes a Connection (Step by Step)

The tricky part: how do two browsers find each other on the internet? They're both behind NAT (your home router). They don't know each other's public IP. This is what makes WebRTC setup complex.

The connection process (called "signaling"):

User A (wants to call User B)
      ↓
Step 1: Create RTCPeerConnection
Step 2: Get local media (camera/mic)
Step 3: Create an "offer" (SDP — Session Description Protocol)
        The offer says: "I can send/receive video in these formats..."
Step 4: Send offer to User B via signaling server (Socket.IO)

User B receives offer
      ↓
Step 5: Create RTCPeerConnection
Step 6: Set A's offer as remote description
Step 7: Create an "answer" (their own SDP)
Step 8: Send answer back to User A via signaling server

Both users exchange ICE candidates
      ↓
Step 9: ICE (Interactive Connectivity Establishment) finds the best path:
        Option 1: Direct P2P (if no NAT issues) — best
        Option 2: Via STUN server (discover public IP) — good
        Option 3: Via TURN server (relay) — fallback

Step 10: Connection established — video flows directly peer-to-peer

Real WebRTC Code

// ============================================
// Complete WebRTC video call implementation
// ============================================

const servers = {
  iceServers: [
    { urls: "stun:stun.l.google.com:19302" },    // STUN: discover public IP
    {
      urls: "turn:turn.yourserver.com:3478",       // TURN: relay fallback
      username: "user",
      credential: "password",
    },
  ],
};

let localStream;
let peerConnection;

// Step 1 — Get camera and microphone
const startCall = async () => {
  localStream = await navigator.mediaDevices.getUserMedia({
    video: { width: 1280, height: 720 },
    audio: true,
  });

  document.getElementById("localVideo").srcObject = localStream;

  // Step 2 — Create peer connection
  peerConnection = new RTCPeerConnection(servers);

  // Add local stream tracks to peer connection
  localStream.getTracks().forEach((track) => {
    peerConnection.addTrack(track, localStream);
  });

  // Step 3 — When remote stream arrives, display it
  peerConnection.ontrack = (event) => {
    document.getElementById("remoteVideo").srcObject = event.streams[0];
  };

  // Step 4 — Send ICE candidates to remote peer via signaling
  peerConnection.onicecandidate = (event) => {
    if (event.candidate) {
      socket.emit("ice-candidate", {
        roomId,
        candidate: event.candidate,
      });
    }
  };

  // Step 5 — Create and send offer
  const offer = await peerConnection.createOffer();
  await peerConnection.setLocalDescription(offer);

  socket.emit("offer", { roomId, offer });
};

// ── On the receiving side ──────────────────────

socket.on("offer", async ({ offer }) => {
  peerConnection = new RTCPeerConnection(servers);

  // Set up the same event handlers...
  peerConnection.ontrack = (event) => {
    document.getElementById("remoteVideo").srcObject = event.streams[0];
  };

  peerConnection.onicecandidate = (event) => {
    if (event.candidate) {
      socket.emit("ice-candidate", { roomId, candidate: event.candidate });
    }
  };

  // Get local media and add tracks
  localStream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
  localStream.getTracks().forEach(track => peerConnection.addTrack(track, localStream));

  // Set remote description from offer
  await peerConnection.setRemoteDescription(offer);

  // Create answer
  const answer = await peerConnection.createAnswer();
  await peerConnection.setLocalDescription(answer);

  socket.emit("answer", { roomId, answer });
});

socket.on("answer", async ({ answer }) => {
  await peerConnection.setRemoteDescription(answer);
});

socket.on("ice-candidate", async ({ candidate }) => {
  await peerConnection.addIceCandidate(candidate);
});

STUN vs TURN — Understanding NAT Traversal

STUN Server (Session Traversal Utilities for NAT):
  - Tells you your own public IP address
  - Your router hides your real IP — STUN reveals it
  - Used 80% of the time for P2P connections
  - Cheap — almost no bandwidth cost

TURN Server (Traversal Using Relays around NAT):
  - Full relay server — all data goes through it
  - Used when P2P fails (symmetric NAT, strict firewalls)
  - Expensive — you pay for all video bandwidth
  - Used ~20% of the time
  - Without TURN: ~15% of calls fail to connect

Real ICE process:
  1. Try direct P2P → success 40% of the time
  2. Try STUN → success 40% more
  3. Fall back to TURN → handles remaining 20%

7. WebRTC vs Socket.IO — When to Use What

This is a common interview question and source of confusion. They solve completely different problems.

Socket.IO — Server-based real-time messaging

How Socket.IO works:
User A → Server → User B
       ↑       ↓
   Message   Message

All data goes through your server. Always.

// Socket.IO — perfect for chat, notifications, presence
// Server
io.on("connection", (socket) => {
  socket.on("message", (data) => {
    io.to(data.room).emit("message", data);  // relay to room
  });
});

// Client
socket.emit("message", { room: "general", text: "Hello!" });
socket.on("message", (data) => {
  displayMessage(data);
});

WebRTC — Peer-to-peer binary data (video/audio/files)

How WebRTC works:
User A ←──────────────→ User B
        Direct connection
        No server in video path

// WebRTC — perfect for video calls, file sharing
// Video travels directly browser-to-browser
// Server is only needed for initial handshake (signaling)

The Real Comparison

Feature	Socket.IO	WebRTC
Data path	Client → Server → Client	Client → Client (direct)
Latency	50–200ms	20–100ms
Video/audio	❌ Not designed for it	✅ Built for it
Text/events	✅ Perfect	✅ Also possible (DataChannel)
Server cost	High (all data through server)	Low (only signaling)
Setup complexity	Simple	Complex
Scales to millions	Hard without clustering	Harder (need SFU)
Firewall issues	Rare	TURN needed sometimes

When to use each

Use Socket.IO for:
✅ Chat messages
✅ Notifications ("3 people liked your post")
✅ Collaborative cursors (Google Docs style)
✅ Live dashboards (stock prices, sports scores)
✅ Game state synchronization (turn-based)
✅ WebRTC signaling itself!

Use WebRTC for:
✅ Video calls (Google Meet, Zoom)
✅ Voice calls
✅ Live streaming with < 500ms latency
✅ Screen sharing
✅ Real-time file transfer
✅ Online gaming with low-latency requirements

The trick: Many production apps use BOTH.
Socket.IO handles signaling for WebRTC + chat/notifications.
WebRTC handles video/audio stream.

8. LiveKit — Why You Should Not Build Raw WebRTC

The Problem with Raw WebRTC at Scale

Raw WebRTC is P2P — it works great for 2 people. But what happens in a video call with 10 people?

Naive P2P Mesh approach (10 users):
User 1 sends video to → Users 2, 3, 4, 5, 6, 7, 8, 9, 10 (9 streams)
User 2 sends video to → Users 1, 3, 4, 5, 6, 7, 8, 9, 10 (9 streams)
...
Total connections: n(n-1)/2 = 45 connections

Each user uploads 9 streams simultaneously.
On a typical 10 Mbps upload connection: 9 × 1 Mbps video = 9 Mbps used.
This completely saturates the user's upload bandwidth.
At 20 users it becomes completely impossible.

The Solution: SFU (Selective Forwarding Unit)

An SFU is a media server that sits between participants and intelligently forwards streams:

With SFU (LiveKit):
User 1 → SFU → User 2
              → User 3
              → User 4
              → ...

User 1 only uploads ONE stream (to SFU)
SFU forwards it to everyone else
User 1's upload: 1 × 1 Mbps = 1 Mbps — sustainable at any scale

SFU benefits:
✅ Each user uploads only 1 stream
✅ SFU can selectively forward (only send video of visible participants)
✅ SFU can transcode for different quality subscribers
✅ Recording is handled at the SFU (not the client)
✅ Simulcast: user uploads 3 quality levels, SFU picks the right one per subscriber

Why LiveKit Specifically

Building your own SFU from scratch is a months-long project. LiveKit gives you:

LiveKit provides out of the box:
✅ SFU infrastructure
✅ React/React Native SDKs
✅ Recording and egress (stream to RTMP/YouTube/Twitch)
✅ End-to-end encryption
✅ Simulcast support
✅ Screen sharing
✅ Data channels (for chat alongside video)
✅ Kubernetes-ready deployment
✅ Self-hostable (open source) or cloud service

LiveKit in a React App

// Install: npm install @livekit/components-react livekit-client

import {
  LiveKitRoom,
  VideoConference,
  RoomAudioRenderer,
} from "@livekit/components-react";
import "@livekit/components-styles";

// That's it — complete video conference UI in ~15 lines
const VideoCall = ({ roomName, userId }) => {
  const [token, setToken] = useState("");

  useEffect(() => {
    // Fetch a room token from YOUR backend
    fetch(`/api/livekit/token?room=${roomName}&user=${userId}`)
      .then(res => res.json())
      .then(data => setToken(data.token));
  }, [roomName, userId]);

  if (!token) return <div>Connecting...</div>;

  return (
    <LiveKitRoom
      video={true}
      audio={true}
      token={token}
      serverUrl={process.env.REACT_APP_LIVEKIT_URL}
      style={{ height: "100vh" }}
    >
      <VideoConference />
      <RoomAudioRenderer />
    </LiveKitRoom>
  );
};

// Backend: Generate a room access token (Node.js)
const { AccessToken } = require("livekit-server-sdk");

app.get("/api/livekit/token", (req, res) => {
  const { room, user } = req.query;

  const token = new AccessToken(
    process.env.LIVEKIT_API_KEY,
    process.env.LIVEKIT_API_SECRET,
    { identity: user }
  );

  token.addGrant({
    roomJoin: true,
    room: room,
    canPublish: true,
    canSubscribe: true,
  });

  res.json({ token: token.toJwt() });
});

WebRTC vs LiveKit Decision

Use raw WebRTC when:
✅ 1-to-1 calls only
✅ You want zero infrastructure cost
✅ Simplest possible setup
✅ Learning/experimenting

Use LiveKit when:
✅ 3+ participants in a call
✅ You need recording
✅ You need live streaming egress (RTMP to YouTube)
✅ You need transcription/AI integration
✅ Production application at any real scale

9. Mini Netflix System Design (Interview Ready)

This is how you answer "Design Netflix" or "Design a video streaming platform" in a system design interview.

Clarify Requirements First (Always do this)

Functional Requirements:
✅ Users can watch videos
✅ Multiple video quality levels
✅ Adaptive quality (auto-switch based on connection)
✅ Resume playback from where user left off
✅ Content protection (paid content)
✅ Search and browse catalog
✅ Recommendations based on watch history

Non-Functional Requirements:
✅ Scale: 100 million daily active users
✅ Availability: 99.99% uptime
✅ Latency: Video starts playing within 2 seconds
✅ Global: Users worldwide

High-Level Architecture

                        ┌─────────────────┐
                        │   Load Balancer │
                        └────────┬────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              ▼                  ▼                  ▼
     ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
     │   Auth API   │  │  Metadata API│  │  License API │
     │   Service    │  │   Service    │  │  Service(DRM)│
     └──────┬───────┘  └──────┬───────┘  └──────┬───────┘
            │                  │                  │
     ┌──────▼───────┐  ┌──────▼───────┐  ┌──────▼───────┐
     │  User DB     │  │  Video DB    │  │  Key Mgmt    │
     │ (PostgreSQL) │  │ (PostgreSQL/ │  │  System      │
     └──────────────┘  │  Cassandra)  │  └──────────────┘
                        └──────────────┘

     ┌──────────────────────────────────────────────────┐
     │                  Upload Pipeline                  │
     │  Upload Service → Message Queue → Encoding Worker│
     │                                  (FFmpeg on EC2) │
     └──────────────────────────┬───────────────────────┘
                                 │
                        ┌────────▼────────┐
                        │   S3 Storage    │
                        │ (encoded files) │
                        └────────┬────────┘
                                 │
                        ┌────────▼────────┐
                        │  CDN (Akamai /  │
                        │   Cloudflare)   │
                        └────────┬────────┘
                                 │
                        ┌────────▼────────┐
                        │  Video Player   │
                        │ (HLS + EME/DRM) │
                        └─────────────────┘

Database Design

-- Users table
CREATE TABLE users (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email       VARCHAR(255) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  plan        VARCHAR(50) DEFAULT 'basic',   -- basic, standard, premium
  created_at  TIMESTAMP DEFAULT NOW()
);

-- Videos table (metadata only — actual files in S3)
CREATE TABLE videos (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  title       VARCHAR(500) NOT NULL,
  description TEXT,
  duration_seconds INTEGER,
  genres      TEXT[],                         -- PostgreSQL array
  status      VARCHAR(50) DEFAULT 'processing', -- processing, ready, failed
  content_id  VARCHAR(255),                   -- DRM content ID
  created_at  TIMESTAMP DEFAULT NOW()
);

-- Video files (multiple quality levels per video)
CREATE TABLE video_files (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  video_id    UUID REFERENCES videos(id),
  quality     VARCHAR(20),                    -- 240p, 480p, 720p, 1080p, 4k
  cdn_url     VARCHAR(1000),                  -- HLS manifest URL
  file_size_bytes BIGINT,
  created_at  TIMESTAMP DEFAULT NOW()
);

-- Watch history (for resume playback)
CREATE TABLE watch_history (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id     UUID REFERENCES users(id),
  video_id    UUID REFERENCES videos(id),
  position_seconds INTEGER DEFAULT 0,        -- resume position
  completed   BOOLEAN DEFAULT FALSE,
  watched_at  TIMESTAMP DEFAULT NOW(),
  UNIQUE(user_id, video_id)
);

Video Upload & Processing Flow

// 1. Upload Service — handles multipart upload to S3
app.post("/api/upload", async (req, res) => {
  const { title, description } = req.body;

  // Create video record in DB
  const video = await db.video.create({
    data: { title, description, status: "processing" }
  });

  // Get pre-signed S3 URL (client uploads directly to S3, bypassing our server)
  const uploadUrl = await s3.getSignedUploadUrl({
    key: `raw/${video.id}/original.mp4`,
    contentType: "video/mp4",
    expiresIn: 3600,
  });

  // Publish encoding job to queue
  await messageQueue.publish("encoding-jobs", {
    videoId: video.id,
    s3Key: `raw/${video.id}/original.mp4`,
  });

  res.json({ videoId: video.id, uploadUrl });
});

// 2. Encoding Worker (separate service, runs on powerful EC2)
messageQueue.consume("encoding-jobs", async (job) => {
  const { videoId, s3Key } = job;

  // Download from S3
  await s3.download(s3Key, "/tmp/original.mp4");

  // Encode to multiple qualities using FFmpeg
  const qualities = ["240p", "480p", "720p", "1080p"];

  for (const quality of qualities) {
    await ffmpeg.encode({
      input: "/tmp/original.mp4",
      output: `/tmp/${quality}/`,
      quality,
      format: "hls",
      segmentDuration: 6,
    });

    // Apply DRM encryption to segments
    await drm.encryptHls({
      inputDir: `/tmp/${quality}/`,
      contentId: videoId,
    });

    // Upload encrypted segments to S3
    await s3.uploadDirectory(`/tmp/${quality}/`, `videos/${videoId}/${quality}/`);
  }

  // Update video status
  await db.video.update({ id: videoId, status: "ready" });
});

Full Playback Flow (Backend + Frontend)

// Backend — Play endpoint
app.get("/api/videos/:id/play", authenticate, async (req, res) => {
  const video = await db.video.findById(req.params.id);

  // Check subscription for premium content
  if (video.isPremium && req.user.plan === "basic") {
    return res.status(403).json({ error: "Upgrade to watch this content" });
  }

  // Get resume position
  const history = await db.watchHistory.findOne({
    userId: req.user.id,
    videoId: video.id,
  });

  // Return playback info
  res.json({
    manifestUrl: `https://cdn.netflix.com/videos/${video.id}/master.m3u8`,
    licenseServerUrl: `https://license.netflix.com/widevine`,
    resumePosition: history?.positionSeconds ?? 0,
    contentId: video.contentId,
  });
});

// Frontend — Video Player Component
const VideoPlayer = ({ videoId }) => {
  const playerRef = useRef(null);
  const hlsRef = useRef(null);

  useEffect(() => {
    const initPlayer = async () => {
      // Get playback info from API
      const { manifestUrl, licenseServerUrl, resumePosition, contentId } =
        await fetch(`/api/videos/${videoId}/play`).then(r => r.json());

      const video = playerRef.current;

      // Initialize HLS.js
      const hls = new Hls({ autoLevelEnabled: true });
      hlsRef.current = hls;
      hls.loadSource(manifestUrl);
      hls.attachMedia(video);

      // Set up DRM (Widevine)
      video.addEventListener("encrypted", async (event) => {
        if (!video.mediaKeys) {
          const access = await navigator.requestMediaKeySystemAccess(
            "com.widevine.alpha",
            [{ initDataTypes: ["cenc"], videoCapabilities: [{ contentType: 'video/mp4; codecs="avc1"' }] }]
          );
          const mediaKeys = await access.createMediaKeys();
          await video.setMediaKeys(mediaKeys);
        }

        const session = video.mediaKeys.createSession();
        session.addEventListener("message", async (msg) => {
          const license = await fetch(licenseServerUrl, {
            method: "POST",
            headers: { Authorization: `Bearer ${userToken}` },
            body: msg.message,
          }).then(r => r.arrayBuffer());

          await session.update(license);
        });

        await session.generateRequest(event.initDataType, event.initData);
      });

      hls.on(Hls.Events.MANIFEST_PARSED, () => {
        video.currentTime = resumePosition;   // resume where user left off
        video.play();
      });
    };

    initPlayer();

    // Save position every 5 seconds
    const saveInterval = setInterval(() => {
      if (playerRef.current) {
        fetch(`/api/videos/${videoId}/progress`, {
          method: "POST",
          body: JSON.stringify({ position: Math.floor(playerRef.current.currentTime) }),
        });
      }
    }, 5000);

    return () => {
      hlsRef.current?.destroy();
      clearInterval(saveInterval);
    };
  }, [videoId]);

  return (
    <video
      ref={playerRef}
      controls
      style={{ width: "100%", maxHeight: "80vh" }}
    />
  );
};

Scaling Strategy

Handling 100 million daily users:

1. CDN handles ~95% of video traffic
   - No origin servers involved in most plays
   - Cloudflare / Akamai has edge nodes everywhere

2. Horizontal scaling for APIs
   - Stateless services behind load balancer
   - Auto-scaling groups (more traffic → more instances)

3. Database scaling
   - Read replicas for metadata queries
   - Redis caching for popular video metadata
   - Cassandra/DynamoDB for watch history (write-heavy, needs sharding)

4. Async encoding
   - Message queue (SQS/Kafka) for encoding jobs
   - Encoding workers scale independently
   - Slow encoding doesn't block uploads

5. Microservices
   - Upload Service
   - Encoding Service
   - Streaming Service (CDN management)
   - License Service (DRM)
   - Recommendation Service
   - Auth Service
   Each scales independently based on its own load.

10. Real Challenges Engineers Face

Challenge 1 — Buffering Under Poor Networks

Problem: User has 2 Mbps connection. 1080p requires 5 Mbps.

Solution stack:
1. Adaptive Bitrate (ABR) — auto-switch to 480p
2. Pre-buffering — download 3 segments ahead
3. CDN edge selection — pick nearest server
4. Connection quality prediction — use network API to detect before buffering

// Browser Network Information API
const connection = navigator.connection;
if (connection.downlink < 2) {
  // Proactively cap quality at 480p
  hls.currentLevel = 1;   // Index of 480p in levels array
}

Challenge 2 — DRM Integration Complexity

Problem: Three different DRM systems for three different browsers.

Solution — Multi-DRM with a single abstraction:

Shaka Player handles DRM detection automatically:

const player = new shaka.Player(videoElement);
await player.configure({
  drm: {
    servers: {
      "com.widevine.alpha":  "https://license.example.com/widevine",   // Chrome
      "com.apple.fps":       "https://license.example.com/fairplay",   // Safari
      "com.microsoft.playready": "https://license.example.com/playready" // Edge
    }
  }
});
// Shaka picks the right DRM for the current browser automatically
await player.load("https://cdn.example.com/video/master.m3u8");

Challenge 3 — WebRTC ICE Failure (Calls Don't Connect)

Problem: ~15% of WebRTC calls fail to connect without TURN.

Root cause: Symmetric NAT — user's router blocks incoming P2P connections.

Solution:
1. Deploy TURN server (coturn is open source)
2. Use paid TURN providers (Twilio STUN/TURN, Xirsys)
3. Budget: TURN bandwidth = all video passing through it (~$0.10/GB)

Detection:
peerConnection.oniceconnectionstatechange = () => {
  if (peerConnection.iceConnectionState === "failed") {
    // Force TURN relay — restart ICE with only TURN candidates
    peerConnection.restartIce();
  }
};

Challenge 4 — Storage Costs

Problem: 1 hour of raw 4K video = ~50GB
         1 movie encoded to all qualities = ~15GB
         Netflix catalog = 15,000+ titles

Math:
15,000 titles × 15GB = 225TB just for video files
Plus CDN cache across 200+ edge locations...

Solutions:
1. S3 Intelligent-Tiering — automatically move rarely-accessed content to cheaper storage
2. Compress older content more aggressively
3. Delete source files after encoding (only keep encoded versions)
4. Use per-title encoding — Netflix uses ML to find optimal bitrate per-scene
   (action scenes need higher bitrate; static scenes can use lower)

11. Architecture Decision Guide

"Which architecture do I need?"

Is it real-time (< 500ms latency)?
  YES → WebRTC (+ LiveKit if 3+ people)
  NO  ↓

Is it live streaming (one-to-many, < 5s delay acceptable)?
  YES → RTMP ingest + HLS output + CDN
  NO  ↓

Is it on-demand video (Netflix type)?
  YES → HLS + CDN + DRM + Adaptive Bitrate
  NO  ↓

Is it just real-time events/messages?
  YES → Socket.IO / WebSockets

"Do I need DRM?"

Is this paid premium content?       → YES → DRM required
Could redistribution harm business? → YES → DRM required
Is this free/public content?        → NO  → DRM optional
Is this internal/corporate video?   → NO  → DRM probably not needed

"WebRTC or LiveKit?"

Is it 1-to-1 call only?          → Raw WebRTC is fine
Is it 3+ participants?            → LiveKit / SFU required
Do you need recording?            → LiveKit
Do you need RTMP output?          → LiveKit
Is this production? > 100 users?  → LiveKit
Are you learning/prototyping?     → Raw WebRTC to understand concepts

12. Interview-Ready Answers

Q: How does Netflix serve video to millions of users without buffering?

Netflix uses a combination of adaptive bitrate streaming (HLS/DASH), a global CDN that caches video segments at edge servers worldwide, and DRM-encrypted content delivery. When a user plays a video, the player fetches a manifest file listing available quality levels, then the HLS.js player monitors bandwidth and automatically switches quality. The CDN serves segments from the nearest edge node — often less than 10ms away — while the origin servers only need to serve the small percentage of requests that miss the CDN cache.

Q: How does DRM work and why can't it be bypassed?

DRM encrypts video segments using AES-128. The encryption key is never included with the video — it only comes from a License Server after verifying the user's subscription and device authorization. In browsers, the decryption happens inside the browser's Content Decryption Module (CDM), a closed-source component that protects the key in a sandbox. At the hardware level (Widevine L1), decryption happens inside a Trusted Execution Environment where even the OS cannot access the key. However, DRM isn't foolproof — screen recording is possible at the software level (L3), and analog capture is always possible. DRM's goal is to raise the effort bar high enough for casual users and to satisfy legal studio requirements.

Q: Why use WebRTC instead of WebSockets for video calls?

WebSockets route all data through a server, which adds latency and creates enormous server bandwidth costs for video. WebRTC establishes a direct peer-to-peer connection between browsers using ICE/STUN/TURN for NAT traversal, so video data travels directly between users without touching a server. This reduces latency from 100–200ms to 20–100ms and eliminates server bandwidth costs for the video stream. The server (using Socket.IO) is still used for signaling — exchanging the SDP offer/answer and ICE candidates — but once the connection is established, all media flows peer-to-peer.

Q: What is an SFU and why does LiveKit use one?

In a multi-user video call, pure peer-to-peer creates an N×(N-1) mesh — with 10 users, each user uploads 9 video streams simultaneously, which saturates their upload bandwidth. An SFU (Selective Forwarding Unit) is a media server where each user uploads one stream to the SFU, and the SFU forwards it to all subscribers. This reduces each user's upload requirement from N-1 streams to 1 stream. The SFU can also selectively forward — only sending video for visible participants — and support simulcast, where users upload multiple quality levels and the SFU sends the appropriate quality to each subscriber based on their bandwidth.

If this helped you understand the real architecture behind streaming and real-time video, drop a ❤️. Questions? Put them in the comments — especially if you're preparing for a system design interview.

Next: Low-latency live streaming architecture, how to build your own DRM license server, and debugging WebRTC connection failures.

webrtc #systemdesign #javascript #webdev #streaming #drm #livekit #architecture #interview

Web Vitals in React: The Complete Guide to Measuring and Optimizing Performance (2026)

Munna Thakur — Tue, 17 Mar 2026 17:42:48 +0000

Who is this for? React developers who want to understand why their app feels slow, what Google actually measures, and how to fix it — with real code examples and production-level techniques.

What Are Web Vitals?
The Three Core Metrics Explained
How to Measure Web Vitals in React
Why React CSR Apps Have Poor LCP
React Fiber: How It Improves Web Vitals Internally
Fixing LCP in Production
Fixing CLS in Production
Fixing INP in Production
Code Splitting: What It Is and Why Users Love It
Image Optimization: Why WebP Matters
The Production Debug Workflow
Interview-Ready Answers
Summary Cheatsheet

1. What Are Web Vitals?

Web Vitals are a set of performance metrics introduced by Google to measure the real user experience of a website — not just technical speed numbers, but how a site actually feels to someone using it.

Before Web Vitals, developers would measure things like "page load time" — a single number that didn't tell you much about whether the page was actually usable. Web Vitals break that down into three specific human experiences:

Can I see the main content quickly? → LCP
Does the page jump around unexpectedly? → CLS
Does the page respond when I click something? → INP

Why Should You Care?

Because Web Vitals directly affect:

Factor	Impact
Google SEO ranking	Google uses Core Web Vitals as a ranking signal
Bounce rate	A 1-second delay in load time increases bounce rate by ~32%
Conversion rate	Faster pages convert better — this is well-documented
User trust	A slow, jumpy page feels broken even if it technically works

💡 Simple Restaurant Analogy: Imagine a restaurant where the food takes 30 minutes (LCP), the table wobbles whenever a dish arrives (CLS), and the waiter takes 5 minutes to respond when you wave at them (INP). The food might be great, but the experience is terrible.

2. The Three Core Metrics Explained

LCP — Largest Contentful Paint

What it measures: How quickly the largest visible element on the page renders inside the viewport.

This is usually your hero image, a main heading, a product photo, or a large text block. Whatever takes up the most visual space above the fold.

Good:   < 2.5 seconds  ✅
Needs improvement: 2.5s – 4.0s  ⚠️
Poor:   > 4.0 seconds  ❌

What affects LCP:

Large, unoptimized images
Slow server response times
Render-blocking JavaScript (very common in React CSR)
Large CSS files that delay rendering

// ❌ This image has no dimensions and is not optimized
<img src="hero.jpg" />

// ✅ Better — explicit dimensions + WebP + preload
<link rel="preload" as="image" href="/hero.webp" />
<img src="/hero.webp" width="1200" height="600" alt="Hero" />

CLS — Cumulative Layout Shift

What it measures: How much the visible content unexpectedly moves around during the page lifecycle. It's a score (not a time), calculated by measuring the total area shifted multiplied by the distance shifted.

Good:   < 0.1   ✅
Needs improvement: 0.1 – 0.25  ⚠️
Poor:   > 0.25  ❌

You've experienced bad CLS when:

You're about to tap a button, and an ad loads above it, pushing the button down
Text reflows suddenly after a web font loads
An image appears without reserved space, pushing everything below it

// ❌ CLS problem: image has no dimensions
// Browser doesn't know how much space to reserve
<img src="/banner.jpg" />

// ✅ Fix: always specify width and height
// Browser reserves the exact space before the image loads
<img src="/banner.webp" width="800" height="400" alt="Banner" />

INP — Interaction to Next Paint

What it measures: The time from when a user interacts with the page (click, tap, keyboard input) to when the browser visually responds. This replaced FID (First Input Delay) in 2024.

Good:   < 200ms   ✅
Needs improvement: 200ms – 500ms  ⚠️
Poor:   > 500ms   ❌

Bad INP feels like: you click a button and nothing seems to happen for half a second. The page feels sluggish or unresponsive.

The main cause in React apps: Heavy JavaScript running on the main thread when a user interaction happens.

// ❌ Heavy synchronous work blocks the browser's ability to respond
function SearchResults({ query }) {
  const results = expensiveFilter(allData, query); // blocks main thread
  return <List data={results} />;
}

// ✅ Defer non-urgent work using useTransition
function SearchResults({ query }) {
  const [isPending, startTransition] = useTransition();
  const [results, setResults] = useState([]);

  const handleSearch = (value) => {
    startTransition(() => {
      // This update runs at lower priority — won't block user interaction
      setResults(expensiveFilter(allData, value));
    });
  };

  return (
    <>
      {isPending && <Spinner />}
      <List data={results} />
    </>
  );
}

3. How to Measure Web Vitals in React

There are three layers of measurement you should know: in-code, browser tools, and real-user monitoring.

Layer 1 — In-Code Measurement (Real User Data)

Install the official web-vitals package:

npm install web-vitals

In a Create React App project

CRA already gives you reportWebVitals.js. Just update your index.js:

// index.js
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import reportWebVitals from './reportWebVitals';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<App />);

// Pass console.log to see metrics in the browser console (dev only)
reportWebVitals(console.log);

Sample console output:

{name: 'LCP', value: 2100, rating: 'good', ...}
{name: 'CLS', value: 0.03, rating: 'good', ...}
{name: 'INP', value: 180, rating: 'good', ...}

In a Vite project (manual setup)

// main.jsx
import { getCLS, getLCP, getINP, getFCP, getTTFB } from 'web-vitals';

// Development: log to console
getCLS(console.log);
getLCP(console.log);
getINP(console.log);
getFCP(console.log);
getTTFB(console.log);

Production: Send to Your Analytics Server

Never just console.log in production. Send the data to your backend:

import { getCLS, getLCP, getINP } from 'web-vitals';

function sendToAnalytics(metric) {
  fetch('/api/vitals', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    // Use `sendBeacon` for reliability on page unload
    body: JSON.stringify({
      name: metric.name,
      value: metric.value,
      rating: metric.rating,  // 'good' | 'needs-improvement' | 'poor'
      id: metric.id,
      page: window.location.pathname,
    }),
  });
}

getCLS(sendToAnalytics);
getLCP(sendToAnalytics);
getINP(sendToAnalytics);

Layer 2 — Browser Dev Tools

Google Lighthouse (built into Chrome)

Right-click page → Inspect → Lighthouse tab → Analyze page load

This gives you a full report with scores, specific issues, and fix recommendations.

Chrome DevTools Performance Panel

Inspect → Performance tab → Click Record → Reload page → Stop recording

Look for:

Long Tasks (red blocks on the main thread)
LCP marker in the timeline
Layout Shift regions

PageSpeed Insights — tests your live URL with real Chrome data:

https://pagespeed.web.dev

Layer 3 — Production Monitoring Tools

Tool	What It Does
Vercel Analytics	Built-in Web Vitals from real users if you deploy on Vercel
Sentry	Performance monitoring + error tracking together
Datadog	Enterprise-level RUM (Real User Monitoring)
Google Search Console	Shows Core Web Vitals for your indexed pages

4. Why React CSR Apps Have Poor LCP

This is one of the most important concepts for any React developer to understand, and it comes up in senior interviews regularly.

The CSR Rendering Pipeline

A typical React app created with CRA or Vite (Client-Side Rendering) works like this:

User navigates to your site
        ↓
Browser downloads HTML from server
(The HTML is basically empty: <div id="root"></div>)
        ↓
Browser downloads your JavaScript bundle (main.js)
[This could be 500KB–2MB]
        ↓
Browser parses and executes the JavaScript
        ↓
React runs, creates the Virtual DOM
        ↓
ReactDOM commits to the real DOM
        ↓
Browser paints the screen
        ↓
LCP is measured HERE 📍

The problem is obvious once you see it: nothing can render until all that JavaScript downloads, parses, and runs. The user stares at a blank screen during all of that.

The SSR / Next.js Pipeline

User navigates to your site
        ↓
Server renders the complete HTML
(The HTML already contains your h1, images, content)
        ↓
Browser receives full HTML and paints immediately
        ↓
LCP is measured HERE 📍 (much earlier!)
        ↓
React "hydrates" the HTML in the background
(attaches event listeners, makes it interactive)

The Numbers in Practice

React CSR (typical):
  HTML download:    20ms
  JS bundle (1MB):  600ms
  JS parse/execute: 300ms
  React render:     150ms
  ─────────────────────
  LCP ≈ 1070ms+ (and that's on a fast connection)

Next.js SSR (same app):
  Server render:    100ms
  HTML download:    50ms
  Browser paint:    immediate
  ─────────────────────
  LCP ≈ 150ms

The Key Difference

	React CSR	Next.js SSR
Initial HTML	`<div id="root"></div>` (empty)	Full page content
Where rendering happens	Browser (client)	Server
LCP	Slow	Fast
SEO	Weak (crawlers see empty HTML)	Strong
Interactivity	Immediate after hydration	After hydration

⚠️ Important nuance: SSR doesn't automatically fix everything. If your server is slow, if you have large unoptimized images, or if your hydration bundle is massive, you can still have poor LCP even with SSR.

5. React Fiber: How It Improves Web Vitals Internally

React Fiber is React's internal rendering engine (introduced in React 16). Most developers use it every day without realizing it exists. Understanding it explains why useTransition and useDeferredValue work the way they do.

The Problem Fiber Solved

Before Fiber, React's rendering was synchronous and uninterruptible. When React started rendering a component tree, it couldn't stop until it was done — even if the user was trying to click a button.

Large state update triggered
        ↓
React starts rendering the full component tree
        ↓
Browser is blocked (can't respond to user input)
        ↓
React finishes rendering
        ↓
DOM updated
        ↓
Browser finally responds to the user's click

On large apps, this blocking period could be 500ms+. That's terrible INP.

How Fiber Fixed It: Incremental Rendering

Fiber breaks rendering work into small units called fibers (one per component). The scheduler can pause between units, check if something more urgent has arrived (like a user click), and handle that first.

Large state update triggered
        ↓
Fiber starts rendering: processes Navbar fiber
        ↓
Yields to browser: "anything urgent?"
        ↓
User click detected! → Handle click immediately
        ↓
Resume rendering: processes Sidebar fiber
        ↓
Yields to browser again
        ↓
Continue until done

This is why React feels responsive even during complex updates.

The Two Phases of Fiber Rendering

Phase 1 — Render Phase (Reconciliation)

React builds a new fiber tree and calculates what changed. This phase is:

Interruptible — can be paused and resumed
Async — can be spread across multiple frames
Side-effect free — no DOM changes yet

Phase 2 — Commit Phase

React applies the calculated changes to the actual DOM. This phase is:

Synchronous — cannot be interrupted
Fast — all calculations are already done
Where DOM mutations, layout effects, and paint happen

Priority Levels in Fiber's Scheduler

Fiber assigns priority to every update:

Priority	Example
Immediate	Error boundaries, forced sync renders
User Blocking	Text input, button clicks, direct interactions
Normal	Data fetches, state updates from effects
Low	Analytics, logging
Idle	Prefetching, precomputing

This is what powers useTransition:

// Without useTransition: typing + filtering compete for same priority
const [query, setQuery] = useState('');
const filtered = data.filter(item => item.includes(query));

// With useTransition: typing is User Blocking, filtering is Normal
// Typing ALWAYS wins — the input never freezes
const [query, setQuery] = useState('');
const [isPending, startTransition] = useTransition();
const [filtered, setFiltered] = useState(data);

const handleChange = (e) => {
  const value = e.target.value;
  setQuery(value); // High priority — updates input immediately

  startTransition(() => {
    setFiltered(data.filter(item => item.includes(value))); // Lower priority
  });
};

useDeferredValue — Fiber's Other Superpower

// Search input stays responsive even while results are computing
function SearchPage() {
  const [query, setQuery] = useState('');

  // This value "lags behind" intentionally — old results stay visible
  // while new results are being computed in the background
  const deferredQuery = useDeferredValue(query);

  return (
    <>
      <input value={query} onChange={e => setQuery(e.target.value)} />
      {/* Results use the deferred value — won't block the input */}
      <SearchResults query={deferredQuery} />
    </>
  );
}

Fiber's Direct Impact on Web Vitals

Metric	How Fiber Helps
INP	Priority scheduling prevents user interactions from being blocked by non-urgent rendering work
LCP	Concurrent features allow streaming SSR and progressive rendering
CLS	Predictable rendering phases reduce unexpected layout changes

6. Fixing LCP in Production

LCP problems in React apps almost always fall into one of three categories: large JavaScript bundles, unoptimized images, or missing server rendering.

Fix 1 — Analyze and Reduce Your Bundle Size

First, see the problem:

# Build the app first
npm run build

# Then analyze what's inside
npx source-map-explorer 'build/static/js/*.js'
# or
npx webpack-bundle-analyzer build/bundle-stats.json

Common culprits:

Importing entire libraries when you only need one function
Duplicate dependencies (two versions of the same package)
Libraries that should be code-split but aren't

// ❌ Imports the entire lodash library (70KB+)
import _ from 'lodash';
const result = _.debounce(fn, 300);

// ✅ Import only what you need (1KB)
import debounce from 'lodash/debounce';
const result = debounce(fn, 300);

// ✅ Even better: use lodash-es for tree shaking
import { debounce } from 'lodash-es';

Fix 2 — Preload Your Hero Image

<!-- In your public/index.html — load hero image before JS even parses -->
<link rel="preload" as="image" href="/hero.webp" />

This is one of the highest-impact single-line fixes for LCP. It tells the browser to start downloading the image as early as possible, instead of waiting to discover it while parsing your React components.

Fix 3 — Code Split Everything That Isn't Needed Immediately

import React, { Suspense, lazy } from 'react';

// These routes only load their JS when the user navigates to them
const Dashboard = lazy(() => import('./pages/Dashboard'));
const Settings = lazy(() => import('./pages/Settings'));
const Profile = lazy(() => import('./pages/Profile'));

function App() {
  return (
    <Router>
      <Suspense fallback={<PageSkeleton />}>
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/dashboard" element={<Dashboard />} />
          <Route path="/settings" element={<Settings />} />
          <Route path="/profile" element={<Profile />} />
        </Routes>
      </Suspense>
    </Router>
  );
}

Before code splitting: main.js = 2.1MB
After code splitting: main.js = 280KB + lazy chunks loaded on demand

Fix 4 — Move to SSR (The Nuclear Option for LCP)

If LCP is consistently poor and your app is content-heavy (blogs, e-commerce, landing pages), the most impactful fix is Server-Side Rendering.

# Migrate to Next.js
npx create-next-app@latest my-app

In Next.js, pages are server-rendered by default:

// pages/index.js — rendered on the server, HTML arrives ready to paint
export default function HomePage({ posts }) {
  return (
    <main>
      <h1>Latest Posts</h1>  {/* This is in the HTML before JS runs */}
      {posts.map(post => <PostCard key={post.id} post={post} />)}
    </main>
  );
}

export async function getServerSideProps() {
  const posts = await fetchPosts();
  return { props: { posts } };
}

7. Fixing CLS in Production

CLS is usually the most fixable metric once you know the rules.

Rule 1 — Always Set Image Dimensions

// ❌ Browser doesn't know the size, reserves 0px, causes shift when image loads
<img src="/product.webp" alt="Product" />

// ✅ Browser reserves exact space before image downloads
<img src="/product.webp" alt="Product" width="400" height="300" />

Or use the CSS aspect-ratio approach:

.image-container {
  aspect-ratio: 4 / 3;  /* Reserves the correct space */
  width: 100%;
}

.image-container img {
  width: 100%;
  height: 100%;
  object-fit: cover;
}

Rule 2 — Use Skeleton Screens for Dynamic Content

function ProductCard({ productId }) {
  const { data, isLoading } = useFetchProduct(productId);

  // ✅ Reserve the exact same space as the real content
  if (isLoading) {
    return (
      <div className="product-card skeleton" style={{ height: '320px' }}>
        <div className="skeleton-image" style={{ height: '200px' }} />
        <div className="skeleton-title" style={{ height: '20px', marginTop: '12px' }} />
        <div className="skeleton-price" style={{ height: '16px', marginTop: '8px' }} />
      </div>
    );
  }

  return (
    <div className="product-card" style={{ height: '320px' }}>
      <img src={data.image} width="400" height="200" alt={data.name} />
      <h2>{data.name}</h2>
      <p>{data.price}</p>
    </div>
  );
}

Rule 3 — Never Inject Content Above Existing Content

// ❌ Injecting a banner at the top after load pushes everything down
const [showBanner, setShowBanner] = useState(false);
useEffect(() => {
  setShowBanner(true); // This causes layout shift!
}, []);

// ✅ Reserve space for the banner from the start
const [bannerContent, setBannerContent] = useState(null);
useEffect(() => {
  setBannerContent('Free shipping on orders over $50!');
}, []);

return (
  // This div always exists — content slot is reserved, no shift
  <div style={{ minHeight: '40px' }}>
    {bannerContent && <Banner>{bannerContent}</Banner>}
  </div>
);

Rule 4 — Use `font-display: optional` for Web Fonts

@font-face {
  font-family: 'MyFont';
  src: url('/fonts/myfont.woff2') format('woff2');
  /* 'optional' uses fallback if font doesn't load quickly */
  /* prevents text from reflowing when the custom font loads */
  font-display: optional;
}

8. Fixing INP in Production

INP is the hardest metric to fix because it requires understanding what's happening on React's main thread during user interactions.

Fix 1 — Memoize Expensive Calculations

// ❌ Recalculates on every render, even when data hasn't changed
function Dashboard({ orders }) {
  const revenue = orders.reduce((sum, o) => sum + o.amount, 0);
  const topProducts = orders
    .sort((a, b) => b.amount - a.amount)
    .slice(0, 10);

  return <StatsDisplay revenue={revenue} topProducts={topProducts} />;
}

// ✅ Only recalculates when orders actually changes
function Dashboard({ orders }) {
  const revenue = useMemo(
    () => orders.reduce((sum, o) => sum + o.amount, 0),
    [orders]
  );

  const topProducts = useMemo(
    () => orders.sort((a, b) => b.amount - a.amount).slice(0, 10),
    [orders]
  );

  return <StatsDisplay revenue={revenue} topProducts={topProducts} />;
}

Fix 2 — Prevent Child Component Re-renders

// ❌ handleSubmit is recreated every render
// → CartItem sees a new prop → rerenders even when nothing changed
function Cart({ items }) {
  const handleRemove = (id) => removeItem(id);
  return items.map(item => <CartItem key={item.id} onRemove={handleRemove} />);
}

// ✅ Stable function reference → CartItem only rerenders when items change
const CartItem = React.memo(function CartItem({ item, onRemove }) {
  return (
    <div>
      <span>{item.name}</span>
      <button onClick={() => onRemove(item.id)}>Remove</button>
    </div>
  );
});

function Cart({ items }) {
  const handleRemove = useCallback((id) => removeItem(id), []);
  return items.map(item => (
    <CartItem key={item.id} item={item} onRemove={handleRemove} />
  ));
}

Fix 3 — Virtualize Long Lists

Rendering 10,000 list items to the DOM is always going to hurt INP. With virtualization, only the ~15 items currently visible in the viewport are rendered as real DOM nodes.

import { FixedSizeList as List } from 'react-window';

// ❌ Renders all 10,000 rows to the DOM at once
function ProductList({ products }) {
  return (
    <ul>
      {products.map(p => <ProductRow key={p.id} product={p} />)}
    </ul>
  );
}

// ✅ Only renders ~15 visible rows at any time
function ProductList({ products }) {
  const Row = ({ index, style }) => (
    <div style={style}>
      <ProductRow product={products[index]} />
    </div>
  );

  return (
    <List
      height={600}        // Height of the scrollable container
      itemCount={products.length}  // Total number of items
      itemSize={72}       // Height of each row in pixels
      width="100%"
    >
      {Row}
    </List>
  );
}

Fix 4 — Debounce Expensive Input Handlers

import { useMemo } from 'react';
import debounce from 'lodash/debounce';

function SearchBox({ onSearch }) {
  // ❌ Fires search API on every single keystroke
  const handleChange = (e) => onSearch(e.target.value);

  // ✅ Waits 300ms after user stops typing before firing
  const handleChange = useMemo(
    () => debounce((e) => onSearch(e.target.value), 300),
    [onSearch]
  );

  return <input onChange={handleChange} placeholder="Search..." />;
}

9. Code Splitting: What It Is and Why Users Love It

Without code splitting, your entire app ships as one JavaScript file. Even if a user only visits the homepage, they download the code for the dashboard, settings, profile pages, and everything else.

Code splitting fixes this by breaking your bundle into route-level (or component-level) chunks that only load when needed.

Before vs After

Without Code Splitting:
  main.js = 2.3MB
  User visits homepage → downloads 2.3MB → 3.2s load time

With Code Splitting:
  main.js = 280KB     (homepage + shared code)
  dashboard.js = 450KB (only loads when user goes to /dashboard)
  settings.js = 180KB  (only loads when user goes to /settings)

  User visits homepage → downloads 280KB → 0.8s load time ⚡

How It Works Internally

When Webpack (or Vite's Rollup) sees a dynamic import(), it automatically creates a separate chunk file at build time:

// Static import — always bundled into main.js
import Dashboard from './Dashboard';

// Dynamic import — creates dashboard.chunk.js as a separate file
const Dashboard = lazy(() => import('./Dashboard'));

At runtime, when React first needs to render <Dashboard />, it triggers the dynamic import, which makes an HTTP request for dashboard.chunk.js, downloads it, and renders the component.

Prefetching Chunks the User Will Likely Need

// Load the chunk immediately (user is about to need it)
const Dashboard = lazy(() => import(/* webpackPreload: true */ './Dashboard'));

// Load the chunk in the background during idle time (user might need it)
const Settings = lazy(() => import(/* webpackPrefetch: true */ './Settings'));

React.lazy + Suspense: Full Pattern

import React, { Suspense, lazy } from 'react';
import { Routes, Route } from 'react-router-dom';

// Route-level code splitting
const Home = lazy(() => import('./pages/Home'));
const Dashboard = lazy(() => import('./pages/Dashboard'));
const UserProfile = lazy(() => import('./pages/UserProfile'));

// A reusable loading fallback that matches your page layout
function PageLoader() {
  return (
    <div style={{ padding: '40px', textAlign: 'center' }}>
      <div className="spinner" aria-label="Loading page..." />
    </div>
  );
}

function App() {
  return (
    <Suspense fallback={<PageLoader />}>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/dashboard" element={<Dashboard />} />
        <Route path="/profile/:id" element={<UserProfile />} />
      </Routes>
    </Suspense>
  );
}

10. Image Optimization: Why WebP Matters

Images are often the largest resource on a page and the single biggest contributor to poor LCP. Choosing the right format makes a massive difference.

Format Comparison

Format	Size	Transparency	Animation	Best For
JPEG	Large	❌	❌	Photos (old standard)
PNG	Very large	✅	❌	Logos, screenshots
GIF	Huge	✅	✅	(Avoid)
WebP	Small	✅	✅	Everything modern
AVIF	Smallest	✅	✅	Next-gen (less browser support)

WebP images are typically 25–70% smaller than JPEG/PNG at the same visual quality.

The Right Way to Use WebP in React

// ✅ Use <picture> for progressive enhancement
// Modern browsers use WebP, older browsers fall back to JPEG
function HeroImage() {
  return (
    <picture>
      <source srcSet="/hero.avif" type="image/avif" />
      <source srcSet="/hero.webp" type="image/webp" />
      <img
        src="/hero.jpg"
        alt="Hero banner"
        width="1200"
        height="600"
        loading="eager"  // Hero image should load immediately
      />
    </picture>
  );
}

// For below-the-fold images, use lazy loading
function ProductImage({ src, alt }) {
  return (
    <picture>
      <source srcSet={src.replace('.jpg', '.webp')} type="image/webp" />
      <img
        src={src}
        alt={alt}
        width="400"
        height="300"
        loading="lazy"    // Browser defers loading until near viewport
        decoding="async"  // Doesn't block main thread while decoding
      />
    </picture>
  );
}

Preloading the Hero Image

The hero image is almost always your LCP element. Tell the browser to fetch it as early as possible:

<!-- public/index.html — runs before any JavaScript -->
<link rel="preload" as="image" href="/hero.webp" type="image/webp" />

This is often a 500ms+ improvement for LCP because the image starts downloading while the HTML is still being parsed, before React even runs.

11. The Production Debug Workflow

When someone reports that the app "feels slow" in production, here's the systematic process to find and fix the problem:

Step 1 — Get Real Numbers

# Test against production URL (or staging)
# Use PageSpeed Insights: https://pagespeed.web.dev

Don't debug against localhost — your machine is much faster than real users' devices. Test on Slow 4G throttling in Chrome DevTools to simulate reality.

Step 2 — Identify Which Metric is Failing

Failing Metric	Likely Cause	Section to Read
LCP > 2.5s	Large JS bundle, slow images, CSR	Section 6
CLS > 0.1	Missing image dimensions, dynamic injection	Section 7
INP > 200ms	Heavy JS, too many re-renders	Section 8

Step 3 — Profile the Specific Problem

For LCP (bundle size issue):

npm run build
npx source-map-explorer 'build/static/js/*.js'

Look for: unexpectedly large libraries, duplicate code, pages that don't need to be in the main bundle.

For INP (interaction lag):

Chrome DevTools → Performance tab → Record
→ Click the slow button
→ Stop recording
→ Look for Long Tasks (red blocks) on the Main thread
→ Click the task to see which functions caused it

Step 4 — Apply Targeted Fixes

// Common fixes by category:

// 1. Bundle size → code split routes
const HeavyPage = lazy(() => import('./HeavyPage'));

// 2. Re-renders → memoize components and callbacks  
const MyComponent = React.memo(Component);
const handleClick = useCallback(() => { /* ... */ }, [deps]);

// 3. Expensive calculations → memoize values
const result = useMemo(() => expensiveCalculation(data), [data]);

// 4. Long lists → virtualize
import { FixedSizeList } from 'react-window';

// 5. Slow interactions → defer non-urgent work
startTransition(() => setHeavyState(newValue));

Step 5 — Verify the Fix

After applying a fix, measure again with the same tool and compare. Don't guess — measure.

12. Interview-Ready Answers

"What are Core Web Vitals?"

Core Web Vitals are three Google performance metrics that measure user experience: LCP (how quickly the largest content loads), CLS (how much the layout shifts unexpectedly), and INP (how fast the UI responds to user interactions). They affect both user experience and Google search rankings.

"Why does a React CSR app have poor LCP?"

In a Client-Side Rendered React app, the initial HTML is essentially empty — just a <div id="root">. The browser must download, parse, and execute the entire JavaScript bundle before React can render anything visible. This means LCP is delayed by the entire JS load + execution time. In contrast, SSR frameworks like Next.js render HTML on the server and send complete content to the browser, so the largest content element is visible immediately.

"What is React Fiber and how does it improve performance?"

React Fiber is React's internal rendering engine that breaks rendering work into small interruptible units. Unlike the old synchronous renderer, Fiber can pause rendering between component units, check if something more urgent (like a user click) needs to happen, handle that first, and then resume. It also introduces a scheduler with priority levels, which powers concurrent features like useTransition that defer non-urgent updates so they don't block user interactions. This directly improves INP.

"What is code splitting and when should you use it?"

Code splitting breaks a large JavaScript bundle into smaller chunks that load on demand. It's implemented in React using React.lazy() with dynamic import(). You should use it for route-level splitting (each page loads its own JS), feature-level splitting (loading heavy components like charts or editors only when needed), and any component that's not visible on initial load. The benefit is a much smaller initial bundle, which directly improves LCP and Time to Interactive.

"How do you fix CLS in a React app?"

CLS is fixed by ensuring space is always reserved for content before it loads. The main techniques are: always specifying width and height on images, using skeleton screens that match the dimensions of the real content, never injecting content above existing content after page load, and using font-display: optional or swap for web fonts to prevent text reflow.

13. Summary Cheatsheet

Metric Quick Reference

LCP (Largest Contentful Paint)
  Target:  < 2.5s
  Fix with: Code splitting, image preloading, WebP images, SSR

CLS (Cumulative Layout Shift)
  Target:  < 0.1
  Fix with: Image dimensions, skeleton screens, reserved space

INP (Interaction to Next Paint)
  Target:  < 200ms
  Fix with: useTransition, useMemo, React.memo, virtualization

The Complete Optimization Toolkit

// 1. Measure
import { getCLS, getLCP, getINP } from 'web-vitals';

// 2. Code Split Routes
const Page = lazy(() => import('./Page'));

// 3. Memoize Components
const Component = React.memo(MyComponent);

// 4. Memoize Values
const value = useMemo(() => compute(data), [data]);

// 5. Stable Callbacks
const fn = useCallback(() => doSomething(), []);

// 6. Defer Non-Urgent Updates
startTransition(() => setHeavyState(newValue));

// 7. Defer Input-Linked State
const deferred = useDeferredValue(searchQuery);

// 8. Virtualize Lists
import { FixedSizeList } from 'react-window';

// 9. Optimize Images
<img src="/image.webp" width="800" height="400" loading="lazy" />

// 10. Preload Hero
<link rel="preload" as="image" href="/hero.webp" />

Decision Guide

App feels slow to load?
  → Check LCP → probably bundle size or images
  → Add code splitting and use WebP + preload

Page elements jump around?
  → Check CLS → probably missing image dimensions
  → Add width/height to all images, use skeleton screens

Clicks feel delayed or unresponsive?
  → Check INP → probably heavy JS on main thread
  → Add useTransition, memoize components, virtualize lists

App is content-heavy (blog, e-commerce)?
  → Consider migrating to Next.js for SSR
  → LCP improvement is often dramatic

react #webperformance #javascript #corevitals #frontend #webdev #nextjs #optimization

Webpack vs Vite: The Complete Guide Every Frontend Dev Must Read (2026)

Munna Thakur — Tue, 17 Mar 2026 17:03:10 +0000

Before we dive in — this article explains everything from scratch. Why bundlers exist, how they work internally, and which one you should pick today. Code examples + interview-ready answers included. 🔥

Why Do We Need Build Tools?
JSX → Browser: The Full Pipeline
Webpack: How It Works Internally
Webpack Config: Every Option Explained
Key Webpack Features
Vite: Why It Feels So Fast
ESM + Dependency Pre-Bundling
Vite Config Explained
Webpack vs Vite: Full Comparison
When to Use What?
Interview Answers
Summary

1. Why Do We Need Build Tools?

Imagine you built a React app. You have:

index.js, App.jsx, Header.jsx — 100+ JS files
styles.css, variables.css — 20+ CSS files
Images, fonts, SVGs

The problem? The browser would need to load each file one by one. That's 100+ separate network requests. Super slow ❌

On top of that, the browser doesn't understand:

JSX — <h1>Hello</h1> is not valid JavaScript
TypeScript — browsers can't run .ts files
import/require — Node.js module system ≠ browser

So build tools solve three core problems:

Problem	Solution
Too many network requests	Bundle all files into 1-2 optimized files
Browser can't understand JSX/TS	Transform (transpile) them to plain JS first
Node module system ≠ browser	Convert `require()` to ES Module format

💡 Simple Analogy: You wrote 100 letters. Instead of mailing them one by one (slow, expensive), a build tool packs them all into one envelope. The post office (browser) delivers one package instead of 100.

2. JSX → Browser: The Full Pipeline

When you write React code, it does not run directly in the browser. It goes through a multi-step transformation. Here's exactly what happens:

Your JSX Code
     ↓
Babel (transforms JSX → JavaScript)
     ↓
React.createElement() (creates Virtual DOM objects)
     ↓
Virtual DOM (a plain JS object tree)
     ↓
Reconciliation / Diffing (React compares old vs new)
     ↓
ReactDOM (applies only the changes to Real DOM)
     ↓
Browser renders the UI on screen 🎉

Let's break each step down.

Step 1 — Babel Transforms JSX

Babel is a transpiler. It reads your JSX and converts it to standard JavaScript that any browser can run.

// What YOU write (JSX)
function App() {
  return <h1 className="title">Hello World</h1>;
}

// What BABEL produces (plain JS)
function App() {
  return React.createElement(
    "h1",
    { className: "title" },
    "Hello World"
  );
}

🔑 Why Babel? Because browsers understand JavaScript — not JSX. Babel is the translator between "developer-friendly syntax" and "browser-safe code."

Since React 17, there's a new JSX transform that's even cleaner:

// React 17+ (auto-imports from react/jsx-runtime)
import { jsx as _jsx } from "react/jsx-runtime";

function App() {
  return _jsx("h1", { className: "title", children: "Hello World" });
}

Step 2 — Virtual DOM Object

React.createElement() doesn't touch the real DOM at all. It returns a plain JavaScript object — a description of what should be on screen:

// This is the Virtual DOM object React creates
{
  type: "h1",
  props: {
    className: "title",
    children: "Hello World"
  },
  key: null,
  ref: null,
  $$typeof: Symbol(react.element)  // protects against XSS attacks
}

Step 3 — Diffing Algorithm (Reconciliation)

When your state changes, React creates a new Virtual DOM tree and compares it to the old one. This process is called reconciliation (powered by React Fiber internally).

React finds the minimum number of changes needed and applies only those changes to the real DOM.

State changes → New Virtual DOM created
                        ↓
          Compare with Old Virtual DOM
                        ↓
        Find only what changed (diffing)
                        ↓
        Update ONLY those real DOM nodes

💡 Why not update the real DOM directly? Real DOM operations are expensive — they trigger layout recalculations and screen repaints. Comparing two JS objects in memory is near-instant. React batches all changes into one DOM operation.

3. Webpack: How It Works Internally

Webpack is a static module bundler. Before your app runs in the browser, Webpack reads every single file, builds a complete map of dependencies, and packages everything into optimized output.

Here's the internal flow:

Entry Point (src/index.js)
         ↓
Scan all imports → Build Dependency Graph
         ↓
Apply Loaders (transform each file type)
         ↓
Apply Plugins (extra optimizations)
         ↓
Output → bundle.js (browser-ready file)

How Webpack builds the dependency graph

// index.js imports App
import App from "./App";
import "./styles.css";

// App.jsx imports Button
import Button from "./Button";
import axios from "axios";

Webpack follows every import and require() like a detective — it maps out the entire relationship tree of your app. This graph tells it what to include in the final bundle and in what order.

Loaders: Teaching Webpack to Handle Non-JS Files

By default, Webpack only understands JavaScript. Loaders are plugins that teach it how to handle other file types.

Loader	What It Does
`babel-loader`	Converts JSX and modern JS (ES6+) → ES5
`css-loader`	Makes Webpack understand `@import` and `url()` in CSS
`style-loader`	Injects CSS into the DOM via `<style>` tags
`file-loader`	Copies images, fonts, and other assets to the output folder
`ts-loader`	Converts TypeScript to JavaScript
`sass-loader`	Converts SCSS/SASS to CSS

Plugins: Extra Power Over the Entire Bundle

Loaders work on individual files. Plugins work on the entire compilation — they can hook into Webpack's lifecycle events.

Plugin	What It Does
`HtmlWebpackPlugin`	Auto-generates `index.html` and injects the bundle
`MiniCssExtractPlugin`	Extracts CSS into separate files (instead of inline)
`DefinePlugin`	Injects environment variables (`process.env.NODE_ENV`)
`BundleAnalyzerPlugin`	Visual map of your bundle size

4. Webpack Config: Every Option Explained

Here's a real-world, production-ready Webpack config with comments explaining every single option:

// webpack.config.js
const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = {
  // ─── ENTRY ─────────────────────────────────────────────
  // Where Webpack starts building the dependency graph.
  // Everything starts from this file.
  entry: './src/index.js',

  // ─── OUTPUT ────────────────────────────────────────────
  // Where to write the final bundles.
  output: {
    path: path.resolve(__dirname, 'dist'),

    // [contenthash] changes the filename when file content changes.
    // This forces browsers to download the new file (cache busting).
    filename: '[name].[contenthash].js',

    // Delete old files in /dist before each new build
    clean: true,
  },

  // ─── MODULE RULES (LOADERS) ────────────────────────────
  // Tell Webpack how to handle each file type it encounters.
  module: {
    rules: [
      {
        // Match any .js or .jsx file
        test: /\.(js|jsx)$/,

        // Don't transform node_modules — they're already plain JS
        exclude: /node_modules/,

        use: {
          loader: 'babel-loader',
          options: {
            // preset-react: understands JSX
            // preset-env: converts modern JS to browser-compatible JS
            presets: ['@babel/preset-react', '@babel/preset-env'],
          },
        },
      },
      {
        test: /\.css$/,
        use: [
          // Step 2: Extract to a real .css file
          MiniCssExtractPlugin.loader,
          // Step 1: Understand CSS @import and url()
          'css-loader',
        ],
        // Note: loaders run RIGHT TO LEFT — css-loader runs first!
      },
      {
        // Handle images, fonts, etc.
        test: /\.(png|jpg|gif|svg|woff2?)$/,
        // 'asset/resource' copies the file to /dist and gives it a hash name
        type: 'asset/resource',
      },
    ],
  },

  // ─── PLUGINS ───────────────────────────────────────────
  plugins: [
    // Auto-create index.html with the correct <script> tag injected
    new HtmlWebpackPlugin({
      template: './public/index.html',
    }),
    // Extract all CSS into a separate file (better performance than inline)
    new MiniCssExtractPlugin({
      filename: '[name].[contenthash].css',
    }),
  ],

  // ─── OPTIMIZATION ──────────────────────────────────────
  optimization: {
    // Code Splitting: separate vendor libraries from app code.
    // React/lodash don't change often → browser caches them separately.
    splitChunks: {
      chunks: 'all',
    },
    // Tree Shaking: remove unused exports from the final bundle
    usedExports: true,
  },

  // ─── DEV SERVER ────────────────────────────────────────
  devServer: {
    port: 3000,
    // Hot Module Replacement: update changed modules without full page reload
    hot: true,
    // Needed for React Router — serve index.html for all routes
    historyApiFallback: true,
  },

  // ─── RESOLVE ───────────────────────────────────────────
  resolve: {
    // So you can write: import App from './App' (no .jsx extension needed)
    extensions: ['.js', '.jsx', '.ts', '.tsx'],
    // Aliases: import Button from '@components/Button'
    alias: {
      '@components': path.resolve(__dirname, 'src/components'),
    },
  },
};

5. Key Webpack Features

🌳 Tree Shaking — Remove Dead Code

Webpack scans your ES Module imports/exports and removes any code that is never actually used anywhere. This can cut bundle size dramatically.

// utils.js
export const add = (a, b) => a + b;
export const multiply = (a, b) => a * b;
export const divide = (a, b) => a / b;   // ← nobody imports this

// app.js — only uses 2 functions
import { add, multiply } from './utils';

// After tree shaking: 'divide' is completely removed from bundle ✅

⚠️ Tree shaking only works with ES Modules (import/export). It does not work with CommonJS (require/module.exports).

✂️ Code Splitting — Split Bundle into Chunks

Instead of one huge bundle.js, code splitting creates multiple smaller files:

// Dynamic import — React lazy loading
const Dashboard = React.lazy(() => import('./Dashboard'));

// Webpack automatically creates a separate chunk for Dashboard.
// It's only downloaded when the user navigates to that page.
// Result: faster initial load time ⚡

With splitChunks, Webpack also separates vendor code:

bundle.js          → Your app code (changes often)
vendors~main.js    → React, lodash, etc. (rarely changes, browser caches it)

🔥 Hot Module Replacement (HMR)

When you save a file in development, HMR updates only that module in the browser — no full page reload, no lost state.

You save Button.jsx
        ↓
Webpack recompiles only Button.jsx
        ↓
Browser swaps out the old module for the new one
        ↓
Page updates instantly, React state stays intact ✅

#️⃣ Content Hash — Cache Busting

filename: '[name].[contenthash].js'
// Produces: main.a3f1bc29.js

If you change your code, the hash changes → browser downloads the new file.
If nothing changed, hash stays the same → browser uses its cache (no download needed).

6. Vite: Why It Feels So Fast

Vite's core philosophy is different from Webpack in a fundamental way:

Webpack bundles everything first, then serves it.
Vite serves files directly, and bundles nothing in development.

The Key Insight: Native ES Modules

Modern browsers (Chrome, Firefox, Safari, Edge) natively support ES Modules. When you write:

<script type="module" src="/src/main.jsx"></script>

The browser can handle import statements on its own! It requests files on-demand as it parses them. Vite takes advantage of this completely.

Vite Dev Mode — Step by Step

Step 1 — npm run dev

Vite starts a dev server in milliseconds. Why? Because it has nothing to bundle. It just starts listening for HTTP requests.

Webpack takes 10–30 seconds here because it bundles everything first.

Step 2 — Browser loads the app

<!-- Vite serves this HTML to the browser -->
<script type="module" src="/src/main.jsx"></script>

The browser sees type="module" and starts resolving imports natively.

Step 3 — On-demand file transformation

When the browser requests /src/App.jsx, Vite:

Reads the file
Transforms it (JSX → JS) using esbuild (written in Go — extremely fast)
Returns the plain JS to the browser
Caches the result

Only the files that are actually requested get transformed. If you have 500 components but only visit the homepage, only the homepage files get processed.

Step 4 — HMR is surgical

When you save a file, Vite:

Invalidates only that file's cache
Sends a WebSocket message to the browser
Browser swaps out only that module

The entire dependency graph does not need to be re-evaluated. This is why Vite HMR feels instant even in large apps.

7. ESM + Dependency Pre-Bundling

Here's a problem Vite has to solve first.

The Problem

Libraries like React, lodash, and date-fns are written in CommonJS format. Browsers can't understand CommonJS. Also, some libraries have hundreds of sub-modules — lodash has ~600 internal files. Loading 600 files over the network is slow even with HTTP/2.

The Solution: esbuild Pre-Bundling

The first time you run vite dev, Vite automatically:

Scans your code for all bare module imports (import React from 'react')
Bundles those dependencies using esbuild (extremely fast — written in Go)
Converts them to ESM format that browsers can use
Caches them in node_modules/.vite/

// Your source code
import React from 'react';
import { debounce } from 'lodash';

// What Vite rewrites it to (browser-compatible path)
import React from '/node_modules/.vite/deps/react.js';
import { debounce } from '/node_modules/.vite/deps/lodash.js';

The pre-bundled files are cached. On subsequent server starts, Vite checks if dependencies changed — if not, it skips pre-bundling entirely.

💡 Why esbuild? esbuild is written in Go and runs natively on your machine. It is 10–100x faster than JavaScript-based tools like Babel. Pre-bundling React takes ~3ms with esbuild vs ~200ms with Babel.

Production Mode: Rollup Under the Hood

In production (npm run build), Vite uses Rollup as its bundler:

Your code
    ↓
Rollup bundles everything
    ↓
Tree shaking (removes unused code)
    ↓
Code splitting (vendor + app chunks)
    ↓
Minification
    ↓
Optimized output in /dist ✅

Why Rollup and not esbuild for production? Rollup has more mature code-splitting and tree-shaking — it produces smaller, better-optimized output for libraries and apps.

8. Vite Config Explained

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  // ─── PLUGINS ─────────────────────────────────────────
  // @vitejs/plugin-react handles:
  // - JSX transformation
  // - Fast Refresh (HMR for React components with state preservation)
  plugins: [react()],

  // ─── RESOLVE ─────────────────────────────────────────
  resolve: {
    // Path aliases — import Button from '@/components/Button'
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },

  // ─── DEV SERVER ──────────────────────────────────────
  server: {
    port: 5173,
    // Automatically open browser when server starts
    open: true,
    // Proxy API calls to avoid CORS issues in development
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
      },
    },
  },

  // ─── BUILD ───────────────────────────────────────────
  build: {
    // Output directory
    outDir: 'dist',
    // Generate source maps for debugging production errors
    sourcemap: true,
    // Customize Rollup options for advanced code splitting
    rollupOptions: {
      output: {
        manualChunks: {
          // Put React in its own chunk — cached separately
          react: ['react', 'react-dom'],
          // Put router in its own chunk
          router: ['react-router-dom'],
        },
      },
    },
  },

  // ─── OPTIMIZATION ────────────────────────────────────
  optimizeDeps: {
    // Force include dependencies that Vite might miss during scan
    include: ['lodash-es'],
  },
});

9. Webpack vs Vite: Full Comparison

Dev Server Startup Speed

Webpack (medium app):   ████████████████████░░░░ ~15–30 seconds
Vite    (medium app):   █░░░░░░░░░░░░░░░░░░░░░░░ < 1 second

Webpack bundles everything before serving. Vite starts immediately and processes on-demand.

HMR Speed

Webpack: rebuild affected modules + dependents → ~500ms–2s
Vite:    invalidate 1 file + browser swap       → ~50ms

Comparison Table

Feature	Webpack	Vite
Dev startup	Slow (bundles everything first)	Instant (no bundling in dev)
HMR speed	Medium (module graph re-evaluation)	Near-instant (1 file update)
Config complexity	High (verbose, many options)	Low (sensible defaults)
Browser support	Excellent (supports IE11 with config)	Modern browsers only (ES Modules required)
Production bundler	Webpack itself	Rollup
Tree shaking	✅ Yes	✅ Yes
Code splitting	✅ Yes	✅ Yes
Legacy project support	✅ Excellent	⚠️ Limited
Ecosystem/plugins	🏆 Massive (years of plugins)	Growing fast
CJS support	✅ Native	⚠️ Via pre-bundling
TypeScript	Via ts-loader	Built-in ✅
CSS Modules	Via loaders	Built-in ✅
Enterprise usage	🏢 Very common	📈 Rapidly growing

Bundle Size (Production)

Both Webpack and Vite produce similarly optimized production bundles. The real difference is developer experience, not production output.

10. When to Use What?

✅ Use Vite When...

Starting a new project from scratch
You want fast dev startup and instant HMR
Your team uses modern browsers (no IE11)
Tech stack: React, Vue, Svelte, or vanilla JS
You want less config boilerplate

# Start a new React project with Vite (recommended in 2026)
npm create vite@latest my-app -- --template react
cd my-app
npm install
npm run dev

✅ Use Webpack When...

Working on a legacy project that already uses Webpack
You need IE11 or old browser support
Your build requires highly custom configuration
Using Create React App (it uses Webpack under the hood)
Large enterprise codebase with complex build requirements

⚡ The 2026 Reality

Tool	Status
Vite	Default choice for new projects ✅
Webpack	Still widely used, especially legacy ✅
Create React App	Deprecated (not maintained) ❌
Next.js	Uses Turbopack (Webpack replacement, Rust-based)
Remix	Uses Vite by default

💡 Short answer: If you're starting fresh today — use Vite. If you're maintaining an existing project — stay on Webpack unless you have time to migrate.

11. Interview-Ready Answers

Q: "What is Webpack?"

Webpack is a static module bundler for JavaScript applications. It builds a dependency graph of your entire codebase, transforms files using loaders (like babel-loader for JSX), optimizes output using plugins, and packages everything into browser-ready bundles. It enables features like tree shaking, code splitting, and Hot Module Replacement.

Q: "What is Vite and why is it faster than Webpack?"

Vite is a modern build tool that uses native ES Modules in development instead of bundling. Unlike Webpack, which bundles your entire app before starting the dev server, Vite starts instantly and transforms files on-demand when the browser requests them. It uses esbuild (written in Go) for fast JSX transformations and pre-bundles only node_modules. In production, it uses Rollup for optimized output.

Q: "What is tree shaking?"

Tree shaking is a dead code elimination technique. When using ES Modules, bundlers can statically analyze which exports are actually imported somewhere in your code. Any exports that are never used are removed from the final bundle, reducing file size. It only works with ES Modules (import/export), not CommonJS (require).

Q: "What are loaders in Webpack?"

Loaders are transformers that teach Webpack how to handle non-JavaScript files. By default, Webpack only understands .js files. Loaders like babel-loader convert JSX to JavaScript, css-loader processes CSS files, and file-loader copies images and fonts. They are applied per-file, defined using regex patterns in the rules array of webpack.config.js.

Q: "What is the difference between Loaders and Plugins in Webpack?"

Loaders work on individual files — they transform one file type into another (e.g., JSX → JS). Plugins work on the entire compilation — they can hook into Webpack's lifecycle events and modify the output bundle, generate files, inject environment variables, etc.

Q: "What is HMR (Hot Module Replacement)?"

HMR is a development feature that updates only the changed module in the browser without a full page reload. When you save a file, the bundler sends the new module to the browser via WebSocket, and the browser swaps it in-place while preserving application state. Vite's HMR is significantly faster than Webpack's because it doesn't re-evaluate the entire dependency graph on each change.

12. Summary

Here's the complete mental model in one place:

YOUR CODE (JSX, CSS, images)
         ↓
BUILD TOOL (Webpack or Vite)
         ↓
  ┌──────────────────────────────────┐
  │  Transform JSX → JS (Babel/esbuild)
  │  Bundle all modules together     
  │  Tree shake unused code          
  │  Code split into chunks          
  │  Optimize + minify               
  └──────────────────────────────────┘
         ↓
BROWSER-READY FILES (bundle.js, styles.css)
         ↓
BROWSER runs the code
         ↓
React creates Virtual DOM
         ↓
Diffing finds what changed
         ↓
ReactDOM updates the Real DOM
         ↓
USER SEES THE UI 🎉

Quick Decision Guide

New project in 2026?        → Vite ✅
Legacy codebase?            → Stay on Webpack ✅
Need IE11 support?          → Webpack ✅
Fast dev experience?        → Vite ✅
Maximum plugin ecosystem?   → Webpack ✅
Interview knowledge needed? → Learn BOTH ✅

Resources to Go Deeper

If this helped you, drop a ❤️ and share it with someone learning frontend. Questions? Drop them in the comments — I read every one.

webpack #vite #react #javascript #webdev #frontend #bundler #beginners

Socket.IO Explained: Why It Exists, How It Works Internally, and How It Scales to Millions

Munna Thakur — Sat, 14 Mar 2026 18:16:44 +0000

You've probably used or heard of Socket.IO. Most tutorials just show you socket.emit() and socket.on() and call it a day.

But if you actually want to understand what's happening under the hood — why Socket.IO exists, why it's more reliable than raw WebSockets, and how apps like WhatsApp handle millions of live connections — this post is for you.

Let's go through the whole thing from the beginning.

The Problem That Started All of This

Normal web apps work on HTTP. You send a request, server sends back a response, connection closes. That's it.

But some apps need the server to push data to the client at any time:

Chat apps
Live notifications
Live sports scores
Multiplayer games
Real-time dashboards

HTTP alone can't do this well. So developers got creative.

What People Did Before WebSockets

Before WebSockets became standard, real-time was painful. Here's what developers actually used:

HTTP Polling — Client asks the server every few seconds: "Any new data?"

setInterval(() => {
  fetch('/messages').then(res => res.json()).then(console.log)
}, 5000)

Works, but wasteful. 10,000 users = 10,000 requests every 5 seconds hitting your server constantly.

Long Polling — Client sends a request, server holds it open until there's new data, then responds. Client immediately sends another request.

Client ──────→ request
Server ─────── waiting...
Server ──────→ here's your data
Client ──────→ new request

Better than polling, but still HTTP overhead on every cycle. Gmail and early Facebook chat used this.

Server-Sent Events (SSE) — Server pushes data to client as a stream. One-way only though. Client can't send back easily.

Comet — A collection of hacks from the 2000s (hidden iframes, streaming, long polling combined). Gmail used it. It was messy.

Then in 2011, WebSocket was standardized in HTML5 and changed everything.

WebSocket: The Real Foundation

WebSocket gives you a persistent, two-way connection between browser and server.

Normal HTTP:
Client → request → Server → response → connection closed

WebSocket:
Client ←————————— persistent connection —————————→ Server
       ←— data anytime —→ ←— data anytime —→

One connection stays open. Server can push data whenever it wants. Client can send whenever it wants. No repeated handshakes.

This is what powers WhatsApp Web, Slack, Discord, live trading platforms, and multiplayer games today.

So Why Does Socket.IO Exist?

Raw WebSocket is powerful, but it has rough edges:

Some corporate firewalls and proxies block WebSocket connections
Older browsers don't support it
If the connection drops, you have to handle reconnection yourself
There's no built-in concept of rooms, events, or broadcasting

Socket.IO is a library built on top of WebSocket that handles all of this for you.

Raw WebSocket:

const ws = new WebSocket('ws://localhost:3000')
ws.onmessage = (event) => console.log(event.data)
ws.send('Hello')

Socket.IO:

import { io } from 'socket.io-client'
const socket = io('http://localhost:3000')

socket.on('newMessage', (data) => console.log(data))
socket.emit('newMessage', 'Hello')

Socket.IO gives you named events, rooms, automatic reconnection, and fallback transport — all built in.

How Socket.IO Actually Works Internally

This is the part most developers skip. Socket.IO has an internal engine called Engine.IO, and connection happens in 4 phases.

Phase 1 — HTTP Handshake

When you call io('http://localhost:5000'), Socket.IO does NOT open a WebSocket immediately. It starts with a plain HTTP request:

GET /socket.io/?EIO=4&transport=polling

Server responds with session info:

{
  "sid": "abc123",
  "upgrades": ["websocket"],
  "pingInterval": 25000,
  "pingTimeout": 20000
}

A session ID is established. Server confirms WebSocket upgrade is possible.

Phase 2 — Long Polling as Fallback

Before upgrading to WebSocket, Engine.IO starts with HTTP long polling. This ensures the connection works even on networks that block WebSockets (corporate proxies, firewalls).

Client ──→ request
Server ─── hold...
Server ──→ sends data when available
Client ──→ immediately sends next request

Phase 3 — Transport Upgrade

Once the polling works, Socket.IO tries to upgrade to WebSocket:

GET /socket.io/?EIO=4&transport=websocket&sid=abc123

Server responds: HTTP 101 Switching Protocols

Polling stops. WebSocket takes over. You now have a persistent connection.

Phase 4 — Real-Time Communication

Now socket.emit() and socket.on() work over WebSocket frames.

// Client
socket.emit('newMessage', 'Hello everyone')

// Server
io.on('connection', (socket) => {
  socket.on('newMessage', (msg) => {
    io.emit('newMessage', msg) // broadcast to all
  })
})

The full flow looks like this:

io() called
    │
HTTP Handshake (get session ID)
    │
Long Polling starts (fallback)
    │
WebSocket upgrade attempt
    │
WebSocket connected
    │
Real-time events ↔

Heartbeat (Ping/Pong)

Socket.IO keeps the connection alive using a heartbeat:

Server ──→ ping
Client ──→ pong

If pong doesn't come back within the timeout, connection is marked dead and auto-reconnect kicks in.

Socket.IO in React

Install:

npm install socket.io-client

Basic usage:

import { useEffect, useState } from 'react'
import { io } from 'socket.io-client'

const socket = io('http://localhost:5000')

function Chat() {
  const [messages, setMessages] = useState([])

  useEffect(() => {
    socket.on('newMessage', (msg) => {
      setMessages((prev) => [...prev, msg])
    })

    return () => socket.off('newMessage')
  }, [])

  const sendMessage = () => {
    socket.emit('newMessage', 'Hello!')
  }

  return (
    <div>
      {messages.map((msg, i) => <p key={i}>{msg}</p>)}
      <button onClick={sendMessage}>Send</button>
    </div>
  )
}

Rooms (Important for Group Chats)

Rooms let you target specific groups of users:

// Server
socket.join('cricket-room')
io.to('cricket-room').emit('scoreUpdate', { score: '45/2' })

Only users in cricket-room receive that event. This is how group chats, channels, and game lobbies work.

The Scaling Problem (This is Where It Gets Interesting)

Socket.IO on a single server works great. But production apps have multiple servers behind a load balancer.

Here's the problem:

           Load Balancer
                │
      ┌─────────┼─────────┐
      │         │         │
   Server1   Server2   Server3

User A → Server1
User B → Server3

User A sends a message to "cricket-room". Server1 knows who's in that room on its own connections. But it has no idea about User B sitting on Server3.

Result: User B never gets the message. ❌

The Fix: Redis Adapter

Redis acts as a message broker between all your Socket.IO servers.

           Load Balancer
                │
      ┌─────────┼─────────┐
      │         │         │
   Server1   Server2   Server3
      │         │         │
      └──────── Redis ────┘

When Server1 emits an event, it publishes to Redis. Redis broadcasts it to all other servers. Each server delivers the message to its own connected clients.

Setup:

npm install @socket.io/redis-adapter redis

import { createClient } from 'redis'
import { Server } from 'socket.io'
import { createAdapter } from '@socket.io/redis-adapter'

const io = new Server(3000)

const pubClient = createClient({ url: 'redis://localhost:6379' })
const subClient = pubClient.duplicate()

await Promise.all([pubClient.connect(), subClient.connect()])

io.adapter(createAdapter(pubClient, subClient))

That's it. Now all your Socket.IO servers share room state through Redis.

Message flow with Redis:

User A → Server1
Server1 → publish to Redis
Redis → broadcast to Server2, Server3
Server2 → deliver to User B
Server3 → deliver to User C

Everyone gets the message regardless of which server they're on.

How Apps Like WhatsApp Handle Millions of Connections

This is the big question. One server can handle maybe 50k–100k WebSocket connections. How do you get to millions?

1. Horizontal Scaling

Simple math: 100 servers × 50k connections = 5 million connections.

2. Load Balancer Routes Traffic

Users
  │
Load Balancer (Nginx / AWS ELB)
  │
WebSocket Server Pool

3. Stateless Servers + Message Broker

Servers don't store state. They just receive and forward. Redis or Kafka sits in the middle.

User A → Server1 → Kafka → Server7 → User B

4. Event Loop Servers (Node.js / Erlang / Go)

Traditional servers use one thread per connection. That doesn't scale.

Node.js uses a single-threaded event loop with non-blocking I/O. One process can handle tens of thousands of concurrent connections.

WhatsApp famously used Erlang — a language designed for millions of lightweight concurrent processes. It's literally built for this.

5. Edge / Regional Clusters

Users connect to the nearest data center. India users hit Asia servers. US users hit US servers. Latency drops, load distributes.

6. Idle Connection Optimization

Most WebSocket connections are idle most of the time. The server is just sending tiny ping/pong packets (10–20 bytes). Millions of idle connections are actually manageable if your server is event-driven.

Full production architecture:

Users
  │
Global Load Balancer
  │
Regional Load Balancers
  │
WebSocket Server Pool (stateless)
  │
Redis / Kafka (message bus)
  │
Database

Quick Comparison: What to Use When

Scenario	Use This
Simple real-time, reliability matters	Socket.IO
You need full control, minimal overhead	Raw WebSocket
One-way server → client stream (feeds, logs)	Server-Sent Events
Multiple servers in production	Socket.IO + Redis Adapter
Millions of connections, serious scale	Kafka + stateless servers

Summary

Here's the full picture in one place:

Before WebSockets: Polling, long polling, Comet hacks — all workarounds
WebSocket: Real persistent two-way connection, changed everything in 2011
Socket.IO: Library on top of WebSocket with events, rooms, reconnection, and fallback transport
Internally: HTTP handshake → polling → upgrade → WebSocket → heartbeat
Scaling problem: Multiple servers can't share room state by default
Redis adapter: Acts as pub/sub bus between servers, solves the problem cleanly
Millions of connections: Horizontal scaling + stateless servers + message broker + edge infrastructure

If this helped, drop a reaction. If you've hit a Socket.IO issue in production that wasn't covered here, drop it in the comments.

Why Most React Apps Fail Core Web Vitals (And How to Actually Fix Them)

Munna Thakur — Sat, 14 Mar 2026 17:29:44 +0000

You built a React app. It looks great. But Google PageSpeed gives you a 45 score and your users are bouncing.

Sound familiar?

The problem is usually Web Vitals. And most React developers either don't know about them or don't know how to fix them in production.

Let's fix that.

What Are Web Vitals (Quick Version)

Google measures 3 things about your website:

Metric	What It Means	Good Score
LCP	How fast does your main content show up?	under 2.5s
CLS	Does your page jump around while loading?	under 0.1
INP	How fast does your UI respond when user clicks something?	under 200ms

These 3 things directly affect your SEO ranking and how users feel on your site.

The Big Problem With React CSR Apps

Here's something a lot of developers miss.

When you open a regular React app (Create React App or Vite), the initial HTML looks like this:

<div id="root"></div>
<script src="main.js"></script>

That's it. There's nothing there. The browser has to:

Download the HTML
Download the JavaScript bundle
Parse and execute the JS
Let React render the UI
Only then does the user see something

So your LCP is always going to be slow. Because the user is staring at a blank screen while all of this is happening.

Compare that to Next.js (SSR):

<div id="root">
  <h1>Welcome to My Site</h1>
  <img src="hero.webp" />
</div>

Server already sent the full HTML. Browser just paints it immediately. LCP is done.

That's why Next.js apps almost always have better LCP out of the box.

How React Fiber Actually Helps (The Internal Stuff)

React Fiber is React's rendering engine (introduced in React 16). Most people have heard of it but don't know what it actually does.

Before Fiber, rendering was fully synchronous. React would start rendering your component tree and could not stop until it was done. If your tree was big, the browser would freeze.

Fiber changed this. It breaks rendering into small chunks and can pause and resume work between browser frames.

Think of it like this:

Before Fiber:

Start rendering → can't stop → browser freezes → bad INP

With Fiber:

Render a bit → pause → let browser paint → continue → smooth UI

This is why modern React APIs like useTransition and useDeferredValue are possible. They tell Fiber to treat certain updates as low priority.

const [isPending, startTransition] = useTransition();

function handleSearch(value) {
  startTransition(() => {
    setResults(filterBigList(value)); // low priority
  });
}

User typing stays fast. The heavy filtering happens in the background. INP stays good.

How to Check Web Vitals in Your React App

First, install the package:

npm install web-vitals

Then in your index.js:

import { getCLS, getLCP, getINP } from 'web-vitals';

getCLS(console.log);
getLCP(console.log);
getINP(console.log);

You'll see something like this in your console:

{ name: 'LCP', value: 2100 }
{ name: 'CLS', value: 0.03 }
{ name: 'INP', value: 145 }

For production monitoring, instead of console.log, send the data to your analytics:

getLCP((metric) => {
  fetch('/analytics', {
    method: 'POST',
    body: JSON.stringify(metric),
  });
});

How to Fix Each Metric

Fixing LCP (Slow Loading)

1. Split your code

Don't ship everything in one big bundle.

const Dashboard = React.lazy(() => import('./Dashboard'));

Users only download what they need.

2. Preload your hero image

<link rel="preload" as="image" href="/hero.webp" />

This tells the browser to start downloading the image before it even finds the <img> tag.

3. Use WebP images

WebP is a modern image format by Google. Same quality, way smaller file size.

Format	File Size
JPEG	500 KB
PNG	800 KB
WebP	~150 KB

That's up to 70% smaller. Smaller image = faster download = better LCP.

<picture>
  <source srcSet="hero.webp" type="image/webp" />
  <img src="hero.jpg" alt="hero" width="800" height="400" />
</picture>

4. Move to SSR

If LCP is consistently bad, the real fix is server-side rendering. Use Next.js or Remix. They pre-render HTML on the server so users never stare at a blank screen.

Fixing CLS (Layout Shifts)

This one is simple but gets ignored a lot.

Always give your images a size:

// Bad - browser doesn't know the size, layout shifts when image loads
<img src="/banner.webp" />

// Good
<img src="/banner.webp" width="800" height="400" />

Reserve space for dynamic content:

If you're loading data and showing it, use a skeleton placeholder so the layout doesn't jump.

function UserCard() {
  return (
    <div style={{ height: '200px' }}>
      {data ? <Profile /> : <Skeleton />}
    </div>
  );
}

Fixing INP (Slow Interactions)

INP gets bad when you run heavy JavaScript on the main thread.

1. Use useMemo for expensive calculations

// Bad - runs on every render
function App() {
  const result = heavyCalculation(data);
  return <div>{result}</div>;
}

// Good - only runs when data changes
const result = useMemo(() => heavyCalculation(data), [data]);

2. Use useTransition for non-urgent updates

const [isPending, startTransition] = useTransition();

startTransition(() => {
  setFilteredList(bigList.filter(fn));
});

3. Virtualize long lists

Rendering 10,000 items kills INP. Use react-window to only render what's visible.

import { FixedSizeList as List } from 'react-window';

<List
  height={400}
  itemCount={10000}
  itemSize={35}
  width={300}
>
  {Row}
</List>

4. Avoid unnecessary re-renders

const MyComponent = React.memo(ExpensiveComponent);

const handleClick = useCallback(() => {
  doSomething();
}, []);

Production Debug Workflow

When Web Vitals are bad in production, here's how to actually debug it:

Run Google Lighthouse (DevTools → Lighthouse tab)
Check which metric is failing
If LCP is bad → look at bundle size and images
If INP is bad → look for heavy JS on the main thread
If CLS is bad → look for images without dimensions

To analyze your bundle size:

npm run build
npx source-map-explorer build/static/js/*.js

This shows you exactly which libraries are eating your bundle. Common culprits:

// Bad - imports the entire lodash library
import _ from 'lodash';

// Good - imports only what you need
import debounce from 'lodash/debounce';

Quick Summary

Problem	Fix
Large JS bundle	Code splitting with `React.lazy`
Slow hero image	WebP format + preload link
Layout shifts	Always define image dimensions
Heavy interactions	`useTransition` + `useMemo`
Long lists	`react-window` virtualization
Consistently bad LCP	Move to Next.js SSR

One Last Thing

Most React performance issues come down to one thing: too much work happening on the main thread at the wrong time.

Fiber handles a lot of this automatically, but you still need to help it. Use the concurrent features (useTransition, useDeferredValue), split your code, optimize your images, and measure everything with the web-vitals package.

Don't guess. Measure first, then fix.

If this helped, drop a reaction. And if you've run into a Web Vitals issue I didn't cover, mention it in the comments — happy to dig into it.

From Page Source Confusion to Understanding How the Browser Really Works

Munna Thakur — Sat, 14 Mar 2026 04:18:01 +0000

One moment of curiosity while switching from React to Next.js led me down a rabbit hole that changed how I think about the web entirely.

The Moment That Started It All

I was working on a Next.js project one day. Normal day, normal work. Out of curiosity I right-clicked on the browser and hit View Page Source.

What I saw made no sense.

The page source was filled with hundreds of lines of weird scripts, JSON data, token strings, user info — everything. It looked like someone had dumped a database into the HTML. I honestly thought something was broken.

Then I compared it with an older React app (Create React App). The page source there was almost empty:

<div id="root"></div>
<script src="/static/js/main.0ab98b7f.js"></script>

That was it. Just a div. Nothing else.

That confusion was actually the best thing that happened. It pushed me to understand what is actually going on when a browser loads a page.

React vs Next.js: Why Page Source Looks So Different

Old React (Create React App) — The Empty Shell

When you build a React app using Create React App, the server sends almost nothing. Just a bare HTML shell with an empty div and a JavaScript file reference.

<!-- What the server sends -->
<html>
  <body>
    <div id="root"></div>
    <script src="/static/js/main.js"></script>
  </body>
</html>

The browser receives this empty shell. Then it downloads main.js, runs it, and React builds the entire page inside that empty div. This whole process happens in the browser, on your computer.

This is called Client Side Rendering (CSR). The server does almost nothing. All the real work happens in the browser.

⚠️ Key thing to understand: View Page Source always shows what the server sent — not what JavaScript built later. That's why React's page source looks empty. The content was built by JavaScript after the page loaded.

Next.js (App Router) — The Full Picture

Next.js works very differently. The server generates the actual HTML before sending it to you. So when you hit View Page Source on a Next.js page, you see the real content plus a lot of extra data.

That extra stuff you see — all those self.__next_f.push() scripts — that is the RSC Streaming Payload. RSC stands for React Server Components.

What it contains:

✅ The actual rendered HTML content
✅ Server-fetched data (articles, topics, lists)
✅ Component props passed from server to client
✅ SEO metadata
⚠️ Sometimes things that shouldn't be there (more on this below)

<!-- What Next.js server sends -->
<h1>Trending Headlines</h1>

<script>
  self.__next_f.push([1, '{"articles": [...], "token": "eyJhbG..."}'])
</script>

This is called Server Side Rendering (SSR). The server does the heavy lifting and sends you a fully built page.

Side by Side Comparison

Feature	React (CRA)	Next.js (App Router)
What server sends	Empty HTML shell	Full rendered HTML
Page Source content	Just `div#root`	Full content + streamed data
When content appears	After JS runs	Before JS runs
SEO friendly	❌ No	✅ Yes
First load performance	Slower	Faster
View Source useful?	Not really	Yes

View Page Source vs Inspect Element

This trips up a lot of developers. They look different because they are different.

🔍 View Page Source

Shows exactly what the server sent to your browser. A snapshot of the raw HTML before JavaScript touched anything.

React apps → you see an empty div
Next.js apps → you see pre-rendered HTML plus RSC payload
Useful for: checking SEO tags, verifying server rendering, finding security issues

🛠️ Inspect Element (DevTools)

Shows the live DOM — the actual state of the page after JavaScript has run, modified, and updated everything.

Always shows the current real UI
Updates in real time as JS runs
This is what the user actually sees

✅ Simple rule: View Source = what the server sent. Inspect Element = what the browser is showing right now.

How the Browser Renders a Page

Once HTML arrives, a very specific sequence kicks off. Understanding this separates a developer who writes code from one who actually knows why things work.

Step 1 — HTML Parsing → DOM

The browser reads HTML top to bottom and builds a tree structure called the DOM (Document Object Model).

<body>
  <h1>Hello</h1>
  <p>World</p>
</body>

Becomes this internally:

Document
  └── html
        └── body
              ├── h1 → "Hello"
              └── p  → "World"

Step 2 — CSS Parsing → CSSOM

The browser reads all CSS and builds the CSSOM (CSS Object Model) — its internal map of all styling rules.

Step 3 — Render Tree

The browser merges DOM + CSSOM into a Render Tree.

Important rule: elements with display: none are not in the render tree at all. visibility: hidden elements still show up — they just have no color.

Step 4 — Layout (Reflow)

The browser calculates the exact position and size of every element. Width, height, coordinates, margins, padding. This is called Layout or Reflow.

It is expensive. If you trigger it repeatedly in JavaScript (like reading offsetHeight inside a loop), your page gets slow.

// ❌ Bad — triggers layout on every iteration
for (let i = 0; i < 1000; i++) {
  element.style.width = "100px"
  element.offsetHeight // forces layout recalculation
}

// ✅ Better — batch reads and writes separately
const height = element.offsetHeight // read once
element.style.width = "100px"       // then write

Step 5 — Paint

The browser fills in the pixels. Colors, backgrounds, shadows, borders, text.

Step 6 — Compositing (GPU Magic)

Modern browsers split the page into layers and hand them to the GPU. transform and opacity only affect this compositing step.

That is why CSS animations using transform are so much smoother than animations using width or height — they skip Layout and Paint entirely.

/* ❌ Triggers layout + paint on every frame */
.box { transition: width 0.3s; }

/* ✅ Only hits compositing — buttery smooth */
.box { transition: transform 0.3s; }

🚀 Pro tip: Always use transform and opacity for animations. They skip the expensive layout and paint phases.

HTTP vs HTTPS — The Real Difference

Before I understood this properly, I thought HTTP and HTTPS were basically the same thing with a padlock icon. That is completely wrong.

HTTP — Plain Text on the Internet

HTTP (HyperText Transfer Protocol) is the language browsers and servers use to communicate. The problem is everything travels in plain text. Zero encryption.

Imagine you're at a cafe on public WiFi. You go to an HTTP website and type your password. Anyone on that same network running a packet sniffer can literally read your password as it travels through the air:

POST /login HTTP/1.1
Host: somesite.com

username=john&password=secret123

🔴 That password is visible to anyone intercepting your traffic. This is not a theoretical risk — it is trivially easy to do on public networks.

HTTPS — Encrypted Communication

HTTPS adds a security layer called TLS (Transport Layer Security) on top of HTTP. That same password POST, when encrypted with TLS, looks like this to anyone intercepting it:

xK93!#@mBqP2▓△◇☆■♠... [scrambled nonsense]

Only the browser and the server hold the keys to decrypt it.

What TLS Actually Does (In Plain Terms)

TLS solves three real-world problems at once:

🔐 1. Encryption

Nobody can read your data in transit. Not your ISP, not hackers on the same WiFi, not your router. The data is scrambled before it leaves your device.

🏷️ 2. Authentication

You can verify you're actually talking to the real website and not a fake one designed to steal your data. This is what the padlock icon confirms.

🔏 3. Integrity

The data that arrives is exactly what was sent. Nobody modified it in the middle. Without this, a middleman could quietly change the content of pages you visit.

The TLS Handshake — Step by Step

Every HTTPS connection starts with a TLS handshake. This happens automatically, in milliseconds, before you see any page content.

Browser                          Server
   |                               |
   |------- ClientHello ---------->|  "Here's what encryption I support"
   |                               |
   |<------ ServerHello -----------|  "Let's use this method"
   |<------ Certificate -----------|  "Here's proof of who I am"
   |<------ Public Key ------------|
   |                               |
   |------- Key Exchange -------->|  Browser generates secret, encrypts it
   |                               |  Both sides now have the same key
   |                               |
   |====== Encrypted Channel ======|
   |                               |
   |------- GET /page ----------->|  Actual request, now encrypted
   |<------ 200 OK + HTML --------|  Actual response, now encrypted

Step by step:

Client Hello — Browser says: here are the encryption methods I support, and here's a random number.
Server Hello — Server picks a method, sends its SSL certificate.
Certificate Check — Browser checks: is this cert from a trusted authority? Is the domain right? Not expired? If anything is wrong, you see the "Not Secure" warning.
Key Exchange — Browser encrypts a secret value using the server's public key and sends it. Both sides derive the same encryption key from this. The actual key never travels over the network — that's the clever part.
Secure Channel — Everything from here on is encrypted.

🔒 For users: When you see the padlock, it means (1) you're on the real site, (2) your data is encrypted in transit, (3) nobody can tamper with what you receive.

The Full Journey: URL to Page

Let us walk through everything that happens when you type a URL and press Enter.

Phase 1 — URL Parsing

https://example.com/headlines?id=10
  │         │           │        │
  │         │           │        └── Query params
  │         │           └────────── Path (which page)
  │         └────────────────────── Domain name
  └──────────────────────────────── Protocol → port 443

Phase 2 — DNS Lookup

The browser needs an IP address, not a domain name. Computers talk in numbers.

example.com
    │
    ├── Browser cache? → yes → use it (skip the rest)
    ├── OS cache?
    ├── Router cache?
    ├── ISP DNS server?
    ├── Root DNS server → "where is .com?"
    ├── .com TLD server → "where is example.com?"
    └── Authoritative DNS → IP: 93.184.216.34  ✅

Phase 3 — TCP 3-Way Handshake

Browser → Server:  SYN      (I want to connect)
Server  → Browser: SYN+ACK  (OK, I'm ready)
Browser → Server:  ACK      (Great, let's go)

Connection established. ✅

Phase 4 — TLS Handshake (if HTTPS)

As described above. Adds 1-2 round trips.

Phase 5 — HTTP Request

GET /headlines HTTP/1.1
Host: example.com
User-Agent: Chrome/145.0.0.0
Accept: text/html
Cookie: session=abc123

Phase 6 — Server Processing

The server reads the route, runs logic, fetches data, generates HTML, and streams it back.

Phase 7 — Browser Rendering

HTML arrives → DOM → CSSOM → Render Tree → Layout → Paint → Composite → you see the page.

The Security Issue I Found

When I looked at my page source, I noticed sensitive data sitting right there in the HTML. Here is what I found and why it matters.

What Was Exposed

A JWT authentication token (the thing that keeps users logged in)
A Google OAuth token
Full user details including email and profile info

Why Is This a Problem?

The JWT token is essentially a digital key to that user's account. If someone grabs it from the page source, they can make API requests pretending to be that user. Tokens have expiry times, but that window can be wide open.

The Right Approach

Sensitive tokens should live in HTTP-only cookies. HTTP-only cookies cannot be accessed by JavaScript at all and are never exposed in page source. The server reads them automatically on each request.

// ❌ Wrong — token passed as prop, now it's in page source
<ClientComponent token={jwt_token_here} />

// ✅ Right — use HTTP-only cookie, set on the server
res.setHeader('Set-Cookie', [
  `auth_token=${token}; HttpOnly; Secure; SameSite=Strict; Path=/`
])

⚠️ Lesson: Just because Next.js makes it easy to pass data from server to client doesn't mean all data should flow that way. Sensitive auth tokens belong in HTTP-only cookies, not in the RSC payload.

What This Means for Users (The Non-Dev Perspective)

Most users have no idea this is happening. But as developers, understanding this helps us build things that actually protect them.

What the user sees	What's actually happening
Typing a URL and pressing Enter	DNS lookup + TCP + TLS + HTTP request, all in under 200ms
The padlock icon	TLS certificate verified, encrypted channel open
Page appearing immediately	SSR pre-built the HTML, browser just painted it
Page loading slowly, then content appearing	CSR — browser downloaded JS, ran it, then fetched data
"Not Secure" warning	No TLS, data is unencrypted
Logging in safely	Password encrypted by TLS before leaving your device
Laggy scrolling	JavaScript causing layout reflow — expensive recalculations

Key Takeaways

React vs Next.js HTML

React (CRA) sends an empty shell. JS builds everything in the browser.
Next.js sends real pre-rendered HTML. The server did the work first.
View Source = what the server sent. Inspect Element = what the user sees.

Browser Rendering

HTML → DOM → CSS → CSSOM → Render Tree → Layout → Paint → Composite
display: none elements are not in the render tree
Use transform and opacity for animations — they skip Layout and Paint
Avoid reading layout properties inside loops (layout thrashing)

HTTP vs HTTPS and TLS

HTTP = plain text. Anyone can read it.
HTTPS = HTTP encrypted with TLS.
TLS provides: encryption (unreadable), authentication (real site), integrity (untampered)
The padlock means all three are active

Security

Never expose auth tokens in RSC payload or as client component props
Use HTTP-only cookies for sensitive session data
Regularly check your page source — you might be surprised what's in there

That one moment of confusion looking at a Next.js page source taught me more about how the web actually works than months of just writing components. Sometimes the best learning comes from pausing and asking — why does this look like this?

Tags: javascript nextjs react webdev security

React Query Architecture — Complete Flow from Hook to Render

Munna Thakur — Sat, 14 Feb 2026 09:39:07 +0000

Ever wondered what actually happens when you call useQuery?

How does React Query:

✅ Connect your component to the cache?
✅ Know when to re-render?
✅ Avoid unnecessary renders?
✅ Work with React 18's concurrent features?

This guide shows you the complete internal flow from hook call to screen update.

From @tanstack/react-query

📋 Table of Contents

The Big Picture
Complete Architecture Diagram
Layer-by-Layer Breakdown
The Complete Flow
React Integration
QueryObserver Deep Dive
useSyncExternalStore Explained
Re-render Logic
Real Code Walkthrough
Performance Optimizations
Mental Models

⚡ Quick Summary

TL;DR: React Query uses:

✅ QueryObserver as the bridge between React and cache

✅ useSyncExternalStore to subscribe to external state

✅ Structural sharing to prevent unnecessary renders

✅ Observer pattern for fine-grained updates

✅ Batched notifications via NotifyManager

Length: ~35 min read | Level: Advanced

🎯 The Big Picture {#the-big-picture}

Simple Mental Model:

React Component
    ↓
useQuery (Hook)
    ↓
QueryObserver (Bridge)
    ↓
Query (State Machine)
    ↓
QueryCache (Database)
    ↓
QueryClient (Orchestrator)

Key Insight:

React Query is NOT React state.

It's an external store that React observes via useSyncExternalStore.

🏗 Complete Architecture Diagram {#complete-architecture-diagram}

Visual Overview:

┌─────────────────────────────────────────────────────────────┐
│                      React Component                         │
│  const { data, isLoading } = useQuery({ queryKey, queryFn })│
└────────────────────┬────────────────────────────────────────┘
                     │
                     │ (1) Hook call
                     ↓
┌─────────────────────────────────────────────────────────────┐
│                       useQuery Hook                          │
│  - Creates/reuses QueryObserver                             │
│  - Calls useSyncExternalStore                               │
│  - Returns result to component                              │
└────────────────────┬────────────────────────────────────────┘
                     │
                     │ (2) Create observer
                     ↓
┌─────────────────────────────────────────────────────────────┐
│                     QueryObserver                            │
│  Role: Bridge between React and Query                       │
│  - Subscribes to Query                                      │
│  - Tracks accessed properties                               │
│  - Diffs state changes                                      │
│  - Notifies React when needed                               │
└────────────────────┬────────────────────────────────────────┘
                     │
                     │ (3) Subscribe to Query
                     ↓
┌─────────────────────────────────────────────────────────────┐
│                        Query                                 │
│  Role: Individual query state machine                       │
│  - Manages state (data, error, status)                     │
│  - Handles fetch logic via Retryer                         │
│  - Notifies observers on state change                      │
│  - Stored in QueryCache                                    │
└────────────────────┬────────────────────────────────────────┘
                     │
                     │ (4) Stored in
                     ↓
┌─────────────────────────────────────────────────────────────┐
│                      QueryCache                              │
│  Role: Database of all Query instances                      │
│  - Map<queryHash, Query>                                    │
│  - Fast O(1) lookup                                         │
│  - Garbage collection                                       │
│  - Global event emitter                                     │
└────────────────────┬────────────────────────────────────────┘
                     │
                     │ (5) Accessed via
                     ↓
┌─────────────────────────────────────────────────────────────┐
│                     QueryClient                              │
│  Role: Central orchestrator                                  │
│  - API for interacting with cache                           │
│  - Invalidation, refetch, mutations                         │
│  - Configuration management                                 │
└─────────────────────────────────────────────────────────────┘

📊 Layer-by-Layer Breakdown {#layer-by-layer-breakdown}

Layer 1: React Component 🎨

Your code:

function UserList() {
  const { data, isLoading, error } = useQuery({
    queryKey: ['users'],
    queryFn: fetchUsers
  })

  if (isLoading) return <Spinner />
  if (error) return <Error />
  return <List data={data} />
}

What component does:

Calls useQuery hook
Receives reactive result
Re-renders when result changes

Layer 2: useQuery Hook 🪝

Internal implementation (simplified):

function useQuery(options) {
  const queryClient = useQueryClient()

  // Create observer (memoized)
  const observer = React.useMemo(
    () => new QueryObserver(queryClient, options),
    []
  )

  // Update options on every render
  observer.setOptions(options)

  // Subscribe using React 18's useSyncExternalStore
  const result = useSyncExternalStore(
    // Subscribe function
    (onStoreChange) => observer.subscribe(onStoreChange),

    // Get current snapshot
    () => observer.getCurrentResult(),

    // Get server snapshot (for SSR)
    () => observer.getCurrentResult()
  )

  return result
}

Key responsibilities:

Create/reuse QueryObserver
Subscribe to observer via useSyncExternalStore
Return current result

Layer 3: QueryObserver 👀

Internal structure:

class QueryObserver {
  constructor(client, options) {
    this.client = client
    this.options = options
    this.listeners = new Set()
    this.currentQuery = undefined
    this.currentResult = undefined
    this.trackedProps = new Set()
  }

  // Called by useSyncExternalStore
  subscribe(listener) {
    this.listeners.add(listener)

    // Get or create query
    this.updateQuery()

    // Subscribe to query
    const unsubscribe = this.currentQuery.subscribe(this)

    return () => {
      this.listeners.delete(listener)
      unsubscribe()
    }
  }

  // Get current result for component
  getCurrentResult() {
    return this.currentResult
  }

  // Called when query updates
  onQueryUpdate() {
    // Create new result
    const result = this.createResult()

    // Check if changed
    if (this.hasResultChanged(result)) {
      this.currentResult = result

      // Notify React
      this.listeners.forEach(listener => listener())
    }
  }

  // Track which properties component accessed
  createResult() {
    const query = this.currentQuery
    const state = query.state

    return {
      data: state.data,
      error: state.error,
      isLoading: state.status === 'pending',
      isSuccess: state.status === 'success',
      isError: state.status === 'error',
      // ... more properties
    }
  }

  // Smart diffing
  hasResultChanged(result) {
    // If no tracked props, check all
    if (this.trackedProps.size === 0) {
      return !shallowEqual(this.currentResult, result)
    }

    // Only check tracked props
    for (const key of this.trackedProps) {
      if (this.currentResult[key] !== result[key]) {
        return true
      }
    }

    return false
  }
}

Key responsibilities:

Bridge between React and Query
Track which properties component uses
Diff state changes efficiently
Notify React only when needed

Layer 4: Query 🔧

Internal structure:

class Query {
  constructor(config) {
    this.queryKey = config.queryKey
    this.queryHash = hashQueryKey(config.queryKey)
    this.options = config.options

    // State
    this.state = {
      data: undefined,
      dataUpdatedAt: 0,
      error: null,
      errorUpdatedAt: 0,
      fetchStatus: 'idle',
      status: 'pending'
    }

    // Observers (components watching this query)
    this.observers = new Set()

    // Current fetch promise
    this.promise = null

    // Retry controller
    this.retryer = null

    // GC timer
    this.gcTimeout = null
  }

  // Add observer (component)
  subscribe(observer) {
    this.observers.add(observer)
    this.clearGcTimeout()

    // Notify observer of current state
    observer.onQueryUpdate()

    return () => {
      this.observers.delete(observer)

      // No observers? Schedule GC
      if (this.observers.size === 0) {
        this.scheduleGc()
      }
    }
  }

  // Fetch data
  async fetch() {
    // Already fetching?
    if (this.promise) {
      return this.promise
    }

    // Update state
    this.setState({
      fetchStatus: 'fetching'
    })

    // Create retryer
    this.retryer = new Retryer({
      fn: this.options.queryFn,
      retry: this.options.retry,
      retryDelay: this.options.retryDelay
    })

    // Start fetch
    this.promise = this.retryer.start()
      .then(data => {
        this.setState({
          data,
          dataUpdatedAt: Date.now(),
          status: 'success',
          fetchStatus: 'idle',
          error: null
        })
        return data
      })
      .catch(error => {
        this.setState({
          error,
          errorUpdatedAt: Date.now(),
          status: 'error',
          fetchStatus: 'idle'
        })
        throw error
      })
      .finally(() => {
        this.promise = null
      })

    return this.promise
  }

  // Update state and notify observers
  setState(updater) {
    this.state = { ...this.state, ...updater }

    // Notify all observers
    this.notify()
  }

  // Notify observers
  notify() {
    notifyManager.batch(() => {
      this.observers.forEach(observer => {
        observer.onQueryUpdate()
      })
    })
  }

  // Schedule garbage collection
  scheduleGc() {
    this.clearGcTimeout()
    this.gcTimeout = setTimeout(() => {
      this.cache.remove(this)
    }, this.options.gcTime)
  }

  clearGcTimeout() {
    if (this.gcTimeout) {
      clearTimeout(this.gcTimeout)
      this.gcTimeout = null
    }
  }
}

Key responsibilities:

Store query state
Handle fetch lifecycle
Manage observers
Notify on state changes

Layer 5: QueryCache 🗄️

Internal structure:

class QueryCache {
  constructor(config) {
    this.config = config
    this.queries = []
    this.queriesMap = new Map()
  }

  // Build or get query
  build(client, options) {
    const queryKey = options.queryKey
    const queryHash = hashQueryKey(queryKey)

    // Existing query?
    let query = this.queriesMap.get(queryHash)

    // Create new if needed
    if (!query) {
      query = new Query({
        cache: this,
        queryKey,
        queryHash,
        options,
        state: options.initialData
          ? {
              data: options.initialData,
              status: 'success',
              dataUpdatedAt: Date.now()
            }
          : undefined
      })

      this.queries.push(query)
      this.queriesMap.set(queryHash, query)
      this.notify({ type: 'added', query })
    }

    return query
  }

  // Find query by key
  find(queryKey) {
    const queryHash = hashQueryKey(queryKey)
    return this.queriesMap.get(queryHash)
  }

  // Find all matching queries
  findAll(filters) {
    return this.queries.filter(query => 
      matchQuery(filters, query)
    )
  }

  // Remove query
  remove(query) {
    const index = this.queries.indexOf(query)
    if (index !== -1) {
      this.queries.splice(index, 1)
      this.queriesMap.delete(query.queryHash)
      this.notify({ type: 'removed', query })
    }
  }

  // Notify listeners (e.g., DevTools)
  notify(event) {
    this.listeners.forEach(listener => {
      listener(event)
    })
  }
}

Key responsibilities:

Store all Query instances
Fast lookup by hash
Garbage collection
Event emission

Layer 6: QueryClient 🧠

We covered this in detail in the QueryClient guide!

🔄 The Complete Flow {#the-complete-flow}

Step-by-Step Execution:

┌─────────────────────────────────────────────────────────────┐
│  Step 1: Component Mounts                                    │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  function UserList() {                                       │
│    const result = useQuery({                                │
│      queryKey: ['users'],                                   │
│      queryFn: fetchUsers                                    │
│    })                                                       │
│  }                                                          │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 2: useQuery Hook Executes                             │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  // Inside useQuery                                         │
│  const observer = useMemo(                                  │
│    () => new QueryObserver(client, options),               │
│    []                                                       │
│  )                                                          │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 3: QueryObserver Created                              │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  QueryObserver {                                            │
│    client: QueryClient                                      │
│    options: { queryKey, queryFn }                          │
│    listeners: Set()                                         │
│    currentQuery: undefined                                  │
│    currentResult: undefined                                 │
│  }                                                          │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 4: useSyncExternalStore Called                        │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  useSyncExternalStore(                                      │
│    // Subscribe callback                                    │
│    (onStoreChange) => {                                     │
│      return observer.subscribe(onStoreChange)              │
│    },                                                       │
│    // Get snapshot                                          │
│    () => observer.getCurrentResult()                       │
│  )                                                          │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 5: Observer Subscribes to Query                       │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  observer.subscribe(onStoreChange) {                        │
│    // Get or create query                                   │
│    const query = queryCache.build(options)                 │
│                                                             │
│    // Subscribe to query                                    │
│    const unsubscribe = query.subscribe(this)               │
│                                                             │
│    // Store listener                                        │
│    this.listeners.add(onStoreChange)                       │
│                                                             │
│    return () => {                                           │
│      unsubscribe()                                          │
│      this.listeners.delete(onStoreChange)                  │
│    }                                                        │
│  }                                                          │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 6: Query Built/Retrieved from Cache                   │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  queryCache.build(options) {                                │
│    const queryHash = hash(['users'])                       │
│                                                             │
│    // Check if exists                                       │
│    let query = this.queriesMap.get(queryHash)             │
│                                                             │
│    // Create if new                                         │
│    if (!query) {                                            │
│      query = new Query({                                   │
│        queryKey: ['users'],                                │
│        queryHash: '["users"]',                             │
│        options                                              │
│      })                                                     │
│      this.queriesMap.set(queryHash, query)                │
│    }                                                        │
│                                                             │
│    return query                                             │
│  }                                                          │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 7: Query Adds Observer                                │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  query.subscribe(observer) {                                │
│    // Add to observers set                                  │
│    this.observers.add(observer)                            │
│                                                             │
│    // Cancel GC                                             │
│    this.clearGcTimeout()                                   │
│                                                             │
│    // Notify observer immediately                           │
│    observer.onQueryUpdate()                                │
│                                                             │
│    return unsubscribe function                             │
│  }                                                          │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 8: Check if Fetch Needed                              │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  // Inside observer.onQueryUpdate()                         │
│  if (!query.state.data || query.isStale()) {              │
│    query.fetch()                                            │
│  }                                                          │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 9: Fetch Starts                                       │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  query.fetch() {                                            │
│    // Update state                                          │
│    this.setState({                                          │
│      fetchStatus: 'fetching'                               │
│    })                                                       │
│                                                             │
│    // Execute queryFn                                       │
│    this.promise = fetchUsers()                             │
│      .then(data => {                                        │
│        this.setState({                                      │
│          data,                                              │
│          status: 'success',                                │
│          fetchStatus: 'idle',                              │
│          dataUpdatedAt: Date.now()                         │
│        })                                                   │
│      })                                                     │
│  }                                                          │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 10: State Updates Trigger Notifications               │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  query.setState(update) {                                   │
│    // Merge state                                           │
│    this.state = { ...this.state, ...update }              │
│                                                             │
│    // Notify all observers                                  │
│    this.notify()                                            │
│  }                                                          │
│                                                             │
│  query.notify() {                                           │
│    notifyManager.batch(() => {                             │
│      this.observers.forEach(observer => {                  │
│        observer.onQueryUpdate()                            │
│      })                                                     │
│    })                                                       │
│  }                                                          │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 11: Observer Receives Update                          │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  observer.onQueryUpdate() {                                 │
│    // Create new result                                     │
│    const result = this.createResult()                      │
│                                                             │
│    // Check if changed                                      │
│    if (this.hasResultChanged(result)) {                    │
│      this.currentResult = result                           │
│                                                             │
│      // Notify React via useSyncExternalStore              │
│      this.listeners.forEach(listener => {                  │
│        listener() // Triggers React re-render              │
│      })                                                     │
│    }                                                        │
│  }                                                          │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 12: React Re-renders Component                        │
└─────────────────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│  function UserList() {                                       │
│    // useSyncExternalStore returns new snapshot            │
│    const { data, isLoading } = useQuery(...)               │
│                                                             │
│    // Component re-renders with new data                    │
│    return <List data={data} />                             │
│  }                                                          │
└─────────────────────────────────────────────────────────────┘

⚛️ React Integration {#react-integration}

Why useSyncExternalStore?

React 18 introduced useSyncExternalStore for exactly this use case:

Subscribing to external stores (non-React state) safely with concurrent rendering.

The Problem Without It:

Before React 18:

// Old approach (tearing risk)
function useExternalStore(store) {
  const [state, setState] = useState(store.getState())

  useEffect(() => {
    const unsubscribe = store.subscribe(() => {
      setState(store.getState())
    })
    return unsubscribe
  }, [])

  return state
}

Problem: Tearing in concurrent mode

Component might render with stale data
Inconsistent UI during suspense

The Solution:

useSyncExternalStore guarantees:

✅ No tearing
✅ Concurrent-safe
✅ Consistent snapshots

How React Query Uses It:

function useQuery(options) {
  const queryClient = useQueryClient()
  const observer = useMemo(
    () => new QueryObserver(queryClient, options),
    []
  )

  // Update options every render
  observer.setOptions(options)

  // Subscribe to observer
  const result = useSyncExternalStore(
    // Subscribe function
    React.useCallback(
      (onStoreChange) => observer.subscribe(onStoreChange),
      [observer]
    ),

    // Get current snapshot (client)
    () => observer.getCurrentResult(),

    // Get server snapshot (SSR)
    () => observer.getCurrentResult()
  )

  return result
}

What This Does:

Subscribe function:
- Called once on mount
- Returns unsubscribe function
- React manages the subscription
Get snapshot:
- Called on every render
- Returns current state
- Must be pure and fast
React handles:
- Subscribing/unsubscribing
- Detecting changes
- Triggering re-renders
- Avoiding tearing

👁️ QueryObserver Deep Dive {#queryobserver-deep-dive}

What is QueryObserver?

The bridge between React and Query.

Why Not Subscribe Directly?

// ❌ Why not this?
function useQuery(options) {
  const query = getQuery(options.queryKey)
  const [state, setState] = useState(query.state)

  useEffect(() => {
    return query.subscribe(() => setState(query.state))
  }, [])

  return state
}

Problems:

❌ Re-renders on ANY state change (even unrelated)
❌ No property tracking
❌ No smart diffing
❌ No batching

QueryObserver Solves This:

class QueryObserver {
  // Track which properties component accessed
  trackedProps = new Set()

  createResult() {
    const query = this.currentQuery
    const state = query.state

    // Create proxy to track access
    return new Proxy({
      data: state.data,
      error: state.error,
      isLoading: state.status === 'pending',
      // ... more properties
    }, {
      get: (target, prop) => {
        // Track that component accessed this prop
        this.trackedProps.add(prop)
        return target[prop]
      }
    })
  }

  hasResultChanged(result) {
    // Only check tracked props
    for (const key of this.trackedProps) {
      if (this.currentResult[key] !== result[key]) {
        return true // Re-render needed
      }
    }
    return false // Skip re-render
  }
}

Example:

function Component() {
  // Only accesses 'data'
  const { data } = useQuery(['users'], fetchUsers)
  return <div>{data}</div>
}

// Tracked props: ['data']
// Won't re-render when isLoading, error, etc. change!

🔄 useSyncExternalStore Explained {#usesyncexternalstore-explained}

API:

useSyncExternalStore<Snapshot>(
  subscribe: (onStoreChange: () => void) => () => void,
  getSnapshot: () => Snapshot,
  getServerSnapshot?: () => Snapshot
): Snapshot

Parameters:

1. `subscribe`

Called once on mount.

const subscribe = (onStoreChange) => {
  // Add listener
  const unsubscribe = observer.subscribe(onStoreChange)

  // Return cleanup
  return unsubscribe
}

When observer detects change:

// Inside QueryObserver
if (this.hasResultChanged(newResult)) {
  // Notify React
  this.listeners.forEach(listener => listener())
}

2. `getSnapshot`

Called on every render.

const getSnapshot = () => {
  return observer.getCurrentResult()
}

Must be:

✅ Pure (same input → same output)
✅ Fast (called frequently)
✅ Synchronous
✅ Returns immutable snapshot

React compares snapshots:

const prev = getSnapshot()
// ... time passes ...
const next = getSnapshot()

if (prev !== next) {
  // Re-render component
}

3. `getServerSnapshot` (optional)

For SSR/SSG.

Returns initial state during server rendering.

How React Uses It:

Component Render
    ↓
Call getSnapshot() → Get current state
    ↓
Compare with previous snapshot
    ↓
Different? → Re-render
Same? → Skip render
    ↓
Wait for notification from subscribe callback
    ↓
On notification → Call getSnapshot() again

Why This Is Safe:

Concurrent rendering problem:

// Component might render multiple times before committing
Render 1: getSnapshot() → { count: 0 }
Render 2: getSnapshot() → { count: 1 }  // Store updated
Render 3: getSnapshot() → { count: 2 }  // Store updated again
Commit:   Use latest snapshot { count: 2 }

useSyncExternalStore ensures:

Always uses consistent snapshot
No partial/stale states
No tearing

🎨 Re-render Logic {#re-render-logic}

When Does React Query Re-render?

Decision tree:

Query state changes
    ↓
Query.notify() called
    ↓
All observers notified
    ↓
QueryObserver.onQueryUpdate()
    ↓
Create new result snapshot
    ↓
Compare with previous result
    ↓
    ├─ No tracked props changed
    │       ↓
    │   Skip notification
    │   (No re-render)
    │
    └─ Tracked props changed
            ↓
        Notify React via listener
            ↓
        useSyncExternalStore detects change
            ↓
        Component re-renders

Example Scenarios:

Scenario 1: Only 'data' accessed

function Component() {
  const { data } = useQuery(['users'], fetchUsers)
  return <div>{data?.length} users</div>
}

// Tracked: ['data']
// Re-renders only when data changes

Timeline:

t0: { data: undefined, isLoading: true }
    → No re-render (data unchanged)

t1: { data: [...], isLoading: false }
    → RE-RENDER (data changed)

t2: { data: [...], isFetching: true }
    → No re-render (data unchanged)

t3: { data: [...], isFetching: false }
    → No re-render (data unchanged)

Scenario 2: Multiple properties accessed

function Component() {
  const { data, isLoading } = useQuery(['users'], fetchUsers)

  if (isLoading) return <Spinner />
  return <div>{data?.length} users</div>
}

// Tracked: ['data', 'isLoading']
// Re-renders when either changes

Timeline:

t0: { data: undefined, isLoading: true }
    → No re-render (initial)

t1: { data: undefined, isLoading: true, isFetching: true }
    → No re-render (tracked props unchanged)

t2: { data: [...], isLoading: false }
    → RE-RENDER (both changed)

Scenario 3: Override tracking

const { data } = useQuery(['users'], fetchUsers, {
  notifyOnChangeProps: ['data']  // Only notify for data
})

// Forces tracking of only 'data'
// Even if component accesses other props

Optimization Tips:

1. Only destructure what you need:

// ❌ Bad - tracks all props
const result = useQuery(['users'], fetchUsers)
return <div>{result.data}</div>

// ✅ Good - tracks only data
const { data } = useQuery(['users'], fetchUsers)
return <div>{data}</div>

2. Use notifyOnChangeProps for heavy components:

const { data } = useQuery(['users'], fetchUsers, {
  notifyOnChangeProps: ['data']
})

3. Use select for derived state:

const { data: userCount } = useQuery({
  queryKey: ['users'],
  queryFn: fetchUsers,
  select: (data) => data.length  // Memoized!
})
// Only re-renders when length changes

💻 Real Code Walkthrough {#real-code-walkthrough}

Complete Example:

import { useQuery, QueryClient, QueryClientProvider } from '@tanstack/react-query'

// 1. Create QueryClient
const queryClient = new QueryClient()

// 2. Provide to app
function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <UserList />
    </QueryClientProvider>
  )
}

// 3. Component using useQuery
function UserList() {
  const { data, isLoading, error } = useQuery({
    queryKey: ['users'],
    queryFn: async () => {
      const res = await fetch('/api/users')
      return res.json()
    }
  })

  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  return (
    <ul>
      {data.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  )
}

What Actually Happens:

App Render
    ↓
QueryClientProvider creates context
    ↓
UserList mounts
    ↓
useQuery called
    ↓
    ├─ useQueryClient() → gets QueryClient from context
    │
    ├─ useMemo() → creates QueryObserver (once)
    │      ↓
    │   new QueryObserver(queryClient, options)
    │
    ├─ observer.setOptions() → updates options
    │
    └─ useSyncExternalStore() → subscribes to observer
           ↓
       observer.subscribe(onStoreChange) called
           ↓
       QueryCache.build() → gets/creates Query
           ↓
       Query.subscribe(observer) → adds observer to set
           ↓
       Query checks if fetch needed
           ↓
       Yes → Query.fetch() starts
           ↓
       Query.setState({ fetchStatus: 'fetching' })
           ↓
       Query.notify() → notifies observers
           ↓
       QueryObserver.onQueryUpdate() → creates new result
           ↓
       Compares { data: undefined, isLoading: true }
       with previous (undefined)
           ↓
       Changed! → calls listener()
           ↓
       useSyncExternalStore detects change
           ↓
       Component re-renders
           ↓
       Shows "Loading..."
           ↓
       ... fetch completes ...
           ↓
       Query.setState({ data: [...], status: 'success' })
           ↓
       Query.notify()
           ↓
       Observer compares { data: [...], isLoading: false }
           ↓
       Changed! → notify React
           ↓
       Component re-renders
           ↓
       Shows user list

⚡ Performance Optimizations {#performance-optimizations}

1. Structural Sharing

Prevents unnecessary re-renders by reusing unchanged references.

// Old data
const oldData = { users: [{ id: 1, name: 'John' }] }

// New data (same content)
const newData = { users: [{ id: 1, name: 'John' }] }

// After structural sharing
oldData.users[0] === newData.users[0]  // true!
// React component using users[0] won't re-render

2. Batched Notifications

Multiple state changes → single render.

// Inside NotifyManager
class NotifyManager {
  batch(callback) {
    // Collect all notifications
    this.isBatching = true
    callback()
    this.isBatching = false

    // Flush once
    this.flush()
  }

  schedule(listener) {
    if (this.isBatching) {
      // Queue it
      this.queue.add(listener)
    } else {
      // Execute immediately
      listener()
    }
  }

  flush() {
    // Execute all queued notifications
    this.queue.forEach(listener => listener())
    this.queue.clear()
  }
}

Result:

// Multiple updates
query.setState({ fetchStatus: 'fetching' })
query.setState({ data: [...] })
query.setState({ status: 'success' })

// Only ONE React render at the end!

3. Property Tracking

Only re-render when accessed properties change.

const { data } = useQuery(['users'], fetchUsers)

// Tracked: ['data']
// Ignores changes to: isLoading, error, isFetching, etc.

4. Fetch Deduplication

Same query requested multiple times → single network request.

// 10 components mount simultaneously
function Component() {
  useQuery(['users'], fetchUsers)
}

// Only 1 network request!
// All components share the same Query.promise

🧠 Mental Models {#mental-models}

Model 1: Query as Database Row

Query = Row in database
QueryKey = Primary key
QueryCache = Database table
QueryObserver = Database subscription

Model 2: Pub/Sub Pattern

Query = Publisher
QueryObserver = Subscriber
Query.notify() = Publish event
Observer.onQueryUpdate() = Handle event

Model 3: React Integration

React Query = External store
useSyncExternalStore = React's bridge to external world
QueryObserver = Adapter that speaks React
Query = Pure async state machine

🎯 Key Takeaways

Architecture:

Layered design - Clean separation of concerns
Framework agnostic - Core logic independent of React
Observer pattern - Fine-grained subscriptions
useSyncExternalStore - Safe concurrent rendering

Flow:

Component calls useQuery
Creates QueryObserver (bridge)
Subscribes via useSyncExternalStore
Observer gets/creates Query from cache
Query fetches if needed
State changes notify observers
Observers diff and notify React
React re-renders component

Optimizations:

Structural sharing - Reuse unchanged references
Property tracking - Only re-render when needed
Batched notifications - Multiple updates → single render
Fetch deduplication - Share promises

📌 Final Thought

React Query's architecture is brilliant because:

✅ Separation of concerns - Each layer has clear responsibility

✅ Framework agnostic - Core can work with any framework

✅ Performance first - Smart diffing and batching

✅ Concurrent safe - Uses React 18's best practices

✅ Developer friendly - Simple API, complex internals

Understanding this architecture helps you:

Debug effectively
Optimize performance
Build advanced patterns
Interview confidently
Appreciate the engineering

🚀 Next Steps

Read useSyncExternalStore RFC
Explore React Query source code
Build custom QueryObserver
Profile with React DevTools Profiler
Contribute to React Query

💡 Pro Tips

Deepen your understanding:

Study the QueryObserver source
Build a mini React Query clone
Profile your app's re-renders
Use React DevTools Profiler

🤝 Let's Connect

Found this helpful?

❤️ Save for future reference
🔄 Share with your team
💬 Ask questions in comments
🐦 Follow for more deep dives

What part of the architecture surprised you most? Comment below! 👇

🔗 GitHub Repository:

https://github.com/TanStack/query

Happy architecting! 🎯

Tags: #react #tanstack #reactquery #javascript #webdev #architecture #usesyncexternalstore #performance

Mastering QueryCache — The Database Layer of React Query

Munna Thakur — Sat, 14 Feb 2026 09:29:34 +0000

If QueryClient is the brain, then QueryCache is the database layer that stores everything.

This is where:

✅ All queries are stored
✅ State is maintained
✅ Observers are attached
✅ Garbage collection is tracked
✅ Fetch deduplication happens

Let's understand QueryCache at the internal engine level 🔥

From @tanstack/react-query

📋 Table of Contents

What is QueryCache?
QueryCache Structure
Query Object Internals
Complete Query Lifecycle
QueryCache Responsibilities
Advanced Concepts
QueryCache vs QueryClient
Internal Event System
Real-World Insights
Performance Characteristics

⚡ Quick Summary

TL;DR: QueryCache is the internal database that:

✅ Stores all Query instances as a hash map

✅ Manages query state machines

✅ Coordinates observers and notifications

✅ Handles fetch deduplication

✅ Tracks garbage collection

✅ Enables structural sharing

✅ Powers DevTools integration

Length: ~25 min read | Level: Advanced

📦 Installation

npm install @tanstack/react-query

🗄️ What is QueryCache? {#what-is-querycache}

Simple Definition:

QueryCache = Internal Database + State Store + Observer Registry

Simplified Internal Structure:

class QueryCache {
  queries: Query[]           // All Query instances
  queriesMap: Map           // Fast lookup by hash
  config: QueryCacheConfig  // Configuration
  listeners: Set<Listener>  // Global subscribers
}

Real Implementation:

QueryCache maintains an indexed collection:

Map<queryHash, Query>

Key: Stable hash of queryKey
Value: Complete Query state machine

Key Point:

QueryCache is framework-agnostic.

It doesn't know about React. React components are just observers.

🏗 QueryCache Structure {#querycache-structure}

How Queries are Stored:

// User writes:
useQuery({ queryKey: ['users', 123] })

// Internally becomes:
{
  queryHash: '["users",123]',
  query: Query {
    queryKey: ['users', 123],
    state: { data, error, status, ... },
    observers: Set<QueryObserver>,
    retryer: Retryer,
    // ... more
  }
}

Visual Representation:

QueryCache
├── Map<queryHash, Query>
│   ├── '["users"]' → Query { state, observers, retryer }
│   ├── '["user",1]' → Query { state, observers, retryer }
│   ├── '["posts"]' → Query { state, observers, retryer }
│   └── ...
│
└── listeners: Set<Listener>
    ├── DevTools
    ├── Custom Logger
    └── ...

🔍 Query Object Internals {#query-object-internals}

What is a Query?

Each entry in QueryCache is a full Query state machine.

Internal Structure:

class Query {
  // Identification
  queryKey: QueryKey              // Original key: ['users', 123]
  queryHash: string               // Stable hash: '["users",123]'

  // State
  state: QueryState               // Current state

  // Observers
  observers: Set<QueryObserver>   // Connected components

  // Fetch Control
  retryer: Retryer               // Retry logic
  promise: Promise               // Current fetch promise

  // Lifecycle
  gcTimeout: NodeJS.Timeout      // Garbage collection timer

  // Options
  options: QueryOptions          // Configuration
}

Let's explore each property:

1. `queryKey`

The original array you pass:

queryKey: ['users', userId, { status: 'active' }]

Why stored:

Needed for matching filters
Used in callbacks
Reference for developers

2. `queryHash`

A stable string hash of queryKey.

// Input
queryKey: ['users', 123]

// Output
queryHash: '["users",123]'

Why needed?

Arrays can't be used directly as Map keys reliably:

// These are different references
['users', 1] !== ['users', 1]

// But same hash
hash(['users', 1]) === hash(['users', 1])

Hash function:

function hashQueryKey(queryKey: QueryKey): string {
  return JSON.stringify(queryKey, (_, val) =>
    isPlainObject(val)
      ? Object.keys(val)
          .sort()
          .reduce((result, key) => {
            result[key] = val[key]
            return result
          }, {} as any)
      : val
  )
}

This ensures:

✅ Stable hashing
✅ Order-independent for objects
✅ Fast lookup

3. `state` (Most Important)

The actual server state:

state: {
  data: any,                    // Query result
  dataUpdatedAt: number,        // Last successful fetch timestamp
  error: Error | null,          // Error object
  errorUpdatedAt: number,       // Last error timestamp
  fetchStatus: 'idle' | 'fetching' | 'paused',
  status: 'pending' | 'error' | 'success',
  fetchFailureCount: number,    // Failed attempts
  fetchFailureReason: Error,    // Last failure reason
  isInvalidated: boolean        // Marked stale by invalidation
}

This is pure server state - no React-specific data.

State machine:

pending → fetching → success
                  ↘ error

4. `observers`

Set of QueryObserver instances.

observers: Set<QueryObserver>

What is a QueryObserver?

Each component that calls useQuery creates a QueryObserver:

function UserList() {
  const { data } = useQuery({ queryKey: ['users'] })
  // Creates QueryObserver that subscribes to Query
}

Why a Set?

Multiple components can use same query
Each gets its own observer
Query notifies all observers when state changes

Example:

// Component A
function ComponentA() {
  useQuery({ queryKey: ['users'] })  // Observer 1
}

// Component B  
function ComponentB() {
  useQuery({ queryKey: ['users'] })  // Observer 2
}

// Same Query, two observers
Query {
  queryKey: ['users'],
  observers: Set([Observer1, Observer2])
}

5. `retryer`

Active fetch controller.

retryer: Retryer {
  continue: () => void,
  cancel: () => void,
  cancelRetry: () => void,
  continueRetry: () => void
}

What it handles:

✅ Retry logic
✅ Exponential backoff
✅ Cancellation
✅ Pause/Resume

Exponential backoff example:

// Attempt 0: 1s
// Attempt 1: 2s  
// Attempt 2: 4s
// Attempt 3: 8s
// Capped at 30s

6. `promise`

Current fetch promise.

promise: Promise<TData> | null

Why stored?

Fetch deduplication!

If same query is requested multiple times:

First request → creates promise
Subsequent requests → return same promise

// ComponentA and ComponentB mount simultaneously
function ComponentA() {
  useQuery({ queryKey: ['users'] })  // Creates fetch
}

function ComponentB() {
  useQuery({ queryKey: ['users'] })  // Reuses same fetch!
}

// Only ONE network request

Behind the scenes:

class Query {
  fetch() {
    // Already fetching?
    if (this.promise) {
      return this.promise  // Reuse!
    }

    // Start new fetch
    this.promise = this.executeFetch()
    return this.promise
  }
}

7. `gcTimeout`

Garbage collection timer reference.

gcTimeout: NodeJS.Timeout | null

How it works:

// When query becomes inactive (no observers)
onObserverRemoved() {
  if (this.observers.size === 0) {
    // Start GC timer
    this.gcTimeout = setTimeout(() => {
      queryCache.remove(this)
    }, this.options.gcTime)
  }
}

Default gcTime: 5 minutes

🔄 Complete Query Lifecycle {#complete-query-lifecycle}

Let's trace what happens when you call useQuery:

useQuery({ queryKey: ['users'], queryFn: fetchUsers })

Step 1: Build or Get Query

QueryClient calls:

queryCache.build(queryKey, options)

Logic:

build(queryKey, options) {
  // 1. Generate hash
  const queryHash = hashQueryKey(queryKey)

  // 2. Existing query?
  let query = this.queriesMap.get(queryHash)

  // 3. Create if missing
  if (!query) {
    query = new Query({
      queryCache: this,
      queryKey,
      queryHash,
      options
    })
    this.queriesMap.set(queryHash, query)
  }

  return query
}

Result: Query instance (new or existing)

Step 2: Observer Attach

Component mount:

const observer = new QueryObserver(queryClient, options)
query.addObserver(observer)

Inside Query:

addObserver(observer) {
  this.observers.add(observer)

  // Query is now active
  this.clearGcTimeout()

  // Notify observer of current state
  observer.onQueryUpdate()
}

Query status changes:

inactive → active

Step 3: Fetch Trigger

Decision logic:

// Should we fetch?
const shouldFetch = 
  !this.state.data ||           // No data
  this.isStale() ||             // Data is stale
  options.refetchOnMount        // Force refetch

if (shouldFetch) {
  query.fetch()
}

If yes, fetch:

fetch() {
  // Create retryer
  this.retryer = new Retryer({
    fn: this.options.queryFn,
    retry: this.options.retry,
    retryDelay: this.options.retryDelay
  })

  // Store promise (for deduplication)
  this.promise = this.retryer.start()

  // Update state
  this.setState({
    fetchStatus: 'fetching'
  })

  return this.promise
}

Step 4: State Update

Fetch resolves:

this.promise
  .then((data) => {
    // Success!
    this.setState({
      data,
      dataUpdatedAt: Date.now(),
      status: 'success',
      fetchStatus: 'idle',
      error: null
    })
  })
  .catch((error) => {
    // Error!
    this.setState({
      error,
      errorUpdatedAt: Date.now(),
      status: 'error',
      fetchStatus: 'idle'
    })
  })

State update triggers observer notification.

Step 5: Observer Notify

QueryCache doesn't trigger renders directly.

Instead:

setState(newState) {
  // Update state
  this.state = { ...this.state, ...newState }

  // Notify all observers
  this.observers.forEach(observer => {
    observer.onQueryUpdate()
  })
}

Inside QueryObserver:

onQueryUpdate() {
  // Diff state
  const hasChanged = this.hasPropsChanged()

  if (hasChanged) {
    // Trigger React re-render
    this.notify()
  }
}

Only re-renders if tracked properties changed!

Step 6: Component Unmount

Cleanup:

// Component unmounts
observer.destroy()

// Inside observer
destroy() {
  query.removeObserver(this)
}

Inside Query:

removeObserver(observer) {
  this.observers.delete(observer)

  // No more observers?
  if (this.observers.size === 0) {
    // Query becomes inactive
    this.scheduleGc()
  }
}

Step 7: Garbage Collection

After gcTime:

scheduleGc() {
  this.clearGcTimeout()

  this.gcTimeout = setTimeout(() => {
    // Remove from cache
    queryCache.remove(this)
  }, this.options.gcTime || 5 * 60 * 1000)
}

Memory freed.

🎯 QueryCache Responsibilities {#querycache-responsibilities}

1. Query Registration

Creating and storing queries.

queryCache.build(queryKey, options)

2. Fast Lookup

O(1) retrieval via hash:

const query = queryCache.find(queryKey)

3. Matching & Filtering

Powers these QueryClient methods:

queryClient.invalidateQueries({ queryKey: ['users'] })
queryClient.refetchQueries({ type: 'active' })
queryClient.removeQueries({ stale: true })

Behind the scenes:

findAll(filters) {
  const queries = Array.from(this.queriesMap.values())

  return queries.filter(query => {
    // Match queryKey
    if (filters.queryKey) {
      if (!partialMatchKey(query.queryKey, filters.queryKey)) {
        return false
      }
    }

    // Match type
    if (filters.type === 'active' && query.observers.size === 0) {
      return false
    }

    // Match stale
    if (filters.stale && !query.isStale()) {
      return false
    }

    return true
  })
}

4. Global Event Listeners

QueryCache maintains subscribers:

listeners: Set<Listener>

DevTools subscribes here:

queryCache.subscribe((event) => {
  if (event.type === 'added') {
    devtools.onQueryAdded(event.query)
  }
})

Events:

added - New query created
removed - Query garbage collected
updated - Query state changed

5. Batch Notifications

Doesn't notify directly:

notify(query) {
  // Use notification manager for batching
  notifyManager.batch(() => {
    // Notify listeners
    this.listeners.forEach(listener => {
      listener({ query })
    })

    // Notify query observers
    query.observers.forEach(observer => {
      observer.onQueryUpdate()
    })
  })
}

Result:

Multiple updates → single React render
Integrates with React batching

🧠 Advanced Concepts {#advanced-concepts}

1. Stale System ⏰

QueryCache doesn't run timers.

Instead:

isStale() {
  // Calculate on-demand
  const now = Date.now()
  const age = now - this.state.dataUpdatedAt
  return age > this.options.staleTime
}

Why this approach?

No active timers to manage
Lower memory overhead
Lazy evaluation

2. Invalidation Logic 🔄

When you call:

queryClient.invalidateQueries(['users'])

Behind the scenes:

// 1. Mark query as invalidated
query.invalidate()

// Inside Query
invalidate() {
  this.state.isInvalidated = true

  // Has active observers?
  if (this.observers.size > 0) {
    // Schedule refetch
    this.fetch()
  }
  // Otherwise, just stays marked stale
}

Important:

Invalidation ≠ immediate fetch

It marks stale first, refetches only if active.

3. Structural Sharing 🧬

Optimizes re-renders by reusing unchanged references.

When data updates:

setData(newData) {
  // Deep comparison
  const sharedData = replaceEqualDeep(
    this.state.data,
    newData
  )

  this.state.data = sharedData
}

How it works:

function replaceEqualDeep(prev, next) {
  if (prev === next) return prev

  const prevType = typeof prev
  const nextType = typeof next

  if (prevType !== nextType) return next

  if (Array.isArray(prev) && Array.isArray(next)) {
    // Check each item
    return prev.map((item, index) => 
      replaceEqualDeep(item, next[index])
    )
  }

  if (isPlainObject(prev) && isPlainObject(next)) {
    // Check each property
    const result = { ...prev }
    Object.keys(next).forEach(key => {
      result[key] = replaceEqualDeep(prev[key], next[key])
    })
    return result
  }

  return next
}

Result:

Unchanged branches keep same reference
React skips re-rendering unchanged parts

Example:

// Old data
const oldUsers = [
  { id: 1, name: 'John' },
  { id: 2, name: 'Jane' }
]

// New data (same content)
const newUsers = [
  { id: 1, name: 'John' },
  { id: 2, name: 'Jane' }
]

// After structural sharing
oldUsers === newUsers  // false (different references)
// But: oldUsers[0] === newUsers[0]  // true! (reused)

4. Fetch Deduplication 🔁

Same query, multiple components:

function ComponentA() {
  useQuery({ queryKey: ['users'] })
}

function ComponentB() {
  useQuery({ queryKey: ['users'] })
}

function ComponentC() {
  useQuery({ queryKey: ['users'] })
}

Without deduplication: 3 network requests

With deduplication: 1 network request

How it works:

fetch() {
  // Already fetching?
  if (this.promise) {
    return this.promise  // Share promise!
  }

  // Start new fetch
  this.promise = this.executeFetch()
    .finally(() => {
      // Clear after completion
      this.promise = null
    })

  return this.promise
}

All observers await the same promise!

5. Cancellation System ❌

When you call:

queryClient.cancelQueries(['users'])

Behind the scenes:

cancel() {
  // Cancel retry logic
  this.retryer?.cancel()

  // Abort network request
  this.abortController?.abort()

  // Clear promise
  this.promise = null
}

If queryFn supports AbortSignal:

queryFn: ({ signal }) => 
  fetch('/api/users', { signal })

Then fetch is truly aborted!

🆚 QueryCache vs QueryClient {#querycache-vs-queryclient}

Clear Separation:

Layer	Responsibility	Example
QueryClient	Orchestrator	`queryClient.invalidateQueries()`
QueryCache	Data store	Stores Query instances
Query	State machine	Manages individual query lifecycle
Observer	React bridge	Connects components to queries

Architecture Diagram:

User Component (React)
    ↓
useQuery (Hook)
    ↓
QueryObserver (Bridge)
    ↓
Query (State Machine)
    ↓
QueryCache (Database)
    ↓
QueryClient (Orchestrator)

Why this separation?

Framework agnostic:

QueryCache has no React dependencies
Can be used with Vue, Angular, Svelte
React is just one observer implementation

📡 Internal Event System {#internal-event-system}

QueryCache emits events:

class QueryCache extends Subscribable {
  notify(event) {
    // Notify all listeners
    this.listeners.forEach(listener => {
      listener(event)
    })
  }
}

Event Types:

type QueryCacheNotifyEvent = 
  | { type: 'added'; query: Query }
  | { type: 'removed'; query: Query }
  | { type: 'updated'; query: Query; action: UpdateAction }

Who subscribes?

1. DevTools:

queryCache.subscribe((event) => {
  devtoolsPanel.updateQueryList()
})

2. Custom Loggers:

queryCache.subscribe((event) => {
  console.log('Query event:', event.type, event.query.queryKey)
})

3. Analytics:

queryCache.subscribe((event) => {
  if (event.type === 'added') {
    analytics.track('Query Created', {
      queryKey: event.query.queryKey
    })
  }
})

💡 Real-World Insights {#real-world-insights}

1. QueryCache is NOT React State

Important concept:

QueryCache ≠ React State
QueryCache = Independent Async Store
React = Observer

Why this matters:

✅ No prop drilling needed

✅ No context cascade re-renders

✅ Fine-grained subscriptions

✅ Works with React Concurrent Mode

✅ No tearing issues

2. Memory Management

Without QueryCache:

Manual cache management
Memory leaks
No automatic cleanup

With QueryCache:

Automatic GC
Configurable gcTime
Memory-efficient

Example:

// Query becomes inactive
query.observers.size === 0

// After 5 minutes (default gcTime)
queryCache.remove(query)

// Memory freed

3. Why Hash-Based Storage?

Problem:

const map = new Map()
map.set(['users', 1], data1)
map.set(['users', 1], data2)  // Different key! (new array reference)
map.size  // 2 (should be 1!)

Solution:

const queryCache = new Map()
const hash1 = hash(['users', 1])  // '["users",1]'
const hash2 = hash(['users', 1])  // '["users",1]'
hash1 === hash2  // true!

queryCache.set(hash1, query1)
queryCache.set(hash2, query2)  // Overwrites query1 ✅
queryCache.size  // 1 (correct!)

4. Observer Pattern Benefits

Traditional approach (Redux):

// Component connects to entire state
const state = useSelector(state => state)
// Re-renders on ANY state change

QueryCache approach:

// Component subscribes to specific query
const { data } = useQuery(['users'])
// Re-renders only when THIS query changes

Result:

Fewer re-renders
Better performance
Isolated updates

⚡ Performance Characteristics {#performance-characteristics}

1. Lookup Performance

O(1) hash-based lookup:

// Super fast
const query = queryCache.get(queryHash)

2. Memory Efficiency

Automatic garbage collection:

// Inactive query after 5 min → removed
// No memory leaks

3. Render Optimization

Structural sharing:

// Unchanged data → same reference → no re-render

Observer diffing:

// Only notify if tracked props changed

4. Network Efficiency

Fetch deduplication:

// 10 components, same query → 1 network request

🎯 Key Takeaways

QueryCache is:

✅ Database Layer - Stores all Query instances
✅ Hash Map - Fast O(1) lookups
✅ Event Emitter - Powers DevTools and monitoring
✅ GC Manager - Automatic memory cleanup
✅ Dedup Engine - Prevents duplicate fetches
✅ Framework Agnostic - No React dependencies

How It Powers React Query:

Centralized storage - Single source of truth
Smart caching - Automatic lifecycle management
Observer pattern - Fine-grained subscriptions
Structural sharing - Optimized re-renders
Fetch deduplication - Network efficiency

Mental Model:

Think of QueryCache as:
- PostgreSQL (if React Query was a backend)
- IndexedDB (for browser persistence)
- Redis (for caching layer)

It's the foundational data store that everything builds on.

📌 Final Thought

QueryCache is the hidden engine that makes React Query magical.

Understanding it helps you:

✅ Debug effectively
✅ Optimize performance
✅ Build advanced patterns
✅ Understand internals
✅ Interview confidently

Most developers use React Query without understanding QueryCache.

Now you're in the top 1% who truly understand how it works. 🚀

🚀 Next Steps

Read TanStack Query source code
Build custom QueryCache visualizer
Experiment with QueryCache events
Create custom persistence layer
Contribute to React Query

💡 Pro Tips

Explore these advanced topics:

Query dehydration/hydration for SSR
Custom QueryCache implementations
Building plugins with QueryCache events
Memory profiling with Chrome DevTools

🤝 Let's Connect

Found this helpful?

❤️ Save for future reference
🔄 Share with your team
💬 Ask questions in comments
🐦 Follow for more deep dives

What QueryCache concept blew your mind? Comment below! 👇

📚 Official Docs:

https://tanstack.com/query/latest/docs/react/overview

Happy caching! 🎯

Tags: #react #tanstack #reactquery #javascript #webdev #frontend #querycache #internals