<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <id>https://billyokeyo.dev/</id>
  <title>Billy Okeyo</title>
  <subtitle>Practical articles on backend reliability, frontend performance, and full-stack engineering. Learn distributed systems, browser rendering, and production-grade patterns beyond basic CRUD and UI.</subtitle>
  <updated>2026-09-11T06:20:29+00:00</updated>
  <author>
    <name>Billy Okeyo</name>
    <uri>https://billyokeyo.dev/</uri>
  </author>
  <link rel="self" type="application/atom+xml" href="https://billyokeyo.dev/feed.xml"/>
  <link rel="alternate" type="text/html" hreflang="en"
    href="https://billyokeyo.dev/"/>
  <generator uri="https://jekyllrb.com/" version="4.4.1">Jekyll</generator>
  <rights> © 2026 Billy Okeyo </rights>
  <icon>https://billyokeyo.dev/assets/img/favicons/favicon.ico</icon>
  <logo>https://billyokeyo.dev/assets/img/favicons/favicon-96x96.png</logo>




  
  





  



  


  <entry>
    <title>Re-Renders Explained: What Actually Happens When Frontend State Changes</title>
    <link href="https://billyokeyo.dev/posts/re-renders/" rel="alternate" type="text/html" title="Re-Renders Explained: What Actually Happens When Frontend State Changes" />
    <published>2026-09-11T00:00:00+00:00</published>
  
    <updated>2026-09-11T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/re-renders/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/re-renders/"><![CDATA[<p>One of the most common pieces of advice in frontend development is:</p>

<blockquote>
  <p><strong>Avoid unnecessary re-renders.</strong></p>
</blockquote>

<p>You hear it when working with React, when discussing component performance, and when someone suggests <code>memo</code>, <code>useMemo</code>, or <code>useCallback</code>; eventually, it can start sounding as though re-rendering is inherently bad, but it isn’t.</p>

<p>Re-rendering is how modern UI frameworks keep the screen synchronized with application state.</p>

<p>Consider a simple counter:</p>

<pre><code class="language-tsx">function Counter() {
  const [count, setCount] = useState(0);

  return (
    &lt;button onClick={() =&gt; setCount(count + 1)}&gt;
      Count: {count}
    &lt;/button&gt;
  );
}
</code></pre>

<p>The browser initially displays:</p>

<pre><code class="language-text">Count: 0
</code></pre>

<p>Then the user clicks the button.</p>

<pre><code class="language-text">Count: 0
    │
    │ click
    ▼
setCount(1)
</code></pre>

<p>The component re-renders.</p>

<p>Eventually, the browser displays:</p>

<pre><code class="language-text">Count: 1
</code></pre>

<p>That process sounds simple, but there are several steps hidden in between.</p>

<p>React doesn’t immediately replace the entire DOM.</p>

<p>The browser doesn’t repaint the entire page just because a state variable changed.</p>

<p>Instead, the framework performs work to determine what the UI <strong>should now look like</strong>, compares that result with what existed before, and updates only the parts of the real DOM that actually changed.</p>

<p>A simplified mental model looks like this:</p>

<pre><code class="language-text">State Change
    │
    ▼
Component Re-renders
    │
    ▼
New UI Description
    │
    ▼
Compare With Previous Result
    │
    ▼
Determine Actual Changes
    │
    ▼
Update DOM
    │
    ▼
Browser Rendering Pipeline
</code></pre>

<p>Understanding this process is important because it helps separate two ideas developers often confuse: <strong>React rendering</strong> and <strong>browser rendering</strong>, which are not the same thing.</p>

<hr />

<h2 id="react-rendering-is-not-browser-rendering">React Rendering Is Not Browser Rendering</h2>

<p>In the first article in this series, we explored the browser rendering pipeline:</p>

<pre><code class="language-text">DOM
 │
 ▼
Style
 │
 ▼
Layout
 │
 ▼
Paint
 │
 ▼
Composite
 │
 ▼
Pixels
</code></pre>

<p>That process belongs to the browser.</p>

<p>React’s rendering happens before that.</p>

<p>React decides <strong>what the DOM should look like</strong>.</p>

<p>The browser decides <strong>how that DOM becomes pixels</strong>.</p>

<p>Conceptually:</p>

<pre><code class="language-text">Application State
      │
      ▼
     React
      │
      ▼
DOM Changes
      │
      ▼
   Browser
      │
      ▼
Layout / Paint / Composite
</code></pre>

<p>This distinction matters.</p>

<p>A React component can re-render without causing any DOM update at all.</p>

<p>And if the DOM doesn’t change, the browser may have very little visual work to do.</p>

<hr />

<h2 id="what-happens-when-state-changes">What Happens When State Changes?</h2>

<p>Let’s use a slightly larger example.</p>

<pre><code class="language-tsx">function Profile() {
  const [name, setName] = useState("Billy");

  return (
    &lt;section&gt;
      &lt;h1&gt;Hello, {name}&lt;/h1&gt;

      &lt;button onClick={() =&gt; setName("William")}&gt;
        Change Name
      &lt;/button&gt;
    &lt;/section&gt;
  );
}
</code></pre>

<p>Initially, React produces a UI description conceptually similar to:</p>

<pre><code class="language-text">section
├── h1
│   └── "Hello, Billy"
└── button
    └── "Change Name"
</code></pre>

<p>After:</p>

<pre><code class="language-tsx">setName("William");
</code></pre>

<p>React renders the component again.</p>

<p>Now the result looks like:</p>

<pre><code class="language-text">section
├── h1
│   └── "Hello, William"
└── button
    └── "Change Name"
</code></pre>

<p>Most of the structure is identical.</p>

<p>Only one text value changed.</p>

<p>So React does not need to rebuild the entire DOM.</p>

<p>It only needs to update:</p>

<pre><code class="language-text">"Hello, Billy"
       ↓
"Hello, William"
</code></pre>

<p>The process can be understood as three broad stages:</p>

<pre><code class="language-text">Render
   │
   ▼
Reconciliation
   │
   ▼
Commit
</code></pre>

<p>Let’s look at each one.</p>

<hr />

<h2 id="the-render-phase">The Render Phase</h2>

<p>When a component re-renders, React executes the component function again.</p>

<p>That point is worth emphasizing.</p>

<p>Consider:</p>

<pre><code class="language-tsx">function Counter() {
  console.log("Counter rendered");

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

  return &lt;p&gt;{count}&lt;/p&gt;;
}
</code></pre>

<p>Whenever React renders <code>Counter</code>, the function executes.</p>

<p>That means:</p>

<pre><code class="language-tsx">console.log("Counter rendered");
</code></pre>

<p>runs again.</p>

<p>So rendering does <strong>not</strong> mean React simply reuses the previous function result.</p>

<p>The component runs again to determine what the UI should look like for the current state and props.</p>

<p>Conceptually:</p>

<pre><code class="language-text">State = 0

Counter()
   │
   ▼
&lt;p&gt;0&lt;/p&gt;
</code></pre>

<p>Then:</p>

<pre><code class="language-text">State = 1

Counter()
   │
   ▼
&lt;p&gt;1&lt;/p&gt;
</code></pre>

<p>React now has a new description of the UI.</p>

<p>But no DOM changes necessarily happened yet.</p>

<p>That distinction becomes very important.</p>

<hr />

<h2 id="reconciliation">Reconciliation</h2>

<p>Once React has the new result, it compares it with the previous one.</p>

<p>This process is known as <strong>reconciliation</strong>.</p>

<p>Suppose before:</p>

<pre><code class="language-tsx">&lt;div&gt;
  &lt;h1&gt;Products&lt;/h1&gt;
  &lt;p&gt;3 items&lt;/p&gt;
&lt;/div&gt;
</code></pre>

<p>and after:</p>

<pre><code class="language-tsx">&lt;div&gt;
  &lt;h1&gt;Products&lt;/h1&gt;
  &lt;p&gt;4 items&lt;/p&gt;
&lt;/div&gt;
</code></pre>

<p>The structure did not change.</p>

<p>The <code>div</code> still exists.</p>

<p>The <code>h1</code> is the same.</p>

<p>Only the paragraph text changed.</p>

<p>React can therefore conclude:</p>

<pre><code class="language-text">Keep div
Keep h1
Keep p
Update text
</code></pre>

<p>instead of:</p>

<pre><code class="language-text">Delete everything
Recreate everything
</code></pre>

<p>This is the heart of reconciliation.</p>

<p>React is determining the minimum DOM work needed to make the actual interface match the new component output.</p>

<hr />

<h2 id="the-commit-phase">The Commit Phase</h2>

<p>Once React knows what needs to change, it performs those mutations during the <strong>commit phase</strong>.</p>

<p>This is where the real DOM is updated.</p>

<p>So the flow becomes:</p>

<pre><code class="language-text">State Change
    │
    ▼
Render Phase
Component functions run
    │
    ▼
Reconciliation
Compare old and new
    │
    ▼
Commit Phase
Update actual DOM
</code></pre>

<p>Only after actual DOM changes occur does the browser potentially need to perform its own rendering work.</p>

<pre><code class="language-text">React Commit
     │
     ▼
DOM Changed
     │
     ▼
Browser
     │
     ├── Style?
     ├── Layout?
     ├── Paint?
     └── Composite?
</code></pre>

<p>This connects directly to everything we learned about reflow and repaint.</p>

<hr />

<h2 id="re-rendering-does-not-mean-dom-mutation">Re-Rendering Does Not Mean DOM Mutation</h2>

<p>This is one of the biggest misconceptions in React performance discussions.</p>

<p>Suppose:</p>

<pre><code class="language-tsx">function Greeting({ name }) {
  console.log("render");

  return &lt;h1&gt;Hello {name}&lt;/h1&gt;;
}
</code></pre>

<p>React may execute this component again.</p>

<p>But if:</p>

<pre><code class="language-text">name = "Billy"
</code></pre>

<p>both before and after the render, the resulting UI may be identical.</p>

<p>React can determine:</p>

<pre><code class="language-text">Previous: &lt;h1&gt;Hello Billy&lt;/h1&gt;

New:      &lt;h1&gt;Hello Billy&lt;/h1&gt;
</code></pre>

<p>No meaningful DOM change is required.</p>

<p>So:</p>

<pre><code class="language-text">Component Render
      ≠
DOM Update
</code></pre>

<p>And:</p>

<pre><code class="language-text">DOM Update
      ≠
Full Browser Repaint
</code></pre>

<p>These are separate stages.</p>

<p>That is why the statement:</p>

<blockquote>
  <p>“This component rendered again!”</p>
</blockquote>

<p>doesn’t automatically mean:</p>

<blockquote>
  <p>“We have a serious performance problem.”</p>
</blockquote>

<p>The cost depends on what happens during that render and what actual work follows.</p>

<hr />

<h2 id="why-child-components-re-render">Why Child Components Re-Render</h2>

<p>This is another area that confuses many developers.</p>

<p>Consider:</p>

<pre><code class="language-tsx">function App() {
  const [count, setCount] = useState(0);

  return (
    &lt;&gt;
      &lt;button onClick={() =&gt; setCount(count + 1)}&gt;
        Increment
      &lt;/button&gt;

      &lt;Header /&gt;
    &lt;/&gt;
  );
}
</code></pre>

<p><code>Header</code> doesn’t use <code>count</code>.</p>

<p>Yet when <code>App</code> re-renders, <code>Header</code> may also render again.</p>

<p>Why?</p>

<p>Because <code>Header</code> is part of the component tree produced by <code>App</code>.</p>

<p>Conceptually:</p>

<pre><code class="language-text">App re-renders
    │
    ├── Button
    │
    └── Header
</code></pre>

<p>React walks through that subtree to determine what the updated UI should look like.</p>

<p>Again, this doesn’t necessarily mean the DOM represented by <code>Header</code> changes.</p>

<p>The component can execute again while producing exactly the same result.</p>

<hr />

<h2 id="parent-re-render-does-not-mean-everything-changed">Parent Re-Render Does Not Mean Everything Changed</h2>

<p>Suppose:</p>

<pre><code class="language-tsx">function Header() {
  return (
    &lt;header&gt;
      &lt;h1&gt;My Store&lt;/h1&gt;
    &lt;/header&gt;
  );
}
</code></pre>

<p>Every time the parent renders, this may execute again.</p>

<p>But React compares:</p>

<pre><code class="language-text">Previous Header

&lt;header&gt;
  &lt;h1&gt;My Store&lt;/h1&gt;
&lt;/header&gt;
</code></pre>

<p>with:</p>

<pre><code class="language-text">New Header

&lt;header&gt;
  &lt;h1&gt;My Store&lt;/h1&gt;
&lt;/header&gt;
</code></pre>

<p>Nothing changed.</p>

<p>So no DOM mutation is required.</p>

<p>This is why React can tolerate far more component renders than developers often assume.</p>

<p>The framework is designed around the idea that rendering should generally be cheap.</p>

<p>Problems appear when rendering itself becomes expensive.</p>

<hr />

<h2 id="when-re-renders-actually-become-expensive">When Re-Renders Actually Become Expensive</h2>

<p>Imagine a component does this:</p>

<pre><code class="language-tsx">function Analytics({ transactions }) {
  const report = generateComplexReport(transactions);

  return &lt;ReportView report={report} /&gt;;
}
</code></pre>

<p>If <code>generateComplexReport()</code> processes hundreds of thousands of records, every render can become expensive.</p>

<p>Now suppose a parent re-renders frequently.</p>

<pre><code class="language-text">Parent changes
     │
     ▼
Analytics renders
     │
     ▼
Expensive calculation
</code></pre>

<p>Even if the resulting DOM doesn’t change, the expensive JavaScript already ran.</p>

<p>This is where unnecessary rendering becomes a real performance problem.</p>

<p>The issue isn’t:</p>

<pre><code class="language-text">DOM updated too much
</code></pre>

<p>It might instead be:</p>

<pre><code class="language-text">JavaScript executed too much
</code></pre>

<p>That connects directly to the Event Loop article.</p>

<p>Heavy component rendering occupies the main thread just like any other JavaScript.</p>

<hr />

<h2 id="a-simple-example-of-expensive-rendering">A Simple Example of Expensive Rendering</h2>

<p>Consider:</p>

<pre><code class="language-tsx">function ProductList({ products, search }) {
  const results = products
    .filter(product =&gt;
      product.name
        .toLowerCase()
        .includes(search.toLowerCase())
    )
    .sort((a, b) =&gt; a.price - b.price);

  return (
    &lt;ul&gt;
      {results.map(product =&gt; (
        &lt;li key={product.id}&gt;
          {product.name}
        &lt;/li&gt;
      ))}
    &lt;/ul&gt;
  );
}
</code></pre>

<p>For:</p>

<pre><code class="language-text">50 products
</code></pre>

<p>this probably doesn’t matter.</p>

<p>For:</p>

<pre><code class="language-text">500,000 products
</code></pre>

<p>it might.</p>

<p>Now imagine an unrelated state change causes the component to render repeatedly.</p>

<pre><code class="language-text">Theme toggled
     │
     ▼
Parent re-render
     │
     ▼
ProductList executes
     │
     ▼
Filter 500,000 products
     │
     ▼
Sort 500,000 products
</code></pre>

<p>Even if the product list itself didn’t actually change, substantial work occurred.</p>

<p>This is where memoization can help.</p>

<hr />

<h2 id="what-usememo-actually-does">What <code>useMemo</code> Actually Does</h2>

<p>Consider:</p>

<pre><code class="language-tsx">const filteredProducts = useMemo(() =&gt; {
  return products.filter(product =&gt;
    product.name.includes(search)
  );
}, [products, search]);
</code></pre>

<p>The goal of <code>useMemo</code> is not:</p>

<blockquote>
  <p>Make React faster.</p>
</blockquote>

<p>Its purpose is more specific.</p>

<p>It says:</p>

<blockquote>
  <p>Recalculate this value only when these dependencies change.</p>
</blockquote>

<p>Conceptually:</p>

<pre><code class="language-text">Render
  │
  ▼
Did products or search change?
      │
   ┌──┴───┐
   │      │
  Yes     No
   │      │
   ▼      ▼
Calculate  Reuse
</code></pre>

<p>If some unrelated state changes:</p>

<pre><code class="language-text">sidebarOpen
</code></pre>

<p>the component may still re-render.</p>

<p>But the expensive product filtering can be skipped.</p>

<p>This distinction is important.</p>

<p><code>useMemo</code> doesn’t necessarily prevent rendering.</p>

<p>It prevents recalculating a memoized result when dependencies haven’t changed.</p>

<hr />

<h2 id="do-not-memoize-everything">Do Not Memoize Everything</h2>

<p>After learning about <code>useMemo</code>, it’s tempting to do this:</p>

<pre><code class="language-tsx">const name = useMemo(() =&gt; {
  return `${firstName} ${lastName}`;
}, [firstName, lastName]);
</code></pre>

<p>But calculating:</p>

<pre><code class="language-javascript">`${firstName} ${lastName}`
</code></pre>

<p>is extremely cheap.</p>

<p>Now we’ve added:</p>

<pre><code class="language-text">Memoization logic
Dependency tracking
Additional code
Mental overhead
</code></pre>

<p>to avoid a trivial string concatenation.</p>

<p>Optimization itself has a cost.</p>

<p>A useful rule is:</p>

<blockquote>
  <p><strong>Memoize expensive computations or values whose identity meaningfully matters, not every expression in your component.</strong></p>
</blockquote>

<p>Measure before making everything more complicated.</p>

<hr />

<h2 id="reactmemo"><code>React.memo</code></h2>

<p>Now suppose the expensive work happens inside a child component.</p>

<pre><code class="language-tsx">function Dashboard() {
  const [sidebarOpen, setSidebarOpen] = useState(false);

  return (
    &lt;&gt;
      &lt;Sidebar open={sidebarOpen} /&gt;
      &lt;ExpensiveChart /&gt;
    &lt;/&gt;
  );
}
</code></pre>

<p>When <code>sidebarOpen</code> changes:</p>

<pre><code class="language-text">Dashboard re-renders
      │
      ├── Sidebar
      └── ExpensiveChart
</code></pre>

<p>But <code>ExpensiveChart</code> receives no changing props.</p>

<p>We may wrap it:</p>

<pre><code class="language-tsx">const ExpensiveChart = React.memo(function ExpensiveChart() {
  return &lt;Chart /&gt;;
});
</code></pre>

<p>Now React can compare its props and potentially skip rendering the component when those props haven’t changed.</p>

<p>Conceptually:</p>

<pre><code class="language-text">Parent re-renders
      │
      ▼
Check child props
      │
   ┌──┴───┐
   │      │
Changed  Same
   │      │
   ▼      ▼
Render   Skip
</code></pre>

<p>Again, the point isn’t that every child should use <code>React.memo</code>.</p>

<p>It is useful when:</p>

<ul>
  <li>The component renders frequently</li>
  <li>Rendering is meaningfully expensive</li>
  <li>Its props often remain unchanged</li>
</ul>

<p>Otherwise, the additional complexity may provide little benefit.</p>

<hr />

<h2 id="why-reactmemo-sometimes-doesnt-work">Why <code>React.memo</code> Sometimes Doesn’t Work</h2>

<p>Consider:</p>

<pre><code class="language-tsx">const ProductCard = React.memo(function ProductCard({
  product,
  onSelect
}) {
  return (
    &lt;button onClick={() =&gt; onSelect(product.id)}&gt;
      {product.name}
    &lt;/button&gt;
  );
});
</code></pre>

<p>The parent does:</p>

<pre><code class="language-tsx">&lt;ProductCard
  product={product}
  onSelect={(id) =&gt; setSelectedId(id)}
/&gt;
</code></pre>

<p>Every parent render creates a new function:</p>

<pre><code class="language-javascript">(id) =&gt; setSelectedId(id)
</code></pre>

<p>Even though the function does the same thing, its identity is new.</p>

<p>Conceptually:</p>

<pre><code class="language-text">Previous render:

onSelect = Function A

New render:

onSelect = Function B
</code></pre>

<p>So from a shallow prop-comparison perspective:</p>

<pre><code class="language-text">Function A !== Function B
</code></pre>

<p>and the memoized child may render again.</p>

<p>This is where <code>useCallback</code> enters the picture.</p>

<hr />

<h2 id="what-usecallback-actually-does">What <code>useCallback</code> Actually Does</h2>

<p>You might write:</p>

<pre><code class="language-tsx">const handleSelect = useCallback((id) =&gt; {
  setSelectedId(id);
}, []);
</code></pre>

<p>Then:</p>

<pre><code class="language-tsx">&lt;ProductCard
  product={product}
  onSelect={handleSelect}
/&gt;
</code></pre>

<p>Now the function reference can remain stable across renders unless its dependencies change.</p>

<p>Conceptually:</p>

<pre><code class="language-text">Render 1
handleSelect = Function A

Render 2
handleSelect = Function A

Render 3
handleSelect = Function A
</code></pre>

<p>This can help when function identity matters, especially when passing callbacks into memoized child components.</p>

<p>But again:</p>

<blockquote>
  <p><strong><code>useCallback</code> does not magically make a function faster.</strong></p>
</blockquote>

<p>It memoizes the function reference.</p>

<p>If nothing depends on that identity, it may provide no practical benefit.</p>

<hr />

<h2 id="usememo-vs-usecallback"><code>useMemo</code> vs <code>useCallback</code></h2>

<p>The difference is simple.</p>

<p><code>useMemo</code> memoizes a <strong>value</strong>.</p>

<pre><code class="language-tsx">const total = useMemo(() =&gt; {
  return calculateTotal(items);
}, [items]);
</code></pre>

<p><code>useCallback</code> memoizes a <strong>function reference</strong>.</p>

<pre><code class="language-tsx">const handleSave = useCallback(() =&gt; {
  save(items);
}, [items]);
</code></pre>

<p>Conceptually:</p>

<pre><code class="language-text">useMemo
   │
   ▼
Remember result


useCallback
   │
   ▼
Remember function
</code></pre>

<p>Both are performance tools.</p>

<p>Neither should automatically appear everywhere.</p>

<hr />

<h2 id="object-identity-causes-similar-problems">Object Identity Causes Similar Problems</h2>

<p>Suppose:</p>

<pre><code class="language-tsx">&lt;Chart
  options={{
    showLegend: true,
    responsive: true
  }}
/&gt;
</code></pre>

<p>Every render creates a new object.</p>

<pre><code class="language-text">Render 1 → Object A

Render 2 → Object B
</code></pre>

<p>Even though:</p>

<pre><code class="language-text">Object A contents
      =
Object B contents
</code></pre>

<p>their references differ.</p>

<p>If <code>Chart</code> is memoized and relies on shallow prop comparison, it may still render again.</p>

<p>One solution can be:</p>

<pre><code class="language-tsx">const options = useMemo(() =&gt; ({
  showLegend: true,
  responsive: true
}), []);

&lt;Chart options={options} /&gt;
</code></pre>

<p>Now the object identity remains stable.</p>

<p>But the same warning applies:</p>

<p>Only optimize where the identity actually causes meaningful work.</p>

<hr />

<h2 id="keys-and-reconciliation">Keys and Reconciliation</h2>

<p>Keys are another important part of how React reasons about changes.</p>

<p>Consider:</p>

<pre><code class="language-tsx">{products.map(product =&gt; (
  &lt;ProductCard
    key={product.id}
    product={product}
  /&gt;
))}
</code></pre>

<p>The key helps React identify which item corresponds to which previous item.</p>

<p>Suppose:</p>

<pre><code class="language-text">Before

A
B
C
</code></pre>

<p>then:</p>

<pre><code class="language-text">After

A
X
B
C
</code></pre>

<p>With stable keys, React can understand:</p>

<pre><code class="language-text">A → same
X → new
B → same
C → same
</code></pre>

<p>Without useful identity, React has a harder time reasoning about which items moved, appeared, or disappeared.</p>

<p>This matters not only for performance but also for preserving component state correctly.</p>

<hr />

<h2 id="why-array-index-keys-can-be-problematic">Why Array Index Keys Can Be Problematic</h2>

<p>Consider:</p>

<pre><code class="language-tsx">items.map((item, index) =&gt; (
  &lt;Row key={index} item={item} /&gt;
));
</code></pre>

<p>Suppose:</p>

<pre><code class="language-text">0 → Alice
1 → Billy
2 → John
</code></pre>

<p>Then Alice is removed.</p>

<p>Now:</p>

<pre><code class="language-text">0 → Billy
1 → John
</code></pre>

<p>React sees:</p>

<pre><code class="language-text">key 0 still exists
key 1 still exists
</code></pre>

<p>even though the underlying items associated with those positions changed.</p>

<p>This can cause surprising state behaviour in interactive lists.</p>

<p>Stable business identifiers are usually better:</p>

<pre><code class="language-tsx">&lt;Row
  key={user.id}
  item={user}
/&gt;
</code></pre>

<p>Keys are fundamentally about identity.</p>

<p>They tell React:</p>

<blockquote>
  <p><strong>This element represents the same conceptual thing as before.</strong></p>
</blockquote>

<hr />

<h2 id="state-position-matters">State Position Matters</h2>

<p>React associates state with a component’s position and identity in the rendered tree.</p>

<p>Imagine:</p>

<pre><code class="language-tsx">{loggedIn ? (
  &lt;Dashboard /&gt;
) : (
  &lt;Login /&gt;
)}
</code></pre>

<p>When the condition changes, one component leaves and another enters.</p>

<p>Its state lifecycle changes accordingly.</p>

<p>Similarly, changing a component’s key can cause React to treat it as a new component.</p>

<p>For example:</p>

<pre><code class="language-tsx">&lt;Profile key={userId} userId={userId} /&gt;
</code></pre>

<p>Changing:</p>

<pre><code class="language-text">userId = 1
</code></pre>

<p>to:</p>

<pre><code class="language-text">userId = 2
</code></pre>

<p>can intentionally reset <code>Profile</code> state because React treats the new key as a different identity.</p>

<p>This can be useful for cases such as resetting forms when switching records.</p>

<hr />

<h2 id="render-phase-vs-effects">Render Phase vs Effects</h2>

<p>Now consider:</p>

<pre><code class="language-tsx">function Profile({ userId }) {
  const [user, setUser] = useState(null);

  useEffect(() =&gt; {
    fetchUser(userId).then(setUser);
  }, [userId]);

  return &lt;ProfileView user={user} /&gt;;
}
</code></pre>

<p>The effect doesn’t run in the middle of calculating the component’s JSX.</p>

<p>Rendering determines what the UI should look like.</p>

<p>Effects are for synchronizing with things outside the pure render calculation, such as:</p>

<pre><code class="language-text">Network
Browser APIs
Subscriptions
Timers
Third-party libraries
</code></pre>

<p>This distinction helps explain why render functions should ideally remain pure.</p>

<p>Given the same state and props:</p>

<pre><code class="language-text">same input
   │
   ▼
same UI description
</code></pre>

<p>That makes React’s rendering model much easier to reason about.</p>

<hr />

<h2 id="why-side-effects-during-render-are-dangerous">Why Side Effects During Render Are Dangerous</h2>

<p>Imagine:</p>

<pre><code class="language-tsx">function BadComponent() {
  fetch("/api/analytics");

  return &lt;div&gt;Hello&lt;/div&gt;;
}
</code></pre>

<p>Every render triggers a network request.</p>

<p>If the component renders three times:</p>

<pre><code class="language-text">Render 1 → request

Render 2 → request

Render 3 → request
</code></pre>

<p>Now application behavior depends on how often React happens to render.</p>

<p>That is fragile.</p>

<p>Rendering should describe UI, not perform unrelated side effects.</p>

<p>Those operations belong in appropriate event handlers, effects, or data-fetching mechanisms.</p>

<hr />

<h2 id="strict-mode-can-make-this-more-visible">Strict Mode Can Make This More Visible</h2>

<p>During development, React Strict Mode may intentionally invoke certain logic more than once to help expose impure rendering and incorrect effect handling.</p>

<p>Developers sometimes see:</p>

<pre><code class="language-text">Why is this component rendering twice?
</code></pre>

<p>and assume React is broken.</p>

<p>But development behavior may deliberately stress-test assumptions.</p>

<p>That is another reason not to attach important side effects directly to render execution.</p>

<p>A component should remain safe to evaluate when React needs to understand what the UI should look like.</p>

<hr />

<h2 id="re-renders-and-context">Re-Renders and Context</h2>

<p>Suppose:</p>

<pre><code class="language-tsx">&lt;AppContext.Provider
  value={{
    user,
    theme,
    cart,
    notifications
  }}
&gt;
  &lt;App /&gt;
&lt;/AppContext.Provider&gt;
</code></pre>

<p>Many components consume this context.</p>

<p>Then:</p>

<pre><code class="language-text">notifications changes
</code></pre>

<p>The provider’s value changes.</p>

<p>Consumers may need to render again, including ones primarily interested in other parts of that context.</p>

<p>This is why very large contexts can sometimes become performance hotspots.</p>

<p>A better architecture might separate concerns:</p>

<pre><code class="language-text">UserContext

ThemeContext

CartContext

NotificationContext
</code></pre>

<p>or use a store with selector-based subscriptions.</p>

<p>Again, the principle from the previous state-management articles applies:</p>

<blockquote>
  <p><strong>State distribution affects how much of your component tree responds when state changes.</strong></p>
</blockquote>

<hr />

<h2 id="global-state-and-selectors">Global State and Selectors</h2>

<p>Imagine a store containing:</p>

<pre><code class="language-text">user
cart
theme
notifications
sidebar
products
</code></pre>

<p>A component needs only:</p>

<pre><code class="language-text">cart.length
</code></pre>

<p>A selector lets it subscribe to that specific information.</p>

<p>Conceptually:</p>

<pre><code class="language-text">Global Store
    │
    ├── Component A → user
    │
    ├── Component B → cart count
    │
    └── Component C → theme
</code></pre>

<p>Now:</p>

<pre><code class="language-text">user changes
</code></pre>

<p>doesn’t necessarily require the cart-count component to render.</p>

<p>This is one reason state architecture and rendering performance are deeply connected.</p>

<p>The question isn’t only:</p>

<blockquote>
  <p>Where do we store state?</p>
</blockquote>

<p>It is also:</p>

<blockquote>
  <p><strong>Which components are notified when that state changes?</strong></p>
</blockquote>

<hr />

<h2 id="server-state-can-trigger-re-renders-too">Server State Can Trigger Re-Renders Too</h2>

<p>From the previous article, we know server-state libraries maintain cached data.</p>

<p>Suppose:</p>

<pre><code class="language-tsx">const { data: products } = useQuery({
  queryKey: ["products"],
  queryFn: fetchProducts
});
</code></pre>

<p>The cache receives updated server data.</p>

<pre><code class="language-text">Old Products
      │
      ▼
Query Refetch
      │
      ▼
New Products
      │
      ▼
Subscribed Components Re-render
</code></pre>

<p>That is expected.</p>

<p>The important thing is that components interested in unrelated queries don’t need to respond.</p>

<p>Well-designed subscriptions help contain updates to the parts of the interface that actually care about them.</p>

<hr />

<h2 id="rendering-large-lists">Rendering Large Lists</h2>

<p>One place re-render costs become very visible is large collections.</p>

<p>Suppose:</p>

<pre><code class="language-tsx">{transactions.map(transaction =&gt; (
  &lt;TransactionRow
    key={transaction.id}
    transaction={transaction}
  /&gt;
))}
</code></pre>

<p>For:</p>

<pre><code class="language-text">20 transactions
</code></pre>

<p>probably fine.</p>

<p>For:</p>

<pre><code class="language-text">100,000 transactions
</code></pre>

<p>you have a different problem.</p>

<p>Even if React efficiently reconciles the list, rendering and maintaining tens of thousands of DOM elements is expensive.</p>

<p>This is where <strong>virtualization</strong> becomes useful.</p>

<p>Instead of rendering every row:</p>

<pre><code class="language-text">Rows 1 → 100,000
</code></pre>

<p>render only the ones currently visible:</p>

<pre><code class="language-text">Rows 420 → 450
</code></pre>

<p>Conceptually:</p>

<pre><code class="language-text">Dataset

100,000 rows
     │
     ▼
Virtualizer
     │
     ▼
Visible viewport
     │
     ▼
~30 DOM rows
</code></pre>

<p>This reduces both framework rendering work and browser DOM/rendering work.</p>

<p>Libraries such as TanStack Virtual and react-window use this approach.</p>

<hr />

<h2 id="component-boundaries-matter">Component Boundaries Matter</h2>

<p>Imagine one enormous component:</p>

<pre><code class="language-tsx">function Dashboard() {
  // 2,000 lines of state, calculations and JSX
}
</code></pre>

<p>Any state change causes that component’s render logic to execute again.</p>

<p>Breaking the interface into meaningful components can create clearer boundaries:</p>

<pre><code class="language-text">Dashboard
│
├── Header
├── BalanceCard
├── Transactions
├── SpendingChart
└── Goals
</code></pre>

<p>This does not automatically guarantee fewer renders.</p>

<p>But it creates opportunities for:</p>

<pre><code class="language-text">Independent state ownership
Memoization
Selective subscriptions
Smaller render workloads
Clearer architecture
</code></pre>

<p>Good component design is therefore partly about defining sensible rendering boundaries.</p>

<hr />

<h2 id="should-you-fear-re-renders">Should You Fear Re-Renders?</h2>

<p>No.</p>

<p>This is probably the most important practical lesson in the article.</p>

<p>A component doing this:</p>

<pre><code class="language-tsx">function Name({ name }) {
  return &lt;p&gt;{name}&lt;/p&gt;;
}
</code></pre>

<p>can execute extremely quickly.</p>

<p>Spending hours preventing that component from rendering again may make your code harder to maintain without producing any measurable user benefit.</p>

<p>Meanwhile, a single component containing:</p>

<pre><code class="language-text">Expensive calculations
Large lists
Complex charts
Heavy parsing
</code></pre>

<p>can create real problems.</p>

<p>So instead of:</p>

<blockquote>
  <p><strong>How do I stop all re-renders?</strong></p>
</blockquote>

<p>ask:</p>

<blockquote>
  <p><strong>Which renders are actually expensive?</strong></p>
</blockquote>

<p>That is a much healthier performance mindset.</p>

<hr />

<h2 id="the-wrong-way-to-optimize">The Wrong Way to Optimize</h2>

<p>A codebase can quickly become:</p>

<pre><code class="language-tsx">const Component = memo(({ value }) =&gt; {
  const result = useMemo(() =&gt; calculate(value), [value]);

  const onClick = useCallback(() =&gt; {
    ...
  }, []);

  ...
});
</code></pre>

<p>everywhere.</p>

<p>Memoization becomes the default rather than a targeted optimization.</p>

<p>Now every developer has to reason about:</p>

<pre><code class="language-text">Dependencies
Stable references
Memoization boundaries
Stale closures
Prop identity
</code></pre>

<p>even when the underlying render takes microseconds.</p>

<p>You’ve optimized the framework workload while increasing human workload.</p>

<p>That’s not always a good trade.</p>

<hr />

<h2 id="measure-before-optimizing">Measure Before Optimizing</h2>

<p>The browser and React both provide tools for identifying performance problems.</p>

<p>React DevTools includes profiling capabilities that can help answer questions such as:</p>

<pre><code class="language-text">Which component rendered?

How long did it take?

Why did it render?

Which parts of the tree were expensive?
</code></pre>

<p>Browser performance tools can then show what happened afterward:</p>

<pre><code class="language-text">JavaScript
     │
     ▼
DOM Commit
     │
     ▼
Layout
     │
     ▼
Paint
</code></pre>

<p>Combining the two gives you a much clearer picture.</p>

<p>Perhaps React rendering is expensive.</p>

<p>Perhaps React is fast and browser layout is the real problem.</p>

<p>Perhaps neither is the bottleneck and you’re waiting on a network request.</p>

<p>Optimization should follow evidence.</p>

<hr />

<h2 id="a-practical-example">A Practical Example</h2>

<p>Suppose a dashboard has:</p>

<pre><code class="language-tsx">function Dashboard() {
  const [sidebarOpen, setSidebarOpen] = useState(false);

  return (
    &lt;&gt;
      &lt;Sidebar
        open={sidebarOpen}
        onClose={() =&gt; setSidebarOpen(false)}
      /&gt;

      &lt;TransactionsTable /&gt;

      &lt;LargeAnalyticsChart /&gt;
    &lt;/&gt;
  );
}
</code></pre>

<p>Toggling the sidebar causes the dashboard to re-render.</p>

<p>If both <code>TransactionsTable</code> and <code>LargeAnalyticsChart</code> are cheap, stop there.</p>

<p>There may be nothing worth optimizing.</p>

<p>But suppose profiling reveals:</p>

<pre><code class="language-text">LargeAnalyticsChart render

180ms
</code></pre>

<p>every time the sidebar changes.</p>

<p>Now there is a measurable problem.</p>

<p>If the chart’s props remain unchanged, memoization may be appropriate:</p>

<pre><code class="language-tsx">const LargeAnalyticsChart = memo(
  function LargeAnalyticsChart({ data }) {
    return &lt;Chart data={data} /&gt;;
  }
);
</code></pre>

<p>Perhaps chart data also requires an expensive transformation:</p>

<pre><code class="language-tsx">const chartData = useMemo(() =&gt; {
  return calculateAnalytics(transactions);
}, [transactions]);
</code></pre>

<p>Now the optimization has a reason.</p>

<pre><code class="language-text">Before

Sidebar toggle
     │
     ▼
Expensive analytics calculation
     │
     ▼
Chart render


After

Sidebar toggle
     │
     ▼
Cached analytics
     │
     ▼
Chart skipped / cheaper work
</code></pre>

<p>That’s much better than adding memoization everywhere “just in case.”</p>

<hr />

<h2 id="rendering-vs-committing">Rendering vs Committing</h2>

<p>Another useful distinction is that React may perform rendering work that never reaches the DOM.</p>

<p>In modern React, rendering work can sometimes be interrupted, restarted, or discarded before it is committed.</p>

<p>That means:</p>

<pre><code class="language-text">Render work
    │
    ▼
Does React commit it?
    │
 ┌──┴───┐
 │      │
Yes     No
 │      │
 ▼      ▼
DOM    Discard
</code></pre>

<p>This is one reason render logic must remain pure.</p>

<p>React may evaluate a component without guaranteeing that the result becomes visible.</p>

<p>Side effects during rendering would therefore become unpredictable.</p>

<p>The <strong>commit phase</strong> is the point at which actual DOM changes are applied.</p>

<hr />

<h2 id="re-renders-and-the-event-loop">Re-Renders and the Event Loop</h2>

<p>Everything we’ve discussed ultimately happens as JavaScript work on the main thread.</p>

<p>Suppose several expensive components render after one state update.</p>

<pre><code class="language-text">State Update
     │
     ▼
Component A     30ms
     │
Component B     40ms
     │
Component C     50ms
     │
     ▼
Total JS        120ms
</code></pre>

<p>The Event Loop article taught us what that means.</p>

<p>While this work runs:</p>

<pre><code class="language-text">User click       waiting
Animation        waiting
Rendering        waiting
Other JS         waiting
</code></pre>

<p>The issue isn’t merely that React “rendered too many times.”</p>

<p>The user-visible problem is that the main thread was occupied for too long.</p>

<p>That is why frontend performance concepts keep connecting back to one another.</p>

<hr />

<h2 id="re-renders-and-the-browser-rendering-pipeline">Re-Renders and the Browser Rendering Pipeline</h2>

<p>Now suppose React finishes reconciliation and commits:</p>

<pre><code class="language-text">width: 300px
      │
      ▼
width: 600px
</code></pre>

<p>React’s work is finished.</p>

<p>But the browser may now need:</p>

<pre><code class="language-text">Style
  │
  ▼
Layout
  │
  ▼
Paint
  │
  ▼
Composite
</code></pre>

<p>Alternatively, React might commit:</p>

<pre><code class="language-text">opacity: 0
     │
     ▼
opacity: 1
</code></pre>

<p>which may be handled much more cheaply.</p>

<p>So frontend performance has at least two separate dimensions:</p>

<pre><code class="language-text">Framework Work

Component rendering
Reconciliation
DOM updates

        +

Browser Work

Style
Layout
Paint
Composite
</code></pre>

<p>Optimizing only one side can leave the actual bottleneck untouched.</p>

<hr />

<h2 id="a-better-mental-model">A Better Mental Model</h2>

<p>When state changes, don’t imagine:</p>

<pre><code class="language-text">State changes
     │
     ▼
Entire page rebuilt
</code></pre>

<p>Think:</p>

<pre><code class="language-text">State changes
     │
     ▼
Affected component tree evaluated
     │
     ▼
New UI description
     │
     ▼
React reconciles
     │
     ▼
Actual differences identified
     │
     ▼
Necessary DOM mutations committed
     │
     ▼
Browser processes those changes
</code></pre>

<p>Every arrow represents a potential cost.</p>

<p>But none should automatically be assumed to be expensive.</p>

<hr />

<h2 id="practical-rules-for-re-render-performance">Practical Rules for Re-Render Performance</h2>

<p>A few principles go a long way: keep state as close as practical to the components that actually need it, avoid placing rapidly changing local state unnecessarily high in the tree, and avoid repeating expensive calculations on every render when memoization or restructuring can prevent that work.</p>

<p>Use stable keys for lists, apply memoization when profiling shows meaningful savings, design Context boundaries and global store subscriptions intentionally, virtualize genuinely large lists, and avoid side effects during render.</p>

<p>Above all, do not optimize purely based on how many renders a console statement reports.</p>

<p>A render is only a problem when the work involved is actually expensive enough to matter.</p>

<hr />

<h2 id="bringing-it-all-together">Bringing It All Together</h2>

<p>A state update begins inside your application:</p>

<pre><code class="language-text">State
  │
  ▼
Re-render
</code></pre>

<p>That re-render produces a new description of the UI.</p>

<pre><code class="language-text">Component Function
       │
       ▼
New Element Tree
</code></pre>

<p>React compares it with what came before.</p>

<pre><code class="language-text">Previous Tree
      │
      ├────► Reconciliation
      │
New Tree
</code></pre>

<p>Only necessary changes are committed.</p>

<pre><code class="language-text">Difference
    │
    ▼
DOM Mutation
</code></pre>

<p>Then the browser takes over.</p>

<pre><code class="language-text">DOM
 │
 ▼
Style
 │
 ▼
Layout
 │
 ▼
Paint
 │
 ▼
Composite
 │
 ▼
Pixels
</code></pre>

<p>That gives us the full chain:</p>

<pre><code class="language-text">State Change
      │
      ▼
Component Render
      │
      ▼
Reconciliation
      │
      ▼
Commit
      │
      ▼
DOM Change
      │
      ▼
Browser Rendering
      │
      ▼
Updated Pixels
</code></pre>

<p>Once you understand those boundaries, performance discussions become much clearer.</p>

<p>You can ask:</p>

<pre><code class="language-text">Is the component render expensive?

Is reconciliation expensive?

Are we committing too many DOM changes?

Is layout the real problem?

Is painting expensive?

Is the main thread blocked?
</code></pre>

<p>Those are much better questions than simply asking:</p>

<blockquote>
  <p>Why is React re-rendering?</p>
</blockquote>

<hr />

<h2 id="final-thoughts">Final Thoughts</h2>

<p>Re-renders have a reputation they do not entirely deserve: they are not bugs, they are not automatically performance problems, and preventing every possible render is not the goal of frontend engineering.</p>

<p>Rendering is how declarative UI frameworks work.</p>

<p>You describe:</p>

<pre><code class="language-text">What the UI should look like
for the current state.
</code></pre>

<p>Then the framework figures out how to get there.</p>

<p>The real performance question is not whether components render, but whether the amount of work happening during those renders prevents the application from delivering a smooth experience.</p>

<p>Sometimes the answer is yes: a large calculation runs repeatedly, a huge list is rendered unnecessarily, or a global state update wakes up hundreds of components, and those cases deserve optimization.</p>

<p>But often, rendering is already cheap, and in those cases adding layers of memoization can make the code harder to understand without making the application noticeably faster.</p>

<p>So the next time you see a component render again, don’t immediately ask:</p>

<blockquote>
  <p><strong>“How do I stop this?”</strong></p>
</blockquote>

<p>Ask:</p>

<blockquote>
  <p><strong>“What work is this render actually doing, and is that work expensive enough to matter?”</strong></p>
</blockquote>

<p>That is the question that leads to better frontend performance decisions.</p>

<hr />

<h2 id="whats-next">What’s Next?</h2>

<p>We’ve now explored how frontend state changes propagate through a component tree and eventually reach the browser.</p>

<p>Many of the expensive calculations we discussed share another important characteristic: sometimes the problem is not that the calculation is too slow, but that we are doing the <strong>same calculation repeatedly</strong>.</p>

<p>That brings us to another important frontend concept:</p>

<blockquote>
  <p><strong>Memoization Explained: When Caching Computation Actually Helps</strong></p>
</blockquote>

<p>We’ll explore how memoization works, referential equality, memoized components, <code>useMemo</code>, <code>useCallback</code>, selectors, cache invalidation, and why adding memoization everywhere can sometimes make an application more complicated without making it any faster.</p>

<p>Because caching work is useful only when the work was worth avoiding in the first place.</p>

]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="Frontend" />
    
    <category term="Performance" />
    
  

  
    
    <category term="Frontend" />
    
    <category term="Performance" />
    
  

    <summary>Learn how React re-renders, reconciliation, and DOM commits work so you can optimize real performance bottlenecks instead of chasing every render.</summary>

  </entry>

  
  





  



  


  <entry>
    <title>State Management Explained: Why Frontend State Gets Complicated</title>
    <link href="https://billyokeyo.dev/posts/state-management/" rel="alternate" type="text/html" title="State Management Explained: Why Frontend State Gets Complicated" />
    <published>2026-09-04T00:00:00+00:00</published>
  
    <updated>2026-09-04T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/state-management/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/state-management/"><![CDATA[<blockquote>
  <p><em>“State management becomes difficult not because applications have state, but because different kinds of state have different owners, lifetimes, and sources of truth.”</em></p>
</blockquote>

<p>Imagine you’re building a simple product page.</p>

<p>At first, there isn’t much to manage.</p>

<pre><code class="language-javascript">const [quantity, setQuantity] = useState(1);
</code></pre>

<p>Easy.</p>

<p>Then you add a product variant.</p>

<pre><code class="language-javascript">const [selectedColor, setSelectedColor] = useState("black");
</code></pre>

<p>Then a modal.</p>

<pre><code class="language-javascript">const [isModalOpen, setIsModalOpen] = useState(false);
</code></pre>

<p>Then authentication, the shopping cart, filters, pagination, API responses, loading states, and errors. The URL needs to remember the filters, another component needs access to the cart, and when the user navigates away and comes back, some state should remain while other state should disappear.</p>

<p>Before long, your application looks like this:</p>

<pre><code class="language-text">Frontend Application
       │
       ├── UI State
       ├── Form State
       ├── Server State
       ├── URL State
       ├── Authentication
       ├── Cached Data
       ├── Global State
       └── Derived State
</code></pre>

<p>And suddenly someone says:</p>

<blockquote>
  <p>“We need a state management library.”</p>
</blockquote>

<p>But that’s often jumping ahead. Before choosing Redux, Zustand, Pinia, Context, TanStack Query, signals, or anything else, there’s a more important question:</p>

<blockquote>
  <p><strong>What kind of state are we actually trying to manage?</strong></p>
</blockquote>

<p>Not everything called “state” is the same problem, and once you understand that, frontend state management becomes much easier to reason about.</p>

<hr />

<h2 id="what-is-state">What Is State?</h2>

<p>At its simplest, state is information that can change over time and affects what your application does or displays.</p>

<p>Consider a counter:</p>

<pre><code class="language-javascript">const [count, setCount] = useState(0);
</code></pre>

<p>The UI depends on <code>count</code>.</p>

<pre><code class="language-jsx">&lt;button onClick={() =&gt; setCount(count + 1)}&gt;
    Count: {count}
&lt;/button&gt;
</code></pre>

<p>At one moment:</p>

<pre><code class="language-text">count = 0
</code></pre>

<p>After a click:</p>

<pre><code class="language-text">count = 1
</code></pre>

<p>The interface changes because the underlying state changed.</p>

<p>We can think of the UI as a function of state:</p>

<pre><code class="language-text">State
  │
  ▼
Render
  │
  ▼
UI
</code></pre>

<p>Change the state:</p>

<pre><code class="language-text">New State
    │
    ▼
Re-render
    │
    ▼
New UI
</code></pre>

<p>This state-driven model is fundamental to frameworks such as React, Vue, Svelte, and others. The problem isn’t the idea itself. The problem begins when an application has <strong>many different sources of changing information</strong>.</p>

<hr />

<h2 id="a-small-application-doesnt-need-state-management">A Small Application Doesn’t Need “State Management”</h2>

<p>Consider a dropdown.</p>

<pre><code class="language-jsx">function Dropdown() {
    const [open, setOpen] = useState(false);

    return (
        &lt;div&gt;
            &lt;button onClick={() =&gt; setOpen(!open)}&gt;
                Menu
            &lt;/button&gt;

            {open &amp;&amp; (
                &lt;div&gt;
                    Profile
                    Settings
                    Logout
                &lt;/div&gt;
            )}
        &lt;/div&gt;
    );
}
</code></pre>

<p>The state belongs naturally to the dropdown.</p>

<pre><code class="language-text">Dropdown
   │
   └── open
</code></pre>

<p>Nobody else needs it.</p>

<p>When the dropdown disappears, we probably don’t care about preserving that state.</p>

<p>This is <strong>local component state</strong>.</p>

<p>And local state is often the best kind of state.</p>

<p>The closer state lives to the code that actually needs it, the easier the application is usually to understand.</p>

<p>The trouble starts when state begins travelling.</p>

<hr />

<h2 id="when-state-needs-to-be-shared">When State Needs to Be Shared</h2>

<p>Imagine two components:</p>

<pre><code class="language-text">Header
  │
  └── CartIcon

ProductPage
  │
  └── AddToCartButton
</code></pre>

<p>When the user clicks:</p>

<pre><code class="language-text">Add to Cart
</code></pre>

<p>the header needs to update:</p>

<pre><code class="language-text">Cart (0)
   │
   ▼
Cart (1)
</code></pre>

<p>Now the cart state cannot live exclusively inside <code>AddToCartButton</code>. Both components need access to it. A common solution is to move the state upward.</p>

<pre><code class="language-text">           App
            │
        cartItems
        /       \
       ▼         ▼
   Header    ProductPage
      │           │
 CartIcon    AddToCart
</code></pre>

<p>This is commonly called <strong>lifting state up</strong>: move shared state to a common owner and pass the necessary values or update functions downward. React’s documentation recommends this pattern when multiple components need coordinated state. (<a href="https://react.dev/learn/managing-state?utm_source=chatgpt.com" title="Managing State - React">React</a>)</p>

<p>That works well.</p>

<p>Until the component tree gets larger.</p>

<hr />

<h2 id="prop-drilling-appears">Prop Drilling Appears</h2>

<p>Suppose the structure becomes:</p>

<pre><code class="language-text">App
 │
 ├── Header
 │    └── Navigation
 │         └── CartButton
 │
 └── Main
      └── ProductPage
           └── ProductDetails
                └── AddToCartButton
</code></pre>

<p>The cart state lives in <code>App</code>.</p>

<p>But <code>AddToCartButton</code> needs it.</p>

<p>You may end up passing:</p>

<pre><code class="language-jsx">&lt;App&gt;
    &lt;Main cart={cart}&gt;
        &lt;ProductPage cart={cart}&gt;
            &lt;ProductDetails cart={cart}&gt;
                &lt;AddToCartButton cart={cart} /&gt;
            &lt;/ProductDetails&gt;
        &lt;/ProductPage&gt;
    &lt;/Main&gt;
&lt;/App&gt;
</code></pre>

<p><code>Main</code> doesn’t care about the cart, and <code>ProductPage</code> may not care either. They’re simply transporting information.</p>

<pre><code class="language-text">App
 │
 │ cart
 ▼
Main
 │
 │ cart
 ▼
ProductPage
 │
 │ cart
 ▼
ProductDetails
 │
 │ cart
 ▼
AddToCartButton
</code></pre>

<p>This is commonly called <strong>prop drilling</strong>, and it’s often the moment developers begin looking for global state management. But before we reach for a global store, we need to make another distinction.</p>

<hr />

<h2 id="not-all-state-is-application-state">Not All State Is Application State</h2>

<p>Consider this dashboard:</p>

<pre><code class="language-text">┌─────────────────────────────────────┐
│ Dashboard                           │
│                                     │
│ Search: [ laptop             ]      │
│                                     │
│ Status: Active                      │
│                                     │
│ Customers                           │
│ ┌─────────────────────────────────┐ │
│ │ Alice                           │ │
│ │ Billy                           │ │
│ │ James                           │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────┘
</code></pre>

<p>What state exists here?</p>

<p>Potentially:</p>

<pre><code class="language-text">searchText
selectedStatus
customers
isLoading
error
currentUser
sidebarOpen
currentPage
</code></pre>

<p>It’s tempting to put all of that into:</p>

<pre><code class="language-text">Global Store
</code></pre>

<p>But those values represent very different things.</p>

<p>For example:</p>

<pre><code class="language-text">sidebarOpen
</code></pre>

<p>belongs to the UI.</p>

<p>While:</p>

<pre><code class="language-text">customers
</code></pre>

<p>probably came from a server.</p>

<p>And:</p>

<pre><code class="language-text">currentPage
</code></pre>

<p>might belong in the URL.</p>

<p>Treating them identically creates unnecessary complexity.</p>

<p>A useful state architecture starts by classifying state.</p>

<hr />

<h2 id="1-local-ui-state">1. Local UI State</h2>

<p>Local UI state represents temporary interaction details.</p>

<p>Examples include:</p>

<pre><code class="language-text">Modal open?
Dropdown expanded?
Selected tab?
Hovered item?
Accordion expanded?
Tooltip visible?
</code></pre>

<p>For example:</p>

<pre><code class="language-javascript">const [isOpen, setIsOpen] = useState(false);
</code></pre>

<p>This state is usually:</p>

<ul>
  <li>Temporary</li>
  <li>Owned by one component or a small subtree</li>
  <li>Not important outside that UI</li>
  <li>Safe to discard when the component disappears</li>
</ul>

<p>It should usually stay local.</p>

<pre><code class="language-text">Modal
  │
  └── isOpen
</code></pre>

<p>Moving every boolean into a global store:</p>

<pre><code class="language-javascript">store.modalOpen
store.dropdownOpen
store.tooltipVisible
store.settingsTab
</code></pre>

<p>can turn a simple application into a state-management bureaucracy.</p>

<hr />

<h2 id="2-shared-client-state">2. Shared Client State</h2>

<p>Some state genuinely needs to be shared across different parts of the application.</p>

<p>Examples might include:</p>

<pre><code class="language-text">Shopping cart
Application theme
Feature preferences
Complex editor state
Currently selected workspace
</code></pre>

<p>Imagine:</p>

<pre><code class="language-text">             Application
                  │
              Cart State
            /     |      \
           ▼      ▼       ▼
        Header Product Checkout
</code></pre>

<p>This is where mechanisms such as:</p>

<pre><code class="language-text">Context
Redux
Zustand
Pinia
Signals
</code></pre>

<p>can become useful depending on the framework and complexity.</p>

<p>The important point is:</p>

<blockquote>
  <p><strong>Global state should be global because its ownership is global, not because passing props became mildly inconvenient.</strong></p>
</blockquote>

<hr />

<h2 id="3-server-state">3. Server State</h2>

<p>Now consider:</p>

<pre><code class="language-javascript">const [products, setProducts] = useState([]);
</code></pre>

<p>At first glance, this looks like ordinary state.</p>

<p>But where did those products come from?</p>

<p>Probably:</p>

<pre><code class="language-text">Database
   │
   ▼
Backend
   │
   ▼
API
   │
   ▼
Frontend
</code></pre>

<p>The frontend does not actually own this data. The server does, and the browser has a <strong>local copy</strong>. That creates completely different problems.</p>

<p>Suppose you fetch:</p>

<pre><code class="language-http">GET /api/products
</code></pre>

<p>and receive:</p>

<pre><code class="language-json">[
    {
        "id": 1,
        "name": "Keyboard",
        "stock": 12
    }
]
</code></pre>

<p>Five seconds later, another customer buys two keyboards.</p>

<p>The server now has:</p>

<pre><code class="language-text">stock = 10
</code></pre>

<p>Your frontend still has:</p>

<pre><code class="language-text">stock = 12
</code></pre>

<p>Now your state is <strong>stale</strong>.</p>

<p>That’s not usually a problem with a modal boolean.</p>

<pre><code class="language-text">isModalOpen = true
</code></pre>

<p>doesn’t suddenly become outdated because another computer changed something.</p>

<p>Server state does.</p>

<hr />

<h2 id="server-state-has-different-problems">Server State Has Different Problems</h2>

<p>Managing server state means thinking about:</p>

<pre><code class="language-text">Fetching
Caching
Staleness
Retries
Refetching
Deduplication
Pagination
Mutations
Optimistic updates
Synchronization
</code></pre>

<p>Consider:</p>

<pre><code class="language-javascript">useEffect(() =&gt; {
    fetch("/api/products")
        .then(response =&gt; response.json())
        .then(setProducts);
}, []);
</code></pre>

<p>Looks simple, until requirements arrive. We need loading state.</p>

<pre><code class="language-javascript">const [loading, setLoading] = useState(true);
</code></pre>

<p>Then errors.</p>

<pre><code class="language-javascript">const [error, setError] = useState(null);
</code></pre>

<p>Then retries, caching, refetching when the user returns to the tab, avoiding duplicate requests, and invalidating products after an update.</p>

<p>What looked like:</p>

<pre><code class="language-text">products
</code></pre>

<p>was actually a synchronization problem between:</p>

<pre><code class="language-text">Server Truth
     │
     ▼
Client Cache
     │
     ▼
UI
</code></pre>

<p>That’s why tools such as <strong>TanStack Query</strong>, SWR, Apollo Client, and framework-native data layers exist. They aren’t simply storing variables. They’re managing <strong>remote data lifecycles</strong>.</p>

<hr />

<h2 id="server-state-shouldnt-automatically-live-in-your-global-store">Server State Shouldn’t Automatically Live in Your Global Store</h2>

<p>A common architecture used to look like:</p>

<pre><code class="language-text">API
 │
 ▼
Redux
 │
 ▼
Components
</code></pre>

<p>Every API response was copied into the application’s global state.</p>

<p>For some applications, that can still be appropriate.</p>

<p>But often you’re making your client store responsible for problems that a server-state cache is specifically designed to solve.</p>

<p>A modern architecture may instead look like:</p>

<pre><code class="language-text">                Frontend
                   │
        ┌──────────┴──────────┐
        │                     │
        ▼                     ▼
 Client State            Server State
        │                     │
    Zustand /             Query Cache
     Redux /                  │
    Context                   ▼
                         Backend API
</code></pre>

<p>Different problems.</p>

<p>Different tools.</p>

<hr />

<h2 id="4-url-state">4. URL State</h2>

<p>Suppose your product page has filters:</p>

<pre><code class="language-text">Category: Laptops
Price: 20,000 - 100,000
Sort: Price Low to High
Page: 3
</code></pre>

<p>You could store them as:</p>

<pre><code class="language-javascript">const [category, setCategory] = useState("laptops");
const [sort, setSort] = useState("price");
const [page, setPage] = useState(3);
</code></pre>

<p>But what happens when the user refreshes? The state disappears. What happens when they copy the URL and send it to someone? The other person sees the default filters. What happens when they press the browser’s Back button? Potentially, nothing useful. Maybe this state belongs somewhere else: the URL.</p>

<pre><code class="language-text">/products?category=laptops&amp;sort=price&amp;page=3
</code></pre>

<p>Now:</p>

<pre><code class="language-text">URL
 │
 ├── category=laptops
 ├── sort=price
 └── page=3
</code></pre>

<p>becomes the source of truth.</p>

<p>This gives us useful behavior almost automatically:</p>

<pre><code class="language-text">Refresh        ✓
Share link     ✓
Bookmark       ✓
Back button    ✓
Forward button ✓
</code></pre>

<p>This is why the URL itself should be thought of as a state container.</p>

<hr />

<h2 id="dont-duplicate-url-state">Don’t Duplicate URL State</h2>

<p>A common mistake is:</p>

<pre><code class="language-text">URL
 │
 └── page=3

AND

React State
 │
 └── page=3
</code></pre>

<p>Now you have two sources of truth.</p>

<p>What happens if:</p>

<pre><code class="language-text">URL page = 3

but

React page = 2
</code></pre>

<p>Which one wins?</p>

<p>You’ve created a synchronization problem that didn’t need to exist.</p>

<p>A better model is:</p>

<pre><code class="language-text">URL
 │
 ▼
page
 │
 ▼
UI
</code></pre>

<p>If the URL owns the value, read it from there.</p>

<hr />

<h2 id="5-form-state">5. Form State</h2>

<p>Forms deserve their own category because they can become surprisingly complicated.</p>

<p>A simple form:</p>

<pre><code class="language-javascript">const [email, setEmail] = useState("");
</code></pre>

<p>is easy.</p>

<p>Now add:</p>

<pre><code class="language-text">Name
Email
Phone
Country
Address
Password
Confirm Password
</code></pre>

<p>Then:</p>

<pre><code class="language-text">Validation
Touched fields
Dirty fields
Submitting
Server errors
Conditional fields
Resetting
Default values
</code></pre>

<p>Suddenly, “email” isn’t the only state.</p>

<p>You have:</p>

<pre><code class="language-text">value
valid?
touched?
dirty?
error?
submitting?
</code></pre>

<p>for potentially dozens of fields.</p>

<p>That’s why libraries such as React Hook Form, Formik, and framework-specific form systems exist.</p>

<p>Again, the lesson isn’t:</p>

<blockquote>
  <p>Use a library for every form.</p>
</blockquote>

<p>It’s:</p>

<blockquote>
  <p><strong>Recognize that form state has a particular lifecycle and shouldn’t automatically become global application state.</strong></p>
</blockquote>

<hr />

<h2 id="6-derived-state">6. Derived State</h2>

<p>Derived state is one of the most common sources of unnecessary complexity.</p>

<p>Imagine:</p>

<pre><code class="language-javascript">const [firstName, setFirstName] = useState("Billy");
const [lastName, setLastName] = useState("Okeyo");
const [fullName, setFullName] = useState("Billy Okeyo");
</code></pre>

<p>We now have three pieces of state.</p>

<p>But do we really?</p>

<p><code>fullName</code> can be calculated:</p>

<pre><code class="language-javascript">const fullName = `${firstName} ${lastName}`;
</code></pre>

<p>So our actual state is:</p>

<pre><code class="language-text">firstName
lastName
</code></pre>

<p>and:</p>

<pre><code class="language-text">fullName
</code></pre>

<p>is derived.</p>

<p>React’s own guidance recommends avoiding redundant state when a value can be calculated from existing props or state during rendering. (<a href="https://react.dev/learn/choosing-the-state-structure?utm_source=chatgpt.com" title="Choosing the State Structure - React">React</a>)</p>

<p>Why?</p>

<p>Because duplication creates synchronization problems.</p>

<hr />

<h2 id="the-synchronization-trap">The Synchronization Trap</h2>

<p>Suppose we store all three:</p>

<pre><code class="language-javascript">const [firstName, setFirstName] = useState("Billy");
const [lastName, setLastName] = useState("Okeyo");
const [fullName, setFullName] = useState("Billy Okeyo");
</code></pre>

<p>Now someone writes:</p>

<pre><code class="language-javascript">setFirstName("John");
</code></pre>

<p>but forgets:</p>

<pre><code class="language-javascript">setFullName("John Okeyo");
</code></pre>

<p>We get:</p>

<pre><code class="language-text">firstName = John
lastName  = Okeyo
fullName  = Billy Okeyo
</code></pre>

<p>Your application contradicts itself.</p>

<p>The problem isn’t React.</p>

<p>The problem is that we stored information that could have been calculated.</p>

<p>A good rule is:</p>

<blockquote>
  <p><strong>Store the minimum information required to describe the application. Derive everything else.</strong></p>
</blockquote>

<p>React describes this as finding the minimal but complete representation of UI state. (<a href="https://react.dev/learn/thinking-in-react?utm_source=chatgpt.com" title="Thinking in React - React">React</a>)</p>

<hr />

<h2 id="another-derived-state-example">Another Derived State Example</h2>

<p>Suppose:</p>

<pre><code class="language-javascript">const [products, setProducts] = useState([...]);
const [search, setSearch] = useState("");
</code></pre>

<p>Should we also store:</p>

<pre><code class="language-javascript">const [filteredProducts, setFilteredProducts] = useState([]);
</code></pre>

<p>Probably not.</p>

<p>We can derive it:</p>

<pre><code class="language-javascript">const filteredProducts = products.filter(product =&gt;
    product.name
        .toLowerCase()
        .includes(search.toLowerCase())
);
</code></pre>

<p>Our model becomes:</p>

<pre><code class="language-text">products ──────┐
               │
               ▼
             Filter ───► filteredProducts
               ▲
               │
search ─────────┘
</code></pre>

<p><code>filteredProducts</code> is an output.</p>

<p>Not necessarily state.</p>

<hr />

<h2 id="state-gets-complicated-when-we-duplicate-truth">State Gets Complicated When We Duplicate Truth</h2>

<p>This is one of the biggest themes in frontend state management.</p>

<p>Imagine:</p>

<pre><code class="language-text">API Response
    │
    ├── Redux Store
    │
    ├── Component State
    │
    ├── Form State
    │
    └── localStorage
</code></pre>

<p>Now the same information exists in four places.</p>

<p>Every update creates a question:</p>

<pre><code class="language-text">Which one is correct?
</code></pre>

<p>Then:</p>

<pre><code class="language-text">Which one should update first?
</code></pre>

<p>Then:</p>

<pre><code class="language-text">What if one update fails?
</code></pre>

<p>Then:</p>

<pre><code class="language-text">What happens after refresh?
</code></pre>

<p>A large percentage of state-management complexity is actually <strong>state synchronization complexity</strong>.</p>

<p>The fewer copies of truth you maintain, the fewer things you need to synchronize.</p>

<hr />

<h2 id="impossible-states">Impossible States</h2>

<p>Poorly structured state can also represent combinations that should never exist.</p>

<p>Consider:</p>

<pre><code class="language-javascript">const [isLoading, setIsLoading] = useState(false);
const [isSuccess, setIsSuccess] = useState(false);
const [isError, setIsError] = useState(false);
</code></pre>

<p>Nothing technically prevents:</p>

<pre><code class="language-text">isLoading = true
isSuccess = true
isError   = true
</code></pre>

<p>But what does that mean?</p>

<p>We’re loading successfully while failing?</p>

<p>Instead, maybe the application actually has one state:</p>

<pre><code class="language-javascript">const [status, setStatus] = useState("idle");
</code></pre>

<p>with possible values:</p>

<pre><code class="language-text">idle
loading
success
error
</code></pre>

<p>Now:</p>

<pre><code class="language-text">status = loading
</code></pre>

<p>cannot simultaneously be:</p>

<pre><code class="language-text">status = success
</code></pre>

<p>The data structure itself prevents invalid combinations. React’s state-structure guidance specifically recommends avoiding contradictory state for this reason. (<a href="https://react.dev/learn/choosing-the-state-structure?utm_source=chatgpt.com" title="Choosing the State Structure - React">React</a>)</p>

<p>This idea becomes extremely powerful in complex UIs.</p>

<hr />

<h2 id="think-in-state-machines">Think in State Machines</h2>

<p>Consider a payment flow.</p>

<p>You might start with:</p>

<pre><code class="language-javascript">const [loading, setLoading] = useState(false);
const [paid, setPaid] = useState(false);
const [failed, setFailed] = useState(false);
const [cancelled, setCancelled] = useState(false);
</code></pre>

<p>But conceptually, the payment probably behaves more like:</p>

<pre><code class="language-text">            ┌───────────┐
            │   IDLE    │
            └─────┬─────┘
                  │ Pay
                  ▼
            ┌───────────┐
            │PROCESSING │
            └─────┬─────┘
                  │
          ┌───────┼────────┐
          ▼       ▼        ▼
      SUCCESS   FAILED   CANCELLED
</code></pre>

<p>Representing it as:</p>

<pre><code class="language-javascript">const [status, setStatus] = useState("idle");
</code></pre>

<p>makes the model much closer to reality.</p>

<p>Good state management often starts with good <strong>data modelling</strong>, not better libraries.</p>

<hr />

<h2 id="state-ownership-matters">State Ownership Matters</h2>

<p>Imagine three components:</p>

<pre><code class="language-text">ProductPage
 ├── ProductGallery
 ├── ProductDetails
 └── AddToCart
</code></pre>

<p>Only <code>ProductGallery</code> needs:</p>

<pre><code class="language-text">currentImage
</code></pre>

<p>Where should it live?</p>

<p>Probably:</p>

<pre><code class="language-text">ProductGallery
      │
      └── currentImage
</code></pre>

<p>Not:</p>

<pre><code class="language-text">Global Store
      │
      └── currentImage
</code></pre>

<p>Now suppose both <code>ProductDetails</code> and <code>AddToCart</code> need:</p>

<pre><code class="language-text">selectedVariant
</code></pre>

<p>Then perhaps:</p>

<pre><code class="language-text">ProductPage
      │
      └── selectedVariant
             │
        ┌────┴─────┐
        ▼          ▼
ProductDetails  AddToCart
</code></pre>

<p>State should generally live at the <strong>lowest level that owns all consumers that need it</strong>.</p>

<p>Move it upward when necessary.</p>

<p>Not before.</p>

<hr />

<h2 id="state-lifetime-matters-too">State Lifetime Matters Too</h2>

<p>Different state should survive for different amounts of time.</p>

<p>Consider:</p>

<pre><code class="language-text">Tooltip open
</code></pre>

<p>Lifetime:</p>

<pre><code class="language-text">Seconds
</code></pre>

<p>Shopping cart:</p>

<pre><code class="language-text">Minutes / Days
</code></pre>

<p>Authentication session:</p>

<pre><code class="language-text">Hours / Days
</code></pre>

<p>URL filter:</p>

<pre><code class="language-text">As long as URL exists
</code></pre>

<p>Server cache:</p>

<pre><code class="language-text">Until stale / invalidated
</code></pre>

<p>User preferences:</p>

<pre><code class="language-text">Months
</code></pre>

<p>Putting all of these into one store ignores their fundamentally different lifecycles.</p>

<p>A useful way to think about state is:</p>

<pre><code class="language-text">State
 │
 ├── Who owns it?
 │
 ├── Who needs it?
 │
 ├── How long should it live?
 │
 ├── Where is the source of truth?
 │
 └── What causes it to change?
</code></pre>

<p>Answer those questions first.</p>

<p>Then choose the storage mechanism.</p>

<hr />

<h2 id="persistence-is-not-the-same-as-state-management">Persistence Is Not the Same as State Management</h2>

<p>Suppose we want the theme to survive refreshes.</p>

<p>We might use:</p>

<pre><code class="language-javascript">localStorage.setItem("theme", "dark");
</code></pre>

<p>Now some developers immediately put all application state into <code>localStorage</code>.</p>

<p>But persistence creates another source of truth.</p>

<pre><code class="language-text">Application State
       │
       ▼
localStorage
</code></pre>

<p>What happens when the application’s expected data structure changes? What happens when the stored value is invalid? What happens when the user logs out? What happens when data becomes stale? Persistence should be intentional. Not every state deserves immortality.</p>

<hr />

<h2 id="context-is-not-automatically-a-state-manager">Context Is Not Automatically a State Manager</h2>

<p>In React, Context is often introduced when prop drilling becomes uncomfortable.</p>

<pre><code class="language-jsx">&lt;CartContext.Provider value={cart}&gt;
    &lt;App /&gt;
&lt;/CartContext.Provider&gt;
</code></pre>

<p>Then:</p>

<pre><code class="language-javascript">const cart = useContext(CartContext);
</code></pre>

<p>This solves a <strong>distribution problem</strong>.</p>

<p>Instead of:</p>

<pre><code class="language-text">App
 │ props
 ▼
A
 │ props
 ▼
B
 │ props
 ▼
C
</code></pre>

<p>we get:</p>

<pre><code class="language-text">      Context
      /  |  \
     ▼   ▼   ▼
     A   B   C
</code></pre>

<p>That’s useful.</p>

<p>But Context doesn’t automatically solve:</p>

<pre><code class="language-text">Caching
Server synchronization
Persistence
Complex update logic
Optimistic updates
Normalized entities
</code></pre>

<p>It’s a mechanism for making values available through a component tree. Sometimes that’s all you need. Sometimes it isn’t.</p>

<hr />

<h2 id="why-global-stores-exist">Why Global Stores Exist</h2>

<p>As applications grow, some client state can become genuinely complicated.</p>

<p>Imagine an image editor.</p>

<pre><code class="language-text">Canvas
 │
 ├── Selected objects
 ├── Layers
 ├── History
 ├── Zoom
 ├── Tools
 ├── Clipboard
 └── Document state
</code></pre>

<p>Many distant components may need to read and modify the same information.</p>

<pre><code class="language-text">              Editor State
          /       |       \
         ▼        ▼        ▼
      Toolbar   Canvas   Layers
         │        │        │
         ▼        ▼        ▼
      Buttons   Objects   Panel
</code></pre>

<p>A centralized or shared store can provide:</p>

<pre><code class="language-text">One ownership model
Predictable updates
Subscriptions
Selectors
Debugging tools
Middleware
</code></pre>

<p>This is where Redux, Zustand, Pinia and similar solutions can shine. The problem isn’t global state. The problem is <strong>unnecessarily global state</strong>.</p>

<hr />

<h2 id="redux-isnt-the-answer-to-every-state-problem">Redux Isn’t the Answer to Every State Problem</h2>

<p>Suppose your application has:</p>

<pre><code class="language-javascript">const [modalOpen, setModalOpen] = useState(false);
</code></pre>

<p>Moving it into Redux:</p>

<pre><code class="language-javascript">dispatch(openModal());
</code></pre>

<p>doesn’t automatically improve the architecture.</p>

<p>Likewise, storing an API response in Redux doesn’t automatically solve server-state caching.</p>

<p>And storing filters in Redux may be worse than putting them in the URL.</p>

<p>Instead of asking:</p>

<blockquote>
  <p>Which state library should we use?</p>
</blockquote>

<p>Ask:</p>

<blockquote>
  <p><strong>Where should this specific piece of state live?</strong></p>
</blockquote>

<p>Then the answer may be:</p>

<pre><code class="language-text">Component
URL
Server cache
Form manager
Context
Global store
Browser storage
</code></pre>

<p>The tool follows the ownership model.</p>

<hr />

<h2 id="a-better-state-architecture">A Better State Architecture</h2>

<p>Imagine an e-commerce application.</p>

<p>Instead of:</p>

<pre><code class="language-text">EVERYTHING
    │
    ▼
Redux
</code></pre>

<p>we might have:</p>

<pre><code class="language-text">                    Application
                         │
       ┌─────────────────┼─────────────────┐
       │                 │                 │
       ▼                 ▼                 ▼
   UI State          URL State        Server State
       │                 │                 │
    useState           Router          Query Cache
       │                                   │
       ▼                                   ▼
 Components                              API

                         │
                         ▼
                  Shared Client State
                         │
                         ▼
                    Global Store
</code></pre>

<p>Now each type of state uses the mechanism suited to its job.</p>

<p>This can actually make an application simpler even though we’re using several different tools.</p>

<p>Because each tool has a clear responsibility.</p>

<hr />

<h2 id="example-building-a-product-search-page">Example: Building a Product Search Page</h2>

<p>Let’s put this into practice.</p>

<p>Suppose we’re building:</p>

<pre><code class="language-text">/products
</code></pre>

<p>The page contains:</p>

<pre><code class="language-text">Search
Category filter
Sort order
Products
Cart
Filter drawer
</code></pre>

<p>Where should everything live?</p>

<h4 id="filter-drawer">Filter Drawer</h4>

<pre><code class="language-text">isFilterDrawerOpen
</code></pre>

<p>This is local UI state.</p>

<pre><code class="language-javascript">const [isFilterDrawerOpen, setFilterDrawerOpen] =
    useState(false);
</code></pre>

<hr />

<h4 id="search-and-filters">Search and Filters</h4>

<p>These affect what page the user is viewing and should be shareable.</p>

<pre><code class="language-text">/products?q=keyboard&amp;category=accessories&amp;sort=price
</code></pre>

<p>So:</p>

<pre><code class="language-text">URL State
</code></pre>

<p>is a strong choice.</p>

<hr />

<h4 id="products">Products</h4>

<p>Products come from:</p>

<pre><code class="language-text">Backend API
</code></pre>

<p>So they’re:</p>

<pre><code class="language-text">Server State
</code></pre>

<p>A query cache could manage them.</p>

<p>Conceptually:</p>

<pre><code class="language-javascript">useQuery({
    queryKey: ["products", search, category, sort],
    queryFn: fetchProducts
});
</code></pre>

<hr />

<h4 id="shopping-cart">Shopping Cart</h4>

<p>The cart may be needed by:</p>

<pre><code class="language-text">Header
Product Page
Checkout
Sidebar
</code></pre>

<p>This could be:</p>

<pre><code class="language-text">Shared Client State
</code></pre>

<p>or server state depending on how the cart is persisted and synchronized.</p>

<p>That’s an architectural decision.</p>

<hr />

<h4 id="number-of-products">Number of Products</h4>

<p>Suppose we already have:</p>

<pre><code class="language-javascript">products
</code></pre>

<p>Don’t necessarily store:</p>

<pre><code class="language-javascript">productCount
</code></pre>

<p>Just derive:</p>

<pre><code class="language-javascript">const productCount = products.length;
</code></pre>

<hr />

<p>Now our architecture is much clearer:</p>

<pre><code class="language-text">Product Search Page
       │
       ├── Filter drawer ──► Local State
       │
       ├── Search ─────────► URL
       │
       ├── Category ───────► URL
       │
       ├── Sort ───────────► URL
       │
       ├── Products ───────► Server Cache
       │
       ├── Cart ───────────► Shared State
       │
       └── Product Count ──► Derived
</code></pre>

<p>That’s state management.</p>

<p>Notice that we haven’t needed one giant store.</p>

<hr />

<h2 id="why-state-libraries-sometimes-make-things-worse">Why State Libraries Sometimes Make Things Worse</h2>

<p>Suppose a team decides:</p>

<blockquote>
  <p>“Everything goes in Redux.”</p>
</blockquote>

<p>Now adding a modal requires:</p>

<pre><code class="language-text">Action
Reducer
Selector
Dispatch
Store
</code></pre>

<p>even though:</p>

<pre><code class="language-javascript">useState(false)
</code></pre>

<p>would have solved the problem.</p>

<p>Or the team puts every API response into the store and manually implements:</p>

<pre><code class="language-text">Loading
Caching
Retries
Invalidation
Staleness
</code></pre>

<p>They end up rebuilding a server-state library.</p>

<p>Or they store pagination in global state and then write custom logic to synchronize it with the URL.</p>

<p>They’ve now created:</p>

<pre><code class="language-text">URL
  ↕
Redux
  ↕
Components
</code></pre>

<p>when:</p>

<pre><code class="language-text">URL
  ↓
Components
</code></pre>

<p>would have been simpler.</p>

<p>More powerful tools don’t automatically create simpler architecture.</p>

<hr />

<h2 id="why-state-libraries-sometimes-make-things-much-better">Why State Libraries Sometimes Make Things Much Better</h2>

<p>The opposite mistake is pretending every application can survive indefinitely on:</p>

<pre><code class="language-text">useState + props
</code></pre>

<p>Imagine a complex trading interface.</p>

<p>Dozens of components need access to:</p>

<pre><code class="language-text">Selected instrument
Open positions
Workspace layout
Active panels
Watchlists
Notifications
User preferences
</code></pre>

<p>Trying to thread everything through component hierarchies can become difficult.</p>

<p>A well-designed store can create:</p>

<pre><code class="language-text">                 Store
        ┌──────────┼──────────┐
        ▼          ▼          ▼
     Chart      Orders     Watchlist
</code></pre>

<p>Components subscribe only to the state they need.</p>

<p>The state transitions can be centralized and inspected.</p>

<p>The lesson isn’t:</p>

<pre><code class="language-text">Global stores are bad.
</code></pre>

<p>It’s:</p>

<pre><code class="language-text">Use global stores for genuinely shared
client-side state.
</code></pre>

<hr />

<h2 id="state-and-re-renders">State and Re-Renders</h2>

<p>State architecture also affects rendering performance.</p>

<p>Suppose a global context contains:</p>

<pre><code class="language-javascript">{
    user,
    cart,
    theme,
    notifications,
    sidebar,
    preferences
}
</code></pre>

<p>A change to:</p>

<pre><code class="language-text">sidebar
</code></pre>

<p>may cause consumers of that context to re-evaluate even if they only care about:</p>

<pre><code class="language-text">user
</code></pre>

<p>depending on how the architecture is implemented.</p>

<p>This is one reason state libraries often provide selectors.</p>

<p>Conceptually:</p>

<pre><code class="language-text">Global Store
    │
    ├── Component A subscribes to cart
    │
    ├── Component B subscribes to user
    │
    └── Component C subscribes to theme
</code></pre>

<p>When:</p>

<pre><code class="language-text">cart changes
</code></pre>

<p>we ideally want to notify only consumers that care about the cart. State management isn’t only about storing information. It’s also about efficiently distributing changes.</p>

<hr />

<h2 id="state-has-identity">State Has Identity</h2>

<p>There’s another subtle issue.</p>

<p>Consider:</p>

<pre><code class="language-javascript">const user = {
    name: "Billy"
};
</code></pre>

<p>Then:</p>

<pre><code class="language-javascript">const anotherUser = {
    name: "Billy"
};
</code></pre>

<p>Their contents look identical.</p>

<p>But:</p>

<pre><code class="language-javascript">user === anotherUser
</code></pre>

<p>is:</p>

<pre><code class="language-text">false
</code></pre>

<p>because they’re different objects.</p>

<p>This matters in reactive systems because object identity can influence:</p>

<pre><code class="language-text">Change detection
Memoization
Dependencies
Selectors
Re-renders
</code></pre>

<p>Carelessly recreating objects can therefore produce unnecessary updates. State management isn’t only about <strong>what values exist</strong>. Sometimes it’s also about <strong>whether the system considers those values changed</strong>.</p>

<hr />

<h2 id="immutable-updates">Immutable Updates</h2>

<p>React developers often encounter patterns such as:</p>

<pre><code class="language-javascript">setUser({
    ...user,
    name: "John"
});
</code></pre>

<p>instead of:</p>

<pre><code class="language-javascript">user.name = "John";
</code></pre>

<p>Why?</p>

<p>Because frameworks need reliable ways to understand that state changed.</p>

<p>With immutable-style updates:</p>

<pre><code class="language-text">Old State
   │
   ▼
Create New State
   │
   ▼
New Reference
</code></pre>

<p>the transition is easier to reason about.</p>

<p>For arrays:</p>

<pre><code class="language-javascript">setProducts(
    products.map(product =&gt;
        product.id === updated.id
            ? updated
            : product
    )
);
</code></pre>

<p>rather than mutating the existing array.</p>

<p>Different frameworks have different reactivity models, but the broader principle remains:</p>

<blockquote>
  <p><strong>Understand how your framework detects change.</strong></p>
</blockquote>

<hr />

<h2 id="deeply-nested-state-gets-painful">Deeply Nested State Gets Painful</h2>

<p>Consider:</p>

<pre><code class="language-javascript">const state = {
    user: {
        profile: {
            address: {
                city: "Nairobi"
            }
        }
    }
};
</code></pre>

<p>Updating the city immutably can become awkward:</p>

<pre><code class="language-javascript">setState({
    ...state,
    user: {
        ...state.user,
        profile: {
            ...state.user.profile,
            address: {
                ...state.user.profile.address,
                city: "Mombasa"
            }
        }
    }
});
</code></pre>

<p>The problem is partly the update syntax.</p>

<p>But it’s also the state shape.</p>

<p>React’s guidance suggests flattening deeply nested state where practical because it makes updates easier and helps reduce duplication. (<a href="https://react.dev/learn/choosing-the-state-structure?utm_source=chatgpt.com" title="Choosing the State Structure - React">React</a>)</p>

<p>Instead of thinking only:</p>

<blockquote>
  <p>How do I update this deeply nested object?</p>
</blockquote>

<p>sometimes ask:</p>

<blockquote>
  <p><strong>Should my state be shaped like this in the first place?</strong></p>
</blockquote>

<hr />

<h2 id="state-should-have-a-source-of-truth">State Should Have a Source of Truth</h2>

<p>Suppose a user’s name exists in:</p>

<pre><code class="language-text">Server
Redux
Header component
Profile form
localStorage
</code></pre>

<p>That’s five versions of:</p>

<pre><code class="language-text">Billy
</code></pre>

<p>Now the profile is changed.</p>

<pre><code class="language-text">Billy
  │
  ▼
William
</code></pre>

<p>Which copies update?</p>

<pre><code class="language-text">Server          William
Redux           William
Header          Billy
Profile Form    William
localStorage    Billy
</code></pre>

<p>Now the UI disagrees with itself.</p>

<p>A better architecture clearly defines:</p>

<pre><code class="language-text">Source of Truth
      │
      ▼
Other representations
</code></pre>

<p>For example:</p>

<pre><code class="language-text">Server
  │
  ▼
Query Cache
  │
  ├── Header
  ├── Profile
  └── Settings
</code></pre>

<p>One authoritative source.</p>

<p>Multiple consumers.</p>

<hr />

<h2 id="the-state-management-decision-tree">The State Management Decision Tree</h2>

<p>Before adding state, ask:</p>

<p><strong>Can this value be calculated from existing information?</strong></p>

<p>If yes:</p>

<pre><code class="language-text">Derive it.
</code></pre>

<p>If no:</p>

<p><strong>Does only one component need it?</strong></p>

<p>If yes:</p>

<pre><code class="language-text">Keep it local.
</code></pre>

<p>If multiple nearby components need it:</p>

<pre><code class="language-text">Lift it to their common owner.
</code></pre>

<p>If it represents navigation or shareable page configuration:</p>

<pre><code class="language-text">Consider the URL.
</code></pre>

<p>If it came from a backend:</p>

<pre><code class="language-text">Treat it as server state.
</code></pre>

<p>If it’s complex form interaction:</p>

<pre><code class="language-text">Treat it as form state.
</code></pre>

<p>If it’s genuinely shared client information:</p>

<pre><code class="language-text">Consider Context or a store.
</code></pre>

<p>If it must survive sessions:</p>

<pre><code class="language-text">Consider persistence deliberately.
</code></pre>

<p>The process looks like:</p>

<pre><code class="language-text">                   New State
                       │
                       ▼
              Can it be derived?
                 /           \
               Yes            No
                │              │
             Derive       Who owns it?
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
          Component          URL            Server
              │                               │
              ▼                               ▼
         Local State                     Query Cache

                 Shared broadly?
                       │
                       ▼
                  Global Store
</code></pre>

<hr />

<h2 id="the-best-state-is-often-no-state">The Best State Is Often No State</h2>

<p>This sounds strange in an article about state management.</p>

<p>But one of the strongest state-management techniques is simply <strong>removing unnecessary state</strong>.</p>

<p>Instead of:</p>

<pre><code class="language-javascript">const [items, setItems] = useState([]);
const [itemCount, setItemCount] = useState(0);
const [hasItems, setHasItems] = useState(false);
</code></pre>

<p>store:</p>

<pre><code class="language-javascript">const [items, setItems] = useState([]);
</code></pre>

<p>and derive:</p>

<pre><code class="language-javascript">const itemCount = items.length;
const hasItems = items.length &gt; 0;
</code></pre>

<p>We’ve gone from:</p>

<pre><code class="language-text">3 synchronized variables
</code></pre>

<p>to:</p>

<pre><code class="language-text">1 source of truth
</code></pre>

<p>React’s documentation emphasizes avoiding redundant and duplicate state precisely because fewer independent pieces of state are easier to keep consistent. (<a href="https://react.dev/learn/choosing-the-state-structure?utm_source=chatgpt.com" title="Choosing the State Structure - React">React</a>)</p>

<p>That’s a lesson that applies far beyond React.</p>

<hr />

<h2 id="bringing-it-all-together">Bringing It All Together</h2>

<p>Frontend state becomes complicated because we’re often using the word <strong>state</strong> to describe many different problems.</p>

<pre><code class="language-text">                     STATE
                       │
       ┌───────────────┼────────────────┐
       │               │                │
       ▼               ▼                ▼
   UI State        Server State      URL State
       │               │                │
       ▼               ▼                ▼
 Component          Query Cache        Router

       ┌───────────────┼────────────────┐
       │               │                │
       ▼               ▼                ▼
  Form State      Shared State     Derived Data
       │               │                │
       ▼               ▼                ▼
 Form Manager      Global Store      Calculate
</code></pre>

<p>Trying to force all of these into one state-management solution creates complexity.</p>

<p>The better approach is to understand the ownership and lifecycle of each value.</p>

<p>Ask:</p>

<pre><code class="language-text">Where did this value come from?

Who owns it?

Who needs it?

How long should it live?

Can it be derived?

Does it need to survive navigation?

Does it belong in the URL?

Is the server actually the source of truth?
</code></pre>

<p>Once those questions are answered, the technology choice becomes much easier.</p>

<hr />

<h2 id="final-thoughts">Final Thoughts</h2>

<p>State management is often presented as a library problem. React developers debate Redux versus Zustand, Vue developers discuss Pinia, and other ecosystems introduce signals, stores, atoms, observables, and new reactive primitives. Those tools matter, but they come <strong>after</strong> the more important architectural decision.</p>

<p>You first need to model your state correctly. A badly designed state model doesn’t become good because you put it into Redux. Duplicated state doesn’t stop being duplicated because Zustand stores it. Server state doesn’t stop becoming stale because Context distributes it. And a filter that belongs in the URL doesn’t suddenly belong somewhere else because your state library has persistence.</p>

<p>Good frontend state management is mostly about maintaining clear ownership and minimizing sources of truth.</p>

<p>So instead of beginning with:</p>

<blockquote>
  <p><strong>“Which state management library should we use?”</strong></p>
</blockquote>

<p>begin with:</p>

<blockquote>
  <p><strong>“What kind of state is this, and where does it naturally belong?”</strong></p>
</blockquote>

<p>That question solves far more problems.</p>

<hr />

<h2 id="whats-next">What’s Next?</h2>

<p>So far in <strong>Beyond the UI</strong>, we’ve moved through several layers of the frontend:</p>

<pre><code class="language-text">Browser Rendering Pipeline
          │
          ▼
Reflow and Repaint
          │
          ▼
JavaScript Event Loop
          │
          ▼
CSR vs SSR
          │
          ▼
Hydration
          │
          ▼
State Management
</code></pre>

<p>We’ve now seen how the browser renders an application, how JavaScript gets scheduled, how applications can be rendered on the server, how hydration makes them interactive, and how their changing data can be organized.</p>

<p>But there’s another performance problem hiding inside modern frontend applications. You update one small piece of state:</p>

<pre><code class="language-javascript">setCount(count + 1);
</code></pre>

<p>and suddenly multiple components execute again. Why? What does “re-render” actually mean? Does re-rendering mean the DOM was rebuilt? When does React actually touch the browser DOM? And when should you use tools such as <code>memo</code>, <code>useMemo</code>, and <code>useCallback</code>?</p>

<p>That’s where we’ll go next:</p>

<blockquote>
  <p><strong>Re-Renders Explained: What Actually Happens When Frontend State Changes</strong></p>
</blockquote>

<p>Because before trying to prevent re-renders, you need to understand what a re-render actually costs.</p>

]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="Frontend" />
    
    <category term="Performance" />
    
  

  
    
    <category term="Frontend" />
    
    <category term="Performance" />
    
  

    <summary>State management is the process of managing the state of an application. This article explains what state management is, how it works, and why it is important.</summary>

  </entry>

  
  





  



  


  <entry>
    <title>Hydration Explained: How Server-Rendered Pages Become Interactive</title>
    <link href="https://billyokeyo.dev/posts/hydration/" rel="alternate" type="text/html" title="Hydration Explained: How Server-Rendered Pages Become Interactive" />
    <published>2026-08-31T00:00:00+00:00</published>
  
    <updated>2026-08-31T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/hydration/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/hydration/"><![CDATA[<blockquote>
  <p><em>“Server-side rendering can make a page visible before JavaScript arrives. Hydration is what turns that visible HTML into an interactive application.”</em></p>
</blockquote>

<p>In the previous article in <strong>Beyond the UI</strong>, we compared Client-Side Rendering and Server-Side Rendering.</p>

<p>With Client-Side Rendering, the browser might initially receive something as small as:</p>

<pre><code class="language-html">&lt;div id="root"&gt;&lt;/div&gt;
&lt;script src="https://billyokeyo.dev/app.js"&gt;&lt;/script&gt;
</code></pre>

<p>JavaScript then constructs the interface in the browser.</p>

<p>With Server-Side Rendering, the server can send meaningful HTML immediately:</p>

<pre><code class="language-html">&lt;article class="product"&gt;
    &lt;h1&gt;Mechanical Keyboard&lt;/h1&gt;
    &lt;p&gt;KES 12,000&lt;/p&gt;

    &lt;button&gt;
        Add to Cart
    &lt;/button&gt;
&lt;/article&gt;
</code></pre>

<p>The browser can parse and display that HTML without waiting for React, Vue, or another framework to construct it.</p>

<p>That sounds like the problem is solved. The user can see the product, the button is visible, and the page looks complete. But then the user clicks:</p>

<pre><code class="language-text">Add to Cart
</code></pre>

<p>and nothing happens. Why?</p>

<p>Because HTML can describe the button, but the server-rendered document doesn’t automatically contain the JavaScript behavior that your application expects.</p>

<p>The browser may know:</p>

<pre><code class="language-text">There is a button here.
</code></pre>

<p>But your framework still needs to establish:</p>

<pre><code class="language-text">When this button is clicked,
update the shopping cart.
</code></pre>

<p>That transition, from <strong>server-rendered HTML</strong> to <strong>interactive application</strong>, is where hydration comes in.</p>

<p>At a high level:</p>

<pre><code class="language-text">Server
   │
   ▼
Render Components
   │
   ▼
HTML
   │
   ▼
Browser Displays HTML
   │
   ▼
JavaScript Loads
   │
   ▼
Hydration
   │
   ▼
Interactive Application
</code></pre>

<p>Hydration sounds simple, but it introduces some of the most interesting performance and architecture challenges in modern frontend development. So let’s follow a page through the process.</p>

<hr />

<h2 id="first-what-exactly-is-hydration">First, What Exactly Is Hydration?</h2>

<p><strong>Hydration is the process through which client-side JavaScript attaches application behavior to HTML that was already rendered on the server.</strong></p>

<p>Imagine a React component:</p>

<pre><code class="language-jsx">function Counter() {
    const [count, setCount] = useState(0);

    return (
        &lt;button onClick={() =&gt; setCount(count + 1)}&gt;
            Count: {count}
        &lt;/button&gt;
    );
}
</code></pre>

<p>When server-rendered, the browser may initially receive:</p>

<pre><code class="language-html">&lt;button&gt;
    Count: 0
&lt;/button&gt;
</code></pre>

<p>That’s perfectly valid HTML. The browser can display it.</p>

<pre><code class="language-text">┌────────────────┐
│    Count: 0    │
└────────────────┘
</code></pre>

<p>But the HTML response itself doesn’t contain React’s <code>setCount</code> function or the component’s runtime state. The browser still needs the relevant JavaScript. Once that JavaScript arrives, React can connect the existing DOM to the application.</p>

<p>Conceptually:</p>

<pre><code class="language-text">Existing HTML

&lt;button&gt;
    Count: 0
&lt;/button&gt;

        +

Client JavaScript

Counter()
useState()
onClick()

        │
        ▼

     Hydration

        │
        ▼

Interactive Button
</code></pre>

<p>After hydration, clicking the button can update the state:</p>

<pre><code class="language-text">Count: 0
   │
   │ click
   ▼
Count: 1
</code></pre>

<p>The key idea is that the framework isn’t necessarily throwing away the server-generated HTML and starting again. It attempts to <strong>reuse the existing DOM and attach the behavior needed to make it interactive</strong>.</p>

<hr />

<h2 id="why-do-we-need-hydration">Why Do We Need Hydration?</h2>

<p>Why not simply let the server render the page and leave it there? For some websites, that’s perfectly reasonable. A simple article might require almost no JavaScript. But modern applications often contain interactions such as:</p>

<pre><code class="language-text">Add to Cart
Like Post
Open Modal
Submit Form
Filter Results
Expand Menu
Update Counter
Drag Item
Search
</code></pre>

<p>Those interactions require application logic somewhere.</p>

<p>For example:</p>

<pre><code class="language-jsx">function AddToCart({ product }) {
    const [adding, setAdding] = useState(false);

    async function addToCart() {
        setAdding(true);

        await api.addToCart(product.id);

        setAdding(false);
    }

    return (
        &lt;button onClick={addToCart}&gt;
            {adding ? "Adding..." : "Add to Cart"}
        &lt;/button&gt;
    );
}
</code></pre>

<p>The server can render:</p>

<pre><code class="language-html">&lt;button&gt;
    Add to Cart
&lt;/button&gt;
</code></pre>

<p>But the browser still needs the JavaScript responsible for:</p>

<pre><code class="language-text">Click
  │
  ▼
Set loading state
  │
  ▼
Call API
  │
  ▼
Update cart
  │
  ▼
Update button
</code></pre>

<p>Hydration bridges the gap between <strong>HTML generated elsewhere</strong> and <strong>behavior running in the browser</strong>.</p>

<hr />

<h2 id="the-full-server-rendering-journey">The Full Server-Rendering Journey</h2>

<p>Let’s look at the entire process. Suppose a user requests:</p>

<pre><code class="language-text">/products/42
</code></pre>

<p>The server receives the request.</p>

<pre><code class="language-text">Browser
   │
   │ GET /products/42
   ▼
Server
</code></pre>

<p>The server fetches the product:</p>

<pre><code class="language-javascript">const product = await database.products.findById(42);
</code></pre>

<p>It renders the application:</p>

<pre><code class="language-jsx">&lt;ProductPage product={product} /&gt;
</code></pre>

<p>which becomes HTML:</p>

<pre><code class="language-html">&lt;main&gt;
    &lt;h1&gt;Mechanical Keyboard&lt;/h1&gt;

    &lt;p&gt;KES 12,000&lt;/p&gt;

    &lt;button&gt;
        Add to Cart
    &lt;/button&gt;
&lt;/main&gt;
</code></pre>

<p>The response reaches the browser. Now everything we’ve discussed earlier in this series begins happening.</p>

<pre><code class="language-text">HTML
 │
 ▼
DOM
 │
 ▼
Layout
 │
 ▼
Paint
 │
 ▼
Pixels
</code></pre>

<p>The user sees the page. Meanwhile, JavaScript required by the application is downloaded.</p>

<pre><code class="language-text">HTML visible
     │
     ├──────────────► User sees content
     │
     ▼
JavaScript downloads
     │
     ▼
JavaScript parses
     │
     ▼
JavaScript executes
     │
     ▼
Hydration
     │
     ▼
Application interactive
</code></pre>

<p>This creates an important distinction. A page can be:</p>

<blockquote>
  <p><strong>Visible</strong></p>
</blockquote>

<p>without yet being:</p>

<blockquote>
  <p><strong>Fully interactive</strong></p>
</blockquote>

<hr />

<h2 id="visible-does-not-mean-interactive">Visible Does Not Mean Interactive</h2>

<p>This is one of the most important concepts to understand about hydration.</p>

<p>Imagine the following timeline:</p>

<pre><code class="language-text">0ms
User requests page

      │
      ▼

300ms
HTML arrives

      │
      ▼

400ms
Content visible

      │
      ▼

800ms
JavaScript downloaded

      │
      ▼

1100ms
JavaScript executed

      │
      ▼

1300ms
Hydration completed
</code></pre>

<p>Between roughly:</p>

<pre><code class="language-text">400ms → 1300ms
</code></pre>

<p>the page may <strong>look ready</strong>.</p>

<p>The user can see:</p>

<pre><code class="language-text">Product

Mechanical Keyboard

KES 12,000

[ Add to Cart ]
</code></pre>

<p>But depending on the application and framework behavior, the client-side interaction may not yet be ready. The user sees a button. Naturally, they click it. If the required JavaScript hasn’t become operational yet, that interaction can be delayed or require special handling by the framework.</p>

<p>This creates an interesting UX problem:</p>

<blockquote>
  <p><strong>A page can visually promise interactivity before it is ready to deliver it.</strong></p>
</blockquote>

<hr />

<h2 id="hydration-is-not-free">Hydration Is Not Free</h2>

<p>SSR is sometimes described as though it simply moves rendering from the browser to the server. But with traditional hydration-heavy architectures, the browser can still have significant work to perform.</p>

<p>Consider this application:</p>

<pre><code class="language-text">Server
   │
   ▼
Render React Application
   │
   ▼
Send HTML
</code></pre>

<p>Then:</p>

<pre><code class="language-text">Browser
   │
   ├── Parse HTML
   ├── Render page
   ├── Download React
   ├── Download application JS
   ├── Parse JavaScript
   ├── Execute JavaScript
   └── Hydrate application
</code></pre>

<p>The server rendered the interface. But the browser may still need much of the JavaScript representation of that application so the framework can make it interactive.</p>

<p>In simplified form:</p>

<pre><code class="language-text">SERVER                         CLIENT

Render Components
       │
       ▼
      HTML ──────────────────► Display HTML
                                │
JavaScript ──────────────────► Download
                                │
                                ▼
                              Parse
                                │
                                ▼
                             Execute
                                │
                                ▼
                             Hydrate
</code></pre>

<p>For a small application, this may be cheap. For a large application, hydration can involve a significant amount of work.</p>

<hr />

<h2 id="the-double-work-problem">The Double-Work Problem</h2>

<p>This leads to one criticism of traditional hydration architectures.</p>

<p>The server does work:</p>

<pre><code class="language-text">Components
    │
    ▼
HTML
</code></pre>

<p>Then the client receives JavaScript describing much of the same application and performs additional work to reconstruct the application’s runtime representation and connect it to the existing DOM.</p>

<p>Conceptually:</p>

<pre><code class="language-text">SERVER

Component Tree
     │
     ▼
HTML


CLIENT

HTML
 +
Component JavaScript
 +
Application State
     │
     ▼
Hydration
</code></pre>

<p>The server rendering was useful because the user received content earlier. But the client hasn’t escaped JavaScript execution.</p>

<p>In some architectures, we’ve effectively said:</p>

<blockquote>
  <p>“Render this application on the server so users can see it quickly, then send enough JavaScript for the browser to understand much of that application again.”</p>
</blockquote>

<p>This trade-off becomes increasingly noticeable as applications grow.</p>

<hr />

<h2 id="a-react-hydration-example">A React Hydration Example</h2>

<p>Consider a small server-rendered React application.</p>

<p>On the server, conceptually:</p>

<pre><code class="language-jsx">const html = renderToString(&lt;App /&gt;);
</code></pre>

<p>The resulting HTML is sent to the browser.</p>

<p>On the client, instead of creating a completely new DOM tree with:</p>

<pre><code class="language-javascript">createRoot(root).render(&lt;App /&gt;);
</code></pre>

<p>a server-rendered React application can hydrate the existing DOM:</p>

<pre><code class="language-javascript">import { hydrateRoot } from "react-dom/client";

hydrateRoot(
    document.getElementById("root"),
    &lt;App /&gt;
);
</code></pre>

<p>The distinction is important.</p>

<p><code>createRoot()</code> effectively says:</p>

<blockquote>
  <p>Build this client application in this root.</p>
</blockquote>

<p><code>hydrateRoot()</code> says:</p>

<blockquote>
  <p>There is already server-generated HTML here. Connect React to it.</p>
</blockquote>

<p>Conceptually:</p>

<pre><code class="language-text">Server HTML

&lt;div id="root"&gt;
    &lt;button&gt;Count: 0&lt;/button&gt;
&lt;/div&gt;

        │
        ▼

hydrateRoot(...)

        │
        ▼

React connects to
existing DOM

        │
        ▼

Interactive Application
</code></pre>

<p>This works well when the client expects the same interface the server produced. But what happens when it doesn’t?</p>

<hr />

<h2 id="hydration-mismatches">Hydration Mismatches</h2>

<p>Suppose the server renders:</p>

<pre><code class="language-html">&lt;p&gt;Welcome back, Billy&lt;/p&gt;
</code></pre>

<p>but when the client begins hydrating, React expects:</p>

<pre><code class="language-html">&lt;p&gt;Welcome back, Guest&lt;/p&gt;
</code></pre>

<p>Now the server and client disagree. This is a <strong>hydration mismatch</strong>.</p>

<p>Conceptually:</p>

<pre><code class="language-text">SERVER HTML

Welcome back, Billy

        ≠

CLIENT EXPECTATION

Welcome back, Guest
</code></pre>

<p>Frameworks may warn about this because hydration depends on the initial server and client output being compatible. A mismatch can cause the framework to repair or re-render portions of the UI, and it can lead to confusing bugs.</p>

<hr />

<h2 id="how-hydration-mismatches-happen">How Hydration Mismatches Happen</h2>

<p>Some mismatches are surprisingly easy to create.</p>

<p>Consider:</p>

<pre><code class="language-jsx">function CurrentTime() {
    return &lt;p&gt;{new Date().toLocaleTimeString()}&lt;/p&gt;;
}
</code></pre>

<p>The server renders at:</p>

<pre><code class="language-text">10:42:01
</code></pre>

<p>By the time the browser hydrates:</p>

<pre><code class="language-text">10:42:03
</code></pre>

<p>The output may differ.</p>

<p>Another classic example is random values:</p>

<pre><code class="language-jsx">function Identifier() {
    return &lt;p&gt;{Math.random()}&lt;/p&gt;;
}
</code></pre>

<p>The server might produce:</p>

<pre><code class="language-text">0.21843
</code></pre>

<p>while the client produces:</p>

<pre><code class="language-text">0.79216
</code></pre>

<p>That’s a mismatch.</p>

<p>Browser-only information can cause similar problems.</p>

<pre><code class="language-javascript">window.innerWidth
localStorage
navigator.language
</code></pre>

<p>Those values may not exist on the server or may differ from what the server assumed.</p>

<hr />

<h2 id="a-more-subtle-example-authentication">A More Subtle Example: Authentication</h2>

<p>Suppose the server knows the user is authenticated. It renders:</p>

<pre><code class="language-html">&lt;nav&gt;
    &lt;span&gt;Welcome Billy&lt;/span&gt;
    &lt;button&gt;Logout&lt;/button&gt;
&lt;/nav&gt;
</code></pre>

<p>But your client-side authentication store initially starts with:</p>

<pre><code class="language-javascript">const user = null;
</code></pre>

<p>The client expects:</p>

<pre><code class="language-html">&lt;nav&gt;
    &lt;button&gt;Login&lt;/button&gt;
&lt;/nav&gt;
</code></pre>

<p>Again:</p>

<pre><code class="language-text">Server
   │
   └── Authenticated

Client initial state
   │
   └── Not authenticated

        ↓

Hydration mismatch
</code></pre>

<p>The solution is often to make sure the initial client state is derived from the same data used to generate the server output.</p>

<p>Conceptually:</p>

<pre><code class="language-text">Server Data
    │
    ├── Render HTML
    │
    └── Serialize initial state
              │
              ▼
            Client
              │
              ▼
           Hydration
</code></pre>

<p>The server and client need to agree about what the initial page represents.</p>

<hr />

<h2 id="why-hydration-can-become-expensive">Why Hydration Can Become Expensive</h2>

<p>Imagine a large e-commerce homepage containing:</p>

<pre><code class="language-text">Header
Navigation
Search
Hero
Recommendations
Categories
Products
Reviews
Newsletter
Footer
</code></pre>

<p>Suppose only a few parts are actually interactive:</p>

<pre><code class="language-text">Search
Cart
Product carousel
Newsletter form
</code></pre>

<p>With a traditional full-page hydration model, the browser may still receive JavaScript for a much larger component tree.</p>

<p>Conceptually:</p>

<pre><code class="language-text">Page
│
├── Header
├── Navigation
├── Hero
├── Categories
├── Products
├── Reviews
├── Newsletter
└── Footer

        │
        ▼

Hydrate Everything
</code></pre>

<p>But much of the page may simply be content. The hero doesn’t necessarily need client-side JavaScript, the footer probably doesn’t need React state, and a product description may never change after rendering. So why hydrate everything?</p>

<p>That question has driven several newer frontend architecture ideas.</p>

<hr />

<h2 id="partial-hydration">Partial Hydration</h2>

<p>Instead of hydrating the entire page, what if we hydrate only the interactive parts?</p>

<p>Imagine:</p>

<pre><code class="language-text">Page
│
├── Header
│
├── Search ◄──── HYDRATE
│
├── Hero
│
├── Product Grid
│
├── Cart Button ◄ HYDRATE
│
├── Article Content
│
└── Footer
</code></pre>

<p>Now static content remains HTML. Interactive pieces receive JavaScript.</p>

<p>Conceptually:</p>

<pre><code class="language-text">Server HTML
│
├── Static
├── Static
├── Interactive Island + JS
├── Static
├── Interactive Island + JS
└── Static
</code></pre>

<p>This is broadly the idea behind <strong>partial hydration</strong> and related “islands” architectures.</p>

<p>The goal is straightforward:</p>

<blockquote>
  <p><strong>Don’t ship JavaScript for parts of the page that don’t need JavaScript.</strong></p>
</blockquote>

<hr />

<h2 id="islands-architecture">Islands Architecture</h2>

<p>Astro is well known for popularizing this model.</p>

<p>Imagine a page:</p>

<pre><code class="language-text">┌───────────────────────────────────────┐
│              Header                   │
├───────────────────────────────────────┤
│                                       │
│          Static Article               │
│                                       │
│       No client JS required           │
│                                       │
├───────────────────────────────────────┤
│       Interactive Comments            │ ◄── JS
├───────────────────────────────────────┤
│              Footer                   │
└───────────────────────────────────────┘
</code></pre>

<p>The interactive component becomes an <strong>island</strong> inside mostly static HTML.</p>

<p>Instead of:</p>

<pre><code class="language-text">Entire Page
    │
    ▼
Hydrate Everything
</code></pre>

<p>we get:</p>

<pre><code class="language-text">Static HTML
    │
    ├── Interactive Island
    │        │
    │        ▼
    │     Hydrate
    │
    └── Static HTML
</code></pre>

<p>For content-heavy sites, this can dramatically reduce the amount of client JavaScript required.</p>

<hr />

<h2 id="lazy-hydration">Lazy Hydration</h2>

<p>Even when a component needs JavaScript, it doesn’t necessarily need it immediately. Consider a comments section at the bottom of a long article. The user might never scroll that far. Hydrating it immediately means spending resources on something the user may never interact with. Instead, hydration can be delayed until a condition is met.</p>

<p>For example:</p>

<pre><code class="language-text">Page Loads
    │
    ▼
Comments not visible
    │
    ▼
Do nothing
    │
    │
User scrolls
    │
    ▼
Comments approach viewport
    │
    ▼
Load / Hydrate
</code></pre>

<p>Other triggers could include:</p>

<pre><code class="language-text">When visible
When browser is idle
When user interacts
After important content is ready
</code></pre>

<p>This shifts hydration from:</p>

<blockquote>
  <p>Hydrate everything now.</p>
</blockquote>

<p>to:</p>

<blockquote>
  <p>Hydrate something when there’s a reason to.</p>
</blockquote>

<hr />

<h2 id="selective-hydration">Selective Hydration</h2>

<p>Another approach is <strong>selective hydration</strong>.</p>

<p>Suppose a page has several sections waiting to hydrate.</p>

<pre><code class="language-text">Header
Product Details
Reviews
Recommendations
Footer
</code></pre>

<p>The user clicks something in the header before everything else has completed. Instead of requiring hydration to proceed strictly from top to bottom, a framework can prioritize the part relevant to the user’s interaction.</p>

<p>Conceptually:</p>

<pre><code class="language-text">Hydration Queue

Product Details
Reviews
Recommendations
Header
Footer

User clicks Header

        │
        ▼

Prioritize Header
</code></pre>

<p>The broader principle is important:</p>

<blockquote>
  <p><strong>Not all parts of a page are equally urgent.</strong></p>
</blockquote>

<p>Modern rendering architectures increasingly try to schedule work according to what matters most to the user.</p>

<hr />

<h2 id="streaming-makes-things-even-more-interesting">Streaming Makes Things Even More Interesting</h2>

<p>Traditional SSR can look like:</p>

<pre><code class="language-text">Request
   │
   ▼
Fetch EVERYTHING
   │
   ▼
Render EVERYTHING
   │
   ▼
Send HTML
</code></pre>

<p>If one slow data source takes two seconds, the entire page might wait. Streaming SSR allows the server to begin sending useful parts of the page earlier.</p>

<p>Conceptually:</p>

<pre><code class="language-text">Request
   │
   ▼
Server

Header ready ───────────────► Browser

Main content ready ─────────► Browser

Recommendations still loading...

Recommendations ready ──────► Browser
</code></pre>

<p>Instead of one giant response arriving after everything is complete, HTML can arrive progressively. Combine that with modern hydration techniques and you get something closer to:</p>

<pre><code class="language-text">HTML arrives
     │
     ▼
Content appears
     │
     ▼
More HTML streams
     │
     ▼
Relevant JavaScript arrives
     │
     ▼
Interactive regions hydrate
</code></pre>

<p>The line between “loading” and “loaded” becomes much less binary.</p>

<hr />

<h2 id="react-server-components-change-the-question">React Server Components Change the Question</h2>

<p>React Server Components take a more fundamental approach.</p>

<p>Consider:</p>

<pre><code class="language-jsx">function ProductDescription({ product }) {
    return (
        &lt;section&gt;
            &lt;h1&gt;{product.name}&lt;/h1&gt;
            &lt;p&gt;{product.description}&lt;/p&gt;
        &lt;/section&gt;
    );
}
</code></pre>

<p>If this component doesn’t need:</p>

<pre><code class="language-text">State
Effects
Browser APIs
Event handlers
</code></pre>

<p>why does its component JavaScript need to run in the browser? With Server Components, it may not.</p>

<p>Conceptually:</p>

<pre><code class="language-text">SERVER

ProductDescription
Reviews
ProductDetails

        │
        ▼

Rendered representation

        │
        ▼

CLIENT

AddToCartButton
Search
Cart
</code></pre>

<p>Only components that require client-side behavior need to become part of the browser’s interactive JavaScript application.</p>

<p>This changes the conversation from:</p>

<blockquote>
  <p>How do we hydrate the entire server-rendered application efficiently?</p>
</blockquote>

<p>toward:</p>

<blockquote>
  <p><strong>How much of this application needs hydration at all?</strong></p>
</blockquote>

<p>That’s a much more powerful question.</p>

<hr />

<h2 id="server-components-vs-hydration">Server Components vs Hydration</h2>

<p>It’s worth separating the concepts.</p>

<p>A traditional server-rendered client component might go through:</p>

<pre><code class="language-text">Server Render
     │
     ▼
HTML
     │
     ▼
Browser
     │
     ▼
Hydration
</code></pre>

<p>A server-only component doesn’t need to become an interactive client component.</p>

<pre><code class="language-text">Server Component
     │
     ▼
Server
     │
     ▼
Rendered output
     │
     ▼
Browser

No equivalent component
JavaScript required
for hydration
</code></pre>

<p>But interactive client components still need browser JavaScript.</p>

<p>For example:</p>

<pre><code class="language-jsx">"use client";

function AddToCart() {
    const [quantity, setQuantity] = useState(1);

    return (
        &lt;button onClick={() =&gt; add(quantity)}&gt;
            Add to Cart
        &lt;/button&gt;
    );
}
</code></pre>

<p>So a modern page may contain both:</p>

<pre><code class="language-text">Server Components
       │
       └── No client hydration for their component logic

Client Components
       │
       └── Need client-side JavaScript / hydration
</code></pre>

<p>Again, modern frontend architecture is increasingly about choosing boundaries.</p>

<hr />

<h2 id="hydration-and-the-main-thread">Hydration and the Main Thread</h2>

<p>Now let’s connect hydration to our previous article on the JavaScript event loop.</p>

<p>Suppose the browser downloads a large JavaScript bundle. It needs to:</p>

<pre><code class="language-text">Download
   │
   ▼
Parse
   │
   ▼
Compile
   │
   ▼
Execute
   │
   ▼
Hydrate
</code></pre>

<p>Much of that work interacts with the browser’s main thread.</p>

<p>If hydration becomes expensive:</p>

<pre><code class="language-text">Main Thread

┌──────────────────────────────┐
│      JavaScript              │
├──────────────────────────────┤
│      Hydration               │
├──────────────────────────────┤
│      More Hydration          │
└──────────────────────────────┘
</code></pre>

<p>user interactions may have to compete with that work.</p>

<p>Remember our earlier lesson:</p>

<blockquote>
  <p>A page can look ready while JavaScript is still occupying the main thread.</p>
</blockquote>

<p>This is why shipping less JavaScript isn’t merely about reducing network transfer.</p>

<p>It can also mean:</p>

<pre><code class="language-text">Less parsing
Less compilation
Less execution
Less hydration
Less main-thread work
</code></pre>

<p>The network is only part of the cost.</p>

<hr />

<h2 id="hydration-and-the-rendering-pipeline">Hydration and the Rendering Pipeline</h2>

<p>Hydration also connects directly to our first two articles. Hydration may update DOM state, DOM updates can invalidate styles, some updates may trigger layout, and layout changes may require painting. So the full picture can become:</p>

<pre><code class="language-text">Server HTML
     │
     ▼
Browser Parses HTML
     │
     ▼
Initial Render
     │
     ▼
JavaScript Loads
     │
     ▼
Hydration
     │
     ▼
DOM / State Updates
     │
     ▼
Style
     │
     ▼
Layout
     │
     ▼
Paint
     │
     ▼
Composite
</code></pre>

<p>The concepts in this series aren’t isolated. They form one system.</p>

<hr />

<h2 id="why-huge-javascript-bundles-hurt-ssr-too">Why Huge JavaScript Bundles Hurt SSR Too</h2>

<p>Imagine two applications. Both server-render their HTML in:</p>

<pre><code class="language-text">300ms
</code></pre>

<p>Application A sends:</p>

<pre><code class="language-text">80 KB JavaScript
</code></pre>

<p>Application B sends:</p>

<pre><code class="language-text">2 MB JavaScript
</code></pre>

<p>Both might display meaningful content quickly. But the browser still has very different workloads.</p>

<pre><code class="language-text">Application A

HTML
 │
 ▼
Small JS
 │
 ▼
Hydrate
 │
 ▼
Interactive


Application B

HTML
 │
 ▼
Large JS
 │
 ▼
Download
 │
 ▼
Parse
 │
 ▼
Execute
 │
 ▼
Hydrate
 │
 ▼
Interactive
</code></pre>

<p>This is why saying:</p>

<blockquote>
  <p>“We’re using SSR, so initial performance is solved.”</p>
</blockquote>

<p>can be misleading. SSR addresses only part of the journey.</p>

<hr />

<h2 id="what-about-event-handlers">What About Event Handlers?</h2>

<p>A common simplified explanation of hydration says:</p>

<blockquote>
  <p>“Hydration attaches event listeners to server-rendered HTML.”</p>
</blockquote>

<p>That’s useful as an introduction, but hydration generally involves more than literally walking through every element and calling <code>addEventListener</code>. Frameworks have different event systems and hydration strategies. For example, React uses event delegation for many events.</p>

<p>The more accurate mental model is:</p>

<blockquote>
  <p><strong>Hydration connects server-rendered DOM with the client framework’s runtime representation so that state, events, and future updates can behave correctly.</strong></p>
</blockquote>

<p>Think:</p>

<pre><code class="language-text">Static Server DOM

        +

Client Application Runtime

        │
        ▼

Connected Interactive UI
</code></pre>

<p>rather than simply:</p>

<pre><code class="language-text">HTML + click handlers
</code></pre>

<hr />

<h2 id="hydration-errors-are-architecture-clues">Hydration Errors Are Architecture Clues</h2>

<p>When developers encounter hydration warnings, the instinct is often to silence them. But a mismatch can reveal an architectural problem.</p>

<p>For example:</p>

<pre><code class="language-jsx">function Theme() {
    const theme = localStorage.getItem("theme");

    return &lt;div className={theme}&gt;...&lt;/div&gt;;
}
</code></pre>

<p>This code assumes browser storage exists. The server cannot make the same assumption. If the component participates in SSR, you need to think carefully about where that value should come from and when it should be read.</p>

<p>Likewise:</p>

<pre><code class="language-jsx">&lt;p&gt;{window.innerWidth}&lt;/p&gt;
</code></pre>

<p>asks for browser-specific state during rendering.</p>

<p>Hydration forces us to confront a fundamental reality:</p>

<pre><code class="language-text">Server Environment
       ≠
Browser Environment
</code></pre>

<p>Code that crosses that boundary needs to be designed accordingly.</p>

<hr />

<h2 id="a-practical-example-theme-preference">A Practical Example: Theme Preference</h2>

<p>Suppose a user prefers dark mode. The browser has:</p>

<pre><code class="language-javascript">localStorage.setItem("theme", "dark");
</code></pre>

<p>But the server doesn’t have access to that browser storage. It renders:</p>

<pre><code class="language-html">&lt;body class="light"&gt;
</code></pre>

<p>Then the browser loads JavaScript and discovers:</p>

<pre><code class="language-text">Theme = dark
</code></pre>

<p>The page switches:</p>

<pre><code class="language-text">Light
  │
  ▼
Dark
</code></pre>

<p>The user may see a flash of the wrong theme. This isn’t necessarily a hydration problem alone, but it demonstrates how server/client differences can become visible.</p>

<p>One solution might be storing the preference in a cookie the server can read.</p>

<p>Then:</p>

<pre><code class="language-text">Cookie
  │
  ├────► Server renders dark
  │
  └────► Client initializes dark
</code></pre>

<p>Both sides agree.</p>

<p>This illustrates a broader principle:</p>

<blockquote>
  <p><strong>The closer server and client are to sharing the same initial truth, the smoother hydration becomes.</strong></p>
</blockquote>

<hr />

<h2 id="a-practical-example-responsive-rendering">A Practical Example: Responsive Rendering</h2>

<p>Suppose the server tries to render different markup for mobile and desktop.</p>

<pre><code class="language-jsx">if (window.innerWidth &lt; 768) {
    return &lt;MobileNavigation /&gt;;
}

return &lt;DesktopNavigation /&gt;;
</code></pre>

<p>There’s an immediate problem. On the server, <code>window</code> doesn’t exist. You could guess based on request information, but that guess may differ from the browser’s actual environment.</p>

<p>A safer solution is often letting CSS handle purely visual responsive differences:</p>

<pre><code class="language-css">.desktop-nav {
    display: block;
}

.mobile-nav {
    display: none;
}

@media (max-width: 768px) {
    .desktop-nav {
        display: none;
    }

    .mobile-nav {
        display: block;
    }
}
</code></pre>

<p>The server can produce stable markup while the browser’s CSS handles presentation.</p>

<p>Hydration encourages developers to distinguish between:</p>

<pre><code class="language-text">Application state

and

Presentation state
</code></pre>

<p>Not every browser difference needs to become JavaScript logic.</p>

<hr />

<h2 id="when-hydration-is-worth-the-cost">When Hydration Is Worth the Cost</h2>

<p>After discussing all these problems, hydration can sound like something we should avoid completely. That’s not the lesson.</p>

<p>Hydration provides an extremely useful combination:</p>

<pre><code class="language-text">Fast server-rendered content

        +

Rich client-side interaction
</code></pre>

<p>For many applications, that’s exactly what we want. Imagine an e-commerce product page.</p>

<p>Users benefit from seeing:</p>

<pre><code class="language-text">Product Name
Image
Price
Description
Reviews
</code></pre>

<p>as early as possible.</p>

<p>But they also need:</p>

<pre><code class="language-text">Add to Cart
Choose Variant
Save Product
Update Quantity
Interactive Gallery
</code></pre>

<p>Server rendering plus hydration can provide both.</p>

<p>The question isn’t:</p>

<blockquote>
  <p>Is hydration bad?</p>
</blockquote>

<p>The better question is:</p>

<blockquote>
  <p><strong>How much hydration does this page actually need?</strong></p>
</blockquote>

<hr />

<h2 id="when-you-may-not-need-hydration">When You May Not Need Hydration</h2>

<p>Suppose you’re building a documentation page.</p>

<p>It contains:</p>

<pre><code class="language-text">Heading
Paragraphs
Code examples
Images
Links
</code></pre>

<p>Perhaps the only interaction is copying code. Do you really need a full client-side framework runtime for the entire page? Possibly not.</p>

<p>You might send static HTML and use a tiny amount of JavaScript for:</p>

<pre><code class="language-text">Copy Button
Search
Theme Toggle
</code></pre>

<p>Likewise, a marketing page may need only:</p>

<pre><code class="language-text">Mobile menu
Newsletter form
Analytics
</code></pre>

<p>The rest can remain HTML and CSS.</p>

<p>A powerful frontend optimization is sometimes simply:</p>

<blockquote>
  <p><strong>Don’t make static content into a JavaScript application unless it needs to be one.</strong></p>
</blockquote>

<hr />

<h2 id="hydration-strategies-compared">Hydration Strategies Compared</h2>

<p>We can summarize the main ideas.</p>

<h4 id="full-hydration">Full Hydration</h4>

<pre><code class="language-text">Entire Page
    │
    ▼
Hydrate
</code></pre>

<p>Simple mental model, but potentially more client-side work.</p>

<h4 id="partial-hydration-1">Partial Hydration</h4>

<pre><code class="language-text">Page
├── Static
├── Interactive ◄── Hydrate
├── Static
└── Interactive ◄── Hydrate
</code></pre>

<p>Only interactive regions hydrate.</p>

<h4 id="lazy-hydration-1">Lazy Hydration</h4>

<pre><code class="language-text">Interactive Component
        │
        ▼
Wait until needed
        │
        ▼
Hydrate
</code></pre>

<p>Hydration is delayed.</p>

<h4 id="selective-hydration-1">Selective Hydration</h4>

<pre><code class="language-text">Several regions waiting
        │
        ▼
User interacts
        │
        ▼
Prioritize relevant region
</code></pre>

<p>Urgent parts can receive attention first.</p>

<h4 id="server-only-components">Server-Only Components</h4>

<pre><code class="language-text">Component
    │
    ▼
Server
    │
    ▼
Rendered output

No client component
runtime required
</code></pre>

<p>Instead of optimizing hydration, avoid needing it for that component. These strategies aren’t necessarily mutually exclusive. Modern frameworks can combine several of them.</p>

<hr />

<h2 id="the-bigger-trend-ship-less-javascript">The Bigger Trend: Ship Less JavaScript</h2>

<p>For years, frontend development often moved in one direction:</p>

<pre><code class="language-text">More application logic
        │
        ▼
More JavaScript
        │
        ▼
More client rendering
</code></pre>

<p>The industry is increasingly reconsidering that default.</p>

<p>Modern architectures ask:</p>

<pre><code class="language-text">Does this code need to run
in the browser?

        │
   ┌────┴────┐
   │         │
  Yes        No
   │         │
   ▼         ▼
Client      Server
</code></pre>

<p>That doesn’t mean JavaScript is going away. Far from it. Rich interfaces still depend heavily on it. But we can become more intentional about <strong>which JavaScript users actually need to download and execute</strong>.</p>

<p>Hydration is central to that conversation.</p>

<hr />

<h2 id="how-to-think-about-hydration-performance">How to Think About Hydration Performance</h2>

<p>When profiling a server-rendered application, don’t look only at how quickly HTML arrives. Think about the whole lifecycle.</p>

<pre><code class="language-text">Request
   │
   ▼
Server Rendering
   │
   ▼
HTML Arrives
   │
   ▼
Content Visible
   │
   ▼
JavaScript Downloads
   │
   ▼
JavaScript Executes
   │
   ▼
Hydration
   │
   ▼
Interaction Ready
</code></pre>

<p>Ask:</p>

<ul>
  <li>How much JavaScript are we shipping?</li>
  <li>How much of it is needed immediately?</li>
  <li>Which components actually require client-side behavior?</li>
  <li>Is hydration producing long tasks?</li>
  <li>Can below-the-fold functionality wait?</li>
  <li>Are server and client producing the same initial state?</li>
  <li>Can static sections remain server-only?</li>
  <li>Are we measuring interaction responsiveness, not just page visibility?</li>
</ul>

<p>Those questions are much more useful than simply asking whether SSR is enabled.</p>

<hr />

<h2 id="connecting-everything-weve-learned">Connecting Everything We’ve Learned</h2>

<p>We’re now four articles into <strong>Beyond the UI</strong>, and the pieces are beginning to connect.</p>

<p>First, we learned how browsers create pixels:</p>

<pre><code class="language-text">HTML
 │
 ▼
DOM
 │
 ▼
Render Tree
 │
 ▼
Layout
 │
 ▼
Paint
 │
 ▼
Composite
</code></pre>

<p>Then we learned how DOM and style changes can trigger expensive rendering work:</p>

<pre><code class="language-text">Reflow
Repaint
Compositing
</code></pre>

<p>Then we explored how JavaScript competes for time on the main thread:</p>

<pre><code class="language-text">Tasks
Microtasks
Event Loop
Rendering
</code></pre>

<p>Then we moved rendering to the server:</p>

<pre><code class="language-text">CSR
SSR
SSG
Hybrid Rendering
</code></pre>

<p>And now hydration connects those worlds:</p>

<pre><code class="language-text">SERVER

Components
    │
    ▼
HTML

    │
    ▼

BROWSER

HTML becomes visible
    │
    ▼
JavaScript arrives
    │
    ▼
Hydration
    │
    ▼
Interactive application
</code></pre>

<p>Frontend performance isn’t one thing. It’s the result of all these systems interacting.</p>

<hr />

<h2 id="bringing-it-all-together">Bringing It All Together</h2>

<p>Hydration exists because server-rendered HTML and client-side applications solve different parts of the user experience.</p>

<p>Server rendering can give us:</p>

<pre><code class="language-text">Content quickly
SEO-friendly HTML
Useful initial document
</code></pre>

<p>Client JavaScript gives us:</p>

<pre><code class="language-text">State
Events
Interactions
Dynamic updates
Rich application behavior
</code></pre>

<p>Hydration connects them.</p>

<pre><code class="language-text">Server-Rendered HTML
          │
          │
          ├──── Client JavaScript
          │
          ▼
       Hydration
          │
          ▼
Interactive Application
</code></pre>

<p>But that connection has a cost. JavaScript must be transferred, parsed, and executed. The framework must connect itself to the server-rendered DOM, and the server and client must agree on what that initial DOM should represent.</p>

<p>That’s why newer frontend architectures increasingly ask whether every part of a page needs hydration at all.</p>

<p>Sometimes the best hydration optimization is:</p>

<pre><code class="language-text">Hydrate later.
</code></pre>

<p>Sometimes it’s:</p>

<pre><code class="language-text">Hydrate only this component.
</code></pre>

<p>And sometimes it’s:</p>

<pre><code class="language-text">Don't hydrate this component.
</code></pre>

<hr />

<h2 id="final-thoughts">Final Thoughts</h2>

<p>Hydration is easy to miss because, when everything works properly, the user never sees it. A page arrives, content appears, buttons work, and the application feels alive. But between those moments, the browser may be doing substantial work.</p>

<p>Understanding hydration helps explain why a server-rendered website can still ship too much JavaScript, why a visible page can still feel unresponsive, why server/client differences produce strange warnings, and why modern frameworks are becoming increasingly interested in server-only components, islands, streaming, and selective hydration.</p>

<p>Most importantly, hydration teaches us another lesson that keeps appearing throughout this series:</p>

<blockquote>
  <p><strong>Frontend performance isn’t about making one stage fast. It’s about reducing unnecessary work across the entire journey from server to interaction.</strong></p>
</blockquote>

<p>The server can generate HTML in 50 milliseconds. The browser can paint it immediately. But if the user then has to wait while megabytes of JavaScript are downloaded, parsed, executed, and hydrated, we’ve optimized only part of the experience.</p>

<p>The real goal is not simply:</p>

<blockquote>
  <p><strong>How quickly can we render the page?</strong></p>
</blockquote>

<p>It’s:</p>

<blockquote>
  <p><strong>How quickly can we give the user a page that is both useful and ready to respond?</strong></p>
</blockquote>

<hr />

<h2 id="whats-next">What’s Next?</h2>

<p>We’ve now seen how a server-rendered application becomes interactive. But once the application is alive, another problem quickly appears. Where should all of its data live?</p>

<p>A simple component might have a boolean:</p>

<pre><code class="language-javascript">const [open, setOpen] = useState(false);
</code></pre>

<p>Then another component needs the same information, another page needs user data, the URL represents filters, API responses need caching, and forms have their own state.</p>

<p>Before long, everything seems to be called “state” even though these values have completely different lifecycles and responsibilities.</p>

<p>So next in <strong>Beyond the UI</strong>:</p>

<blockquote>
  <p><strong>State Management Explained: Why Frontend State Gets Complicated</strong></p>
</blockquote>

<p>We’ll explore local state, shared state, server state, URL state, form state, and derived state, and why the solution to frontend state management isn’t simply putting everything into one global store.</p>
]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="Frontend" />
    
    <category term="Performance" />
    
  

  
    
    <category term="Frontend" />
    
    <category term="Performance" />
    
  

    <summary>Hydration is the process through which client-side JavaScript attaches application behavior to HTML that was already rendered on the server. This article explains what hydration is, how it works, and why it is important.</summary>

  </entry>

  
  





  



  


  <entry>
    <title>Client-Side Rendering vs Server-Side Rendering Explained: Where Should Your UI Be Built?</title>
    <link href="https://billyokeyo.dev/posts/csr-vs-ssr/" rel="alternate" type="text/html" title="Client-Side Rendering vs Server-Side Rendering Explained: Where Should Your UI Be Built?" />
    <published>2026-08-28T00:00:00+00:00</published>
  
    <updated>2026-08-28T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/csr-vs-ssr/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/csr-vs-ssr/"><![CDATA[<blockquote>
  <p><em>“Every web application eventually becomes HTML in the browser. The interesting question is where that HTML should be created.”</em></p>
</blockquote>

<p>Open two modern websites in your browser. They may look almost identical: both have navigation bars, product cards, forms, dashboards, buttons, and interactive components, and both may even be built using React. But underneath, the journey those interfaces took before appearing on your screen could be completely different.</p>

<p>One application might send the browser a relatively small HTML document:</p>

<pre><code class="language-html">&lt;div id="root"&gt;&lt;/div&gt;

&lt;script src="https://billyokeyo.dev/app.js"&gt;&lt;/script&gt;
</code></pre>

<p>JavaScript downloads, executes, fetches data, builds the interface, and inserts it into the page.</p>

<p>Another application might send this immediately:</p>

<pre><code class="language-html">&lt;main&gt;
    &lt;h1&gt;Products&lt;/h1&gt;

    &lt;article&gt;
        &lt;h2&gt;MacBook Pro&lt;/h2&gt;
        &lt;p&gt;KES 250,000&lt;/p&gt;
    &lt;/article&gt;
&lt;/main&gt;
</code></pre>

<p>The browser already has meaningful content before the application’s JavaScript finishes loading.</p>

<p>The first approach is broadly known as <strong>Client-Side Rendering (CSR)</strong>, and the second is <strong>Server-Side Rendering (SSR)</strong>.</p>

<p>At first, the difference sounds simple:</p>

<pre><code class="language-text">CSR

Server
  │
  ▼
JavaScript
  │
  ▼
Browser builds UI
</code></pre>

<p>versus:</p>

<pre><code class="language-text">SSR

Server builds UI
  │
  ▼
HTML
  │
  ▼
Browser displays UI
</code></pre>

<p>But that small architectural decision affects much more than where some HTML is generated.</p>

<p>It influences:</p>

<ul>
  <li>Initial page load</li>
  <li>JavaScript requirements</li>
  <li>SEO</li>
  <li>Caching</li>
  <li>Server infrastructure</li>
  <li>Time to interactive</li>
  <li>Data fetching</li>
  <li>Navigation</li>
  <li>Personalization</li>
  <li>Failure modes</li>
  <li>Application complexity</li>
</ul>

<p>And modern frameworks have made the distinction even more interesting. Next.js can render some things on the server and others in the browser, Nuxt does something similar for Vue, and Astro can ship almost no JavaScript for parts of a page while hydrating interactive islands. Modern applications increasingly aren’t purely client-rendered or purely server-rendered.</p>

<p>To understand why, we first need to understand what actually happens in each model.</p>

<hr />

<h2 id="what-is-client-side-rendering">What Is Client-Side Rendering?</h2>

<p>In Client-Side Rendering, the browser receives enough HTML to bootstrap the application, but JavaScript performs much of the work required to construct the actual interface.</p>

<p>A simplified React application might start with:</p>

<pre><code class="language-html">&lt;!DOCTYPE html&gt;
&lt;html&gt;
&lt;head&gt;
    &lt;title&gt;Store&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;

    &lt;div id="root"&gt;&lt;/div&gt;

    &lt;script src="https://billyokeyo.dev/app.js"&gt;&lt;/script&gt;

&lt;/body&gt;
&lt;/html&gt;
</code></pre>

<p>Notice what’s missing: there are no products, there is no navigation, and there may not even be a visible heading. Instead, the browser downloads <code>app.js</code>, and React then mounts the application.</p>

<pre><code class="language-javascript">const root = ReactDOM.createRoot(
    document.getElementById("root")
);

root.render(&lt;App /&gt;);
</code></pre>

<p>The application may then fetch data.</p>

<pre><code class="language-javascript">fetch("/api/products")
    .then(response =&gt; response.json())
    .then(products =&gt; {
        // Update application state
    });
</code></pre>

<p>Eventually, React creates the DOM necessary to display the page.</p>

<p>Conceptually:</p>

<pre><code class="language-text">Request Page
     │
     ▼
Server
     │
     ▼
Minimal HTML
     │
     ▼
Browser
     │
     ▼
Download JavaScript
     │
     ▼
Parse JavaScript
     │
     ▼
Execute Application
     │
     ▼
Fetch Data
     │
     ▼
Build DOM
     │
     ▼
Render UI
</code></pre>

<p>The browser does a significant amount of work before the user sees the completed application. That’s Client-Side Rendering.</p>

<hr />

<h2 id="why-client-side-rendering-became-popular">Why Client-Side Rendering Became Popular</h2>

<p>Traditional websites worked differently. Clicking a link usually caused the browser to request another document from the server.</p>

<pre><code class="language-text">Page A
  │
  │ Click link
  ▼
Server Request
  │
  ▼
New HTML Document
  │
  ▼
Page B
</code></pre>

<p>The browser navigated away from the current page and loaded another.</p>

<p>This model worked extremely well, and it still does.</p>

<p>But as web applications became increasingly interactive, developers wanted experiences that behaved more like desktop applications. Instead of requesting an entirely new page whenever something changed, JavaScript could update only the necessary parts of the interface.</p>

<p>This led to the rise of <strong>Single-Page Applications</strong>, or SPAs. Frameworks such as Angular, React, and Vue made these applications much easier to build, and navigation could happen without a full page reload.</p>

<pre><code class="language-text">Initial Page
     │
     ▼
JavaScript Application
     │
     ├────► /products
     │
     ├────► /orders
     │
     └────► /profile
</code></pre>

<p>The application remained loaded while the UI changed around it.</p>

<p>For dashboards, admin portals, project management tools, email clients, and other highly interactive applications, this was extremely attractive.</p>

<hr />

<h2 id="the-client-side-rendering-experience">The Client-Side Rendering Experience</h2>

<p>Imagine visiting an online store implemented entirely using CSR.</p>

<p>The browser requests:</p>

<pre><code class="language-http">GET /products
</code></pre>

<p>The server might respond with:</p>

<pre><code class="language-html">&lt;!DOCTYPE html&gt;
&lt;html&gt;
&lt;body&gt;

    &lt;div id="root"&gt;&lt;/div&gt;

    &lt;script src="https://billyokeyo.dev/bundle.js"&gt;&lt;/script&gt;

&lt;/body&gt;
&lt;/html&gt;
</code></pre>

<p>The browser can parse this almost immediately, but there still isn’t much useful content.</p>

<p>Next:</p>

<pre><code class="language-text">Download bundle.js
</code></pre>

<p>Perhaps that bundle is:</p>

<pre><code class="language-text">300 KB
</code></pre>

<p>or:</p>

<pre><code class="language-text">1 MB
</code></pre>

<p>or considerably larger.</p>

<p>Downloading isn’t the end of the work.</p>

<p>JavaScript must also be:</p>

<pre><code class="language-text">Downloaded
    │
    ▼
Parsed
    │
    ▼
Compiled
    │
    ▼
Executed
</code></pre>

<p>Then the application starts and may immediately request:</p>

<pre><code class="language-http">GET /api/products
</code></pre>

<p>Only after that response arrives can the application render the product list.</p>

<pre><code class="language-text">HTML
 │
 ▼
JavaScript
 │
 ▼
API Request
 │
 ▼
Data
 │
 ▼
UI
</code></pre>

<p>This creates what is sometimes called a <strong>request waterfall</strong>: the user requested the page long ago, but useful content depended on several sequential steps.</p>

<hr />

<h2 id="the-empty-page-problem">The Empty Page Problem</h2>

<p>This is one of the classic weaknesses of pure CSR.</p>

<p>Suppose your initial HTML contains:</p>

<pre><code class="language-html">&lt;div id="root"&gt;
    &lt;div class="spinner"&gt;&lt;/div&gt;
&lt;/div&gt;
</code></pre>

<p>The browser can render something, but the actual content isn’t available yet.</p>

<p>On a fast laptop with fiber internet, this might happen so quickly that nobody notices.</p>

<p>Now imagine:</p>

<pre><code class="language-text">Budget Android phone
        +
Slow mobile network
        +
Large JavaScript bundle
        +
Slow API response
</code></pre>

<p>The experience changes considerably.</p>

<pre><code class="language-text">User opens page
      │
      ▼
Blank / Loading UI
      │
      │
      │
      ▼
JavaScript loads
      │
      ▼
Application starts
      │
      ▼
Data loads
      │
      ▼
Content appears
</code></pre>

<p>This doesn’t mean CSR is inherently slow. A well-built client-rendered application can be extremely fast, but it does mean the browser may have more work to perform before meaningful content appears.</p>

<hr />

<h2 id="what-is-server-side-rendering">What Is Server-Side Rendering?</h2>

<p>Server-Side Rendering moves some of that work away from the browser. Instead of sending an almost empty application shell, the server generates HTML for the requested page.</p>

<p>Suppose the user requests:</p>

<pre><code class="language-http">GET /products
</code></pre>

<p>The server loads the necessary data.</p>

<pre><code class="language-text">Server
  │
  ▼
Database / API
  │
  ▼
Products
</code></pre>

<p>It then renders the page. The browser receives:</p>

<pre><code class="language-html">&lt;main&gt;
    &lt;h1&gt;Products&lt;/h1&gt;

    &lt;article&gt;
        &lt;h2&gt;Laptop&lt;/h2&gt;
        &lt;p&gt;KES 75,000&lt;/p&gt;
    &lt;/article&gt;

    &lt;article&gt;
        &lt;h2&gt;Monitor&lt;/h2&gt;
        &lt;p&gt;KES 35,000&lt;/p&gt;
    &lt;/article&gt;
&lt;/main&gt;
</code></pre>

<p>The journey becomes:</p>

<pre><code class="language-text">Request
   │
   ▼
Server
   │
   ├── Fetch data
   │
   └── Render HTML
   │
   ▼
HTML Response
   │
   ▼
Browser
   │
   ▼
Content
</code></pre>

<p>The browser receives meaningful HTML from the beginning. That’s Server-Side Rendering.</p>

<hr />

<h2 id="a-simple-server-side-example">A Simple Server-Side Example</h2>

<p>Imagine an Express application using a template engine.</p>

<pre><code class="language-javascript">app.get("/products", async (req, res) =&gt; {
    const products = await productService.getAll();

    res.render("products", {
        products
    });
});
</code></pre>

<p>The template might contain:</p>

<pre><code class="language-html">&lt;h1&gt;Products&lt;/h1&gt;

&lt;% products.forEach(product =&gt; { %&gt;

    &lt;article&gt;
        &lt;h2&gt;&lt;%= product.name %&gt;&lt;/h2&gt;
        &lt;p&gt;&lt;%= product.price %&gt;&lt;/p&gt;
    &lt;/article&gt;

&lt;% }) %&gt;
</code></pre>

<p>The browser doesn’t need JavaScript to create those product elements because the server already did it.</p>

<p>This model isn’t new. PHP, Ruby on Rails, Django, Laravel, ASP.NET MVC, JSP, and countless other technologies have rendered HTML on servers for decades. What changed is that modern frontend frameworks started bringing server rendering back into JavaScript-heavy application architectures.</p>

<hr />

<h2 id="csr-vs-ssr-the-fundamental-difference">CSR vs SSR: The Fundamental Difference</h2>

<p>At its simplest:</p>

<pre><code class="language-text">CLIENT-SIDE RENDERING

Server
  │
  ▼
Application Shell
  │
  ▼
Browser
  │
  ├── Load JavaScript
  ├── Execute Application
  ├── Fetch Data
  └── Build UI
</code></pre>

<p>While:</p>

<pre><code class="language-text">SERVER-SIDE RENDERING

Browser
  │
  ▼
Server
  │
  ├── Fetch Data
  └── Build HTML
  │
  ▼
Browser receives UI
</code></pre>

<p>The final browser DOM may look almost identical, but the difference is <strong>where the initial work happened</strong>.</p>

<hr />

<h2 id="but-server-rendered-html-isnt-necessarily-interactive">But Server-Rendered HTML Isn’t Necessarily Interactive</h2>

<p>Suppose the server sends:</p>

<pre><code class="language-html">&lt;button id="cart"&gt;
    Add to Cart
&lt;/button&gt;
</code></pre>

<p>The browser can display the button immediately, but what happens when the user clicks it?</p>

<p>If the page is supposed to behave like an interactive React application, the browser still needs JavaScript. This introduces another important concept: <strong>Hydration</strong>.</p>

<p>A server-rendered React application might conceptually work like this:</p>

<pre><code class="language-text">Server
  │
  ▼
Render React Components
  │
  ▼
HTML
  │
  ▼
Browser Displays Page
  │
  ▼
JavaScript Downloads
  │
  ▼
React Hydrates HTML
  │
  ▼
Page Becomes Fully Interactive
</code></pre>

<p>Before hydration:</p>

<pre><code class="language-text">Looks like application
</code></pre>

<p>After hydration:</p>

<pre><code class="language-text">Behaves like application
</code></pre>

<p>This distinction creates an interesting performance problem. A user may be able to <strong>see</strong> a button before the JavaScript necessary to handle that button has finished loading and executing. The page looks ready, but it isn’t necessarily ready.</p>

<p>We’ll explore hydration deeply in the next article. For now, remember:</p>

<blockquote>
  <p><strong>SSR can make content visible earlier, but interactive applications may still require significant client-side JavaScript.</strong></p>
</blockquote>

<hr />

<h2 id="initial-load-performance">Initial Load Performance</h2>

<p>This is where CSR and SSR are often compared most aggressively. Imagine a CSR application:</p>

<pre><code class="language-text">Request
  │
  ▼
HTML
  │
  ▼
JavaScript
  │
  ▼
Execute
  │
  ▼
Fetch Data
  │
  ▼
Render
</code></pre>

<p>Now SSR:</p>

<pre><code class="language-text">Request
  │
  ▼
Server Fetches Data
  │
  ▼
Server Renders
  │
  ▼
HTML
  │
  ▼
Browser Renders
</code></pre>

<p>SSR can often deliver meaningful content earlier because the browser doesn’t have to wait for the application to construct that content, but that doesn’t automatically mean SSR is faster in every situation. The server now has work to do before sending the response.</p>

<p>If server rendering requires slow database queries:</p>

<pre><code class="language-text">Request
  │
  ▼
Database
  │
  │ 1.5 seconds
  ▼
Render
  │
  ▼
Response
</code></pre>

<p>the browser may wait longer for the initial HTML.</p>

<p>Performance depends on the entire system.</p>

<hr />

<h2 id="time-to-first-byte-vs-useful-content">Time to First Byte vs Useful Content</h2>

<p>SSR can introduce an interesting trade-off. With CSR, the server can often return the initial shell quickly:</p>

<pre><code class="language-text">Request
  │
  ▼
HTML shell
</code></pre>

<p>That can produce a fast <strong>Time to First Byte</strong>, but meaningful content may arrive later.</p>

<p>SSR may take longer before sending the first HTML because the server needs to fetch data and render the page.</p>

<pre><code class="language-text">Request
  │
  ▼
Fetch Data
  │
  ▼
Render
  │
  ▼
HTML
</code></pre>

<p>But when the response arrives, it already contains useful content. So asking whether one approach returns HTML faster isn’t enough. A better question is:</p>

<blockquote>
  <p><strong>“When can the user actually see and use the content they came for?”</strong></p>
</blockquote>

<hr />

<h2 id="seo-and-crawlers">SEO and Crawlers</h2>

<p>SEO is one of the most frequently cited reasons for SSR.</p>

<p>Imagine a crawler receives:</p>

<pre><code class="language-html">&lt;div id="root"&gt;&lt;/div&gt;

&lt;script src="https://billyokeyo.dev/app.js"&gt;&lt;/script&gt;
</code></pre>

<p>The meaningful content depends on JavaScript execution. Modern search engines have become much better at processing JavaScript, but server-rendered HTML still provides a simpler and more predictable document for crawlers, link previews, social platforms, and other systems that consume webpage metadata.</p>

<p>Compare:</p>

<pre><code class="language-html">&lt;div id="root"&gt;&lt;/div&gt;
</code></pre>

<p>with:</p>

<pre><code class="language-html">&lt;article&gt;
    &lt;h1&gt;
        The Browser Rendering Pipeline Explained
    &lt;/h1&gt;

    &lt;p&gt;
        Learn how browsers turn HTML into pixels...
    &lt;/p&gt;
&lt;/article&gt;
</code></pre>

<p>The second document already describes the content without requiring application execution.</p>

<p>For:</p>

<ul>
  <li>Blogs</li>
  <li>Documentation</li>
  <li>News websites</li>
  <li>E-commerce product pages</li>
  <li>Marketing websites</li>
  <li>Public landing pages</li>
</ul>

<p>having content available in the initial HTML is often valuable.</p>

<p>For:</p>

<pre><code class="language-text">Internal accounting dashboard
</code></pre>

<p>SEO probably doesn’t matter at all. Architecture should follow requirements.</p>

<hr />

<h2 id="csr-can-be-excellent-for-application-like-interfaces">CSR Can Be Excellent for Application-Like Interfaces</h2>

<p>Imagine you’re building an internal analytics dashboard. Users authenticate once, then spend hours navigating between:</p>

<pre><code class="language-text">Overview
Reports
Customers
Invoices
Settings
</code></pre>

<p>SEO is irrelevant, the application is highly interactive, and users frequently move between screens.</p>

<p>A client-rendered SPA can work extremely well. After the initial JavaScript has loaded, navigation may require only data requests.</p>

<pre><code class="language-text">Application already loaded
        │
        ├── /api/reports
        ├── /api/customers
        └── /api/invoices
</code></pre>

<p>The shell remains in the browser, and only data and necessary UI updates change.</p>

<p>This can create a very responsive application experience. The point isn’t that CSR is outdated; it’s that <strong>different applications have different performance profiles</strong>.</p>

<hr />

<h2 id="ssr-has-a-server-cost">SSR Has a Server Cost</h2>

<p>With CSR, your backend might primarily serve static assets and APIs, and a CDN can distribute:</p>

<pre><code class="language-text">index.html
app.js
styles.css
</code></pre>

<p>very efficiently.</p>

<p>With dynamic SSR, each page request may require server computation.</p>

<pre><code class="language-text">Request 1 ─────► Render Page

Request 2 ─────► Render Page

Request 3 ─────► Render Page

Request 4 ─────► Render Page
</code></pre>

<p>At scale:</p>

<pre><code class="language-text">Thousands of requests
        │
        ▼
Server Rendering
        │
        ▼
CPU + Memory + Data Access
</code></pre>

<p>Now you need to think about:</p>

<ul>
  <li>Server capacity</li>
  <li>Rendering latency</li>
  <li>Caching</li>
  <li>Database load</li>
  <li>Failure handling</li>
  <li>Geographic distribution</li>
</ul>

<p>SSR moves work away from the client, but it doesn’t make the work disappear. It moves responsibility to another part of the system.</p>

<hr />

<h2 id="static-site-generation-enters-the-picture">Static Site Generation Enters the Picture</h2>

<p>What if the page doesn’t change on every request? Suppose you’re publishing a technical article. Rendering it on the server every single time someone visits may be unnecessary, so instead, the HTML can be generated during deployment. This is commonly known as <strong>Static Site Generation</strong>, or SSG.</p>

<pre><code class="language-text">BUILD TIME

Markdown
   │
   ▼
Framework
   │
   ▼
Generate HTML
   │
   ▼
Static File
</code></pre>

<p>Then at request time:</p>

<pre><code class="language-text">User
 │
 ▼
CDN
 │
 ▼
Pre-generated HTML
</code></pre>

<p>No application server needs to render the article for every visitor, which can be extremely fast and highly cacheable.</p>

<hr />

<h2 id="csr-vs-ssr-vs-ssg">CSR vs SSR vs SSG</h2>

<p>We now have three broad models.</p>

<h3 id="client-side-rendering">Client-Side Rendering</h3>

<pre><code class="language-text">Request Time

Server
  │
  ▼
Application Shell
  │
  ▼
Browser builds UI
</code></pre>

<h3 id="server-side-rendering">Server-Side Rendering</h3>

<pre><code class="language-text">Request Time

Request
  │
  ▼
Server builds UI
  │
  ▼
HTML
</code></pre>

<h3 id="static-site-generation">Static Site Generation</h3>

<pre><code class="language-text">Build Time

Framework
  │
  ▼
HTML generated ahead of time

Request Time

CDN
  │
  ▼
HTML
</code></pre>

<p>A simplified comparison:</p>

<table>
  <thead>
    <tr>
      <th>Characteristic</th>
      <th>CSR</th>
      <th>SSR</th>
      <th>SSG</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Initial HTML content</td>
      <td>Limited in pure CSR</td>
      <td>Rich</td>
      <td>Rich</td>
    </tr>
    <tr>
      <td>Rendering happens</td>
      <td>Browser</td>
      <td>Server</td>
      <td>Build time</td>
    </tr>
    <tr>
      <td>SEO friendliness</td>
      <td>Depends on implementation</td>
      <td>Strong</td>
      <td>Strong</td>
    </tr>
    <tr>
      <td>Server work per request</td>
      <td>Low</td>
      <td>Potentially higher</td>
      <td>Very low</td>
    </tr>
    <tr>
      <td>Dynamic personalization</td>
      <td>Strong</td>
      <td>Strong</td>
      <td>Limited without client/server additions</td>
    </tr>
    <tr>
      <td>CDN caching</td>
      <td>Excellent for shell/assets</td>
      <td>Possible but more complex</td>
      <td>Excellent</td>
    </tr>
    <tr>
      <td>Highly interactive apps</td>
      <td>Excellent</td>
      <td>Excellent after client JS</td>
      <td>Requires client JS for interaction</td>
    </tr>
    <tr>
      <td>Content-heavy sites</td>
      <td>Possible</td>
      <td>Strong</td>
      <td>Excellent when content changes infrequently</td>
    </tr>
  </tbody>
</table>

<p>But modern frameworks don’t force you to choose one strategy for your entire application, and that’s where things get more interesting.</p>

<hr />

<h2 id="modern-applications-are-hybrid">Modern Applications Are Hybrid</h2>

<p>Imagine an e-commerce application. Its homepage contains marketing content that changes once per day, its product pages change when inventory or prices change, its shopping cart is specific to each user, and its account dashboard requires authentication and real-time information.</p>

<p>Why should all four parts use exactly the same rendering strategy? They probably shouldn’t.</p>

<p>A modern architecture might look like:</p>

<pre><code class="language-text">Homepage
   │
   └── Static Generation

Product Page
   │
   └── Server Rendering / Cached Rendering

Shopping Cart
   │
   └── Client Interaction

Account Dashboard
   │
   └── Server + Client
</code></pre>

<p>Instead of asking:</p>

<blockquote>
  <p>CSR or SSR?</p>
</blockquote>

<p>modern frontend architecture increasingly asks:</p>

<blockquote>
  <p><strong>Which parts should run where?</strong></p>
</blockquote>

<hr />

<h2 id="nextjs-and-hybrid-rendering">Next.js and Hybrid Rendering</h2>

<p>This is one reason frameworks such as Next.js became popular: a single application can combine multiple rendering strategies.</p>

<p>Conceptually:</p>

<pre><code class="language-text">Next.js Application
        │
        ├── Static pages
        │
        ├── Server-rendered pages
        │
        ├── Server components
        │
        └── Client components
</code></pre>

<p>A mostly static marketing page doesn’t need the same architecture as an interactive dashboard. Modern frameworks allow developers to make those decisions at a much smaller granularity, and the boundary between “frontend” and “backend” becomes less rigid.</p>

<hr />

<h2 id="server-components-add-another-dimension">Server Components Add Another Dimension</h2>

<p>Traditional SSR generally works like:</p>

<pre><code class="language-text">Server
  │
  ▼
HTML
  │
  ▼
Browser
  │
  ▼
Hydrate JavaScript
</code></pre>

<p>Server Components introduce a different idea: some components execute only on the server and don’t need their component JavaScript shipped to the browser.</p>

<p>Conceptually:</p>

<pre><code class="language-text">Page
│
├── ProductDetails
│      Server
│
├── Reviews
│      Server
│
└── AddToCartButton
       Client
</code></pre>

<p>The interactive button needs browser JavaScript, but the static product description may not.</p>

<p>That means instead of sending JavaScript for everything:</p>

<pre><code class="language-text">Browser

ProductDetails JS
Reviews JS
Button JS
Navigation JS
Footer JS
</code></pre>

<p>you can potentially send client-side JavaScript only where interaction requires it.</p>

<pre><code class="language-text">Browser

Button JS
Navigation JS
</code></pre>

<p>This is another example of the industry moving away from the idea that an entire application must belong exclusively to either the client or the server.</p>

<hr />

<h2 id="the-javascript-cost-still-matters">The JavaScript Cost Still Matters</h2>

<p>In the previous article, we explored the JavaScript event loop and why long-running JavaScript can freeze the UI, and that knowledge matters here.</p>

<p>Suppose SSR delivers content almost instantly. Great. But then the browser downloads:</p>

<pre><code class="language-text">2.5 MB JavaScript
</code></pre>

<p>and spends significant time parsing and executing it.</p>

<p>The user may see the page quickly but still struggle to interact with it.</p>

<pre><code class="language-text">HTML arrives
     │
     ▼
Content visible
     │
     ▼
Large JS bundle
     │
     ▼
Parse + Execute
     │
     ▼
Hydration
     │
     ▼
Interactive
</code></pre>

<p>This is why SSR isn’t a magical performance switch. You need to think about both:</p>

<pre><code class="language-text">How quickly can users SEE the page?

and

How quickly can users USE the page?
</code></pre>

<p>Those are related but different questions.</p>

<hr />

<h2 id="data-fetching-changes-too">Data Fetching Changes Too</h2>

<p>CSR often produces a pattern like:</p>

<pre><code class="language-text">Browser
   │
   ▼
Load Application
   │
   ▼
Application Starts
   │
   ▼
Fetch /api/user
   │
   ▼
Fetch /api/orders
   │
   ▼
Render
</code></pre>

<p>With server rendering, data can often be fetched before HTML is sent.</p>

<pre><code class="language-text">Browser
   │
   ▼
Server
   │
   ├── Fetch User
   ├── Fetch Orders
   │
   ▼
Render HTML
   │
   ▼
Browser
</code></pre>

<p>This can eliminate some client-side waterfalls and can also allow the server to access internal services or databases without exposing those credentials or endpoints directly to the browser.</p>

<p>But now server rendering depends on those services, and if one is slow, the page may become slow. Again, architecture moves trade-offs around; it rarely eliminates them.</p>

<hr />

<h2 id="caching-changes-the-equation">Caching Changes the Equation</h2>

<p>Suppose 100,000 people request the same product page. If you dynamically server-render the page 100,000 times:</p>

<pre><code class="language-text">100,000 Requests
       │
       ▼
100,000 Renders
</code></pre>

<p>that could be wasteful.</p>

<p>If the response can safely be cached:</p>

<pre><code class="language-text">First Request
     │
     ▼
Render
     │
     ▼
Cache
     │
     ├────► User
     ├────► User
     ├────► User
     └────► User
</code></pre>

<p>the economics change dramatically.</p>

<p>Caching can make server-generated content behave much more like static content from an infrastructure perspective, which is why rendering strategy and caching strategy should often be designed together.</p>

<hr />

<h2 id="personalized-pages-are-different">Personalized Pages Are Different</h2>

<p>Now imagine:</p>

<pre><code class="language-text">/dashboard
</code></pre>

<p>Billy sees:</p>

<pre><code class="language-text">Welcome Billy

Account Balance: ...
Recent Orders: ...
</code></pre>

<p>Alice sees completely different data.</p>

<p>Caching the entire HTML response globally is dangerous because responses are user-specific.</p>

<p>You now need to consider:</p>

<pre><code class="language-text">Authentication
Personalization
Cache boundaries
Data privacy
Server rendering cost
</code></pre>

<p>This doesn’t mean SSR is wrong. It means personalized SSR has a different operational profile from rendering a public blog article.</p>

<hr />

<h2 id="failure-modes-are-different">Failure Modes Are Different</h2>

<p>Suppose a pure CSR application loads successfully but its API fails. The browser may still have the application shell.</p>

<pre><code class="language-text">Application
    │
    ▼
API fails
    │
    ▼
Show error state
</code></pre>

<p>With SSR, if the server cannot obtain critical data, it may be unable to generate the page.</p>

<pre><code class="language-text">Request
   │
   ▼
Server
   │
   ▼
Data dependency fails
   │
   ▼
Page rendering fails
</code></pre>

<p>You therefore need to think about:</p>

<ul>
  <li>Timeouts</li>
  <li>Partial rendering</li>
  <li>Error boundaries</li>
  <li>Fallback content</li>
  <li>Retries</li>
  <li>Caching stale data</li>
  <li>Graceful degradation</li>
</ul>

<p>Rendering architecture isn’t only a performance decision; it’s also a reliability decision.</p>

<hr />

<h2 id="what-about-navigation-after-the-first-page">What About Navigation After the First Page?</h2>

<p>Another common misconception is:</p>

<blockquote>
  <p>SSR means every click reloads the entire page.</p>
</blockquote>

<p>That doesn’t have to be true. Modern SSR frameworks frequently combine server-rendered initial requests with client-side navigation.</p>

<p>The first request might look like:</p>

<pre><code class="language-text">Browser
   │
   ▼
Server
   │
   ▼
Rendered Page
</code></pre>

<p>Then subsequent navigation can behave more like:</p>

<pre><code class="language-text">Current Application
      │
      ▼
Click /products/42
      │
      ▼
Fetch required data/content
      │
      ▼
Update interface
</code></pre>

<p>This hybrid behavior allows applications to combine fast initial content with smooth navigation, and again, the boundary is becoming less binary.</p>

<hr />

<h2 id="when-should-you-choose-csr">When Should You Choose CSR?</h2>

<p>CSR remains an excellent choice when the application is primarily an interactive tool rather than publicly indexed content.</p>

<p>Examples include:</p>

<pre><code class="language-text">Admin dashboards
Internal business tools
Analytics platforms
Complex editors
Authenticated SaaS applications
Project management tools
Email-like applications
</code></pre>

<p>CSR can be particularly attractive when users remain inside the application for long sessions, since the initial loading cost is paid once and navigation and interactions can then happen entirely within the application shell.</p>

<p>You should still care about bundle size, rendering performance, caching, and code splitting, but SSR isn’t automatically necessary simply because it exists.</p>

<hr />

<h2 id="when-should-you-choose-ssr">When Should You Choose SSR?</h2>

<p>SSR becomes particularly attractive when initial content matters immediately.</p>

<p>Examples include:</p>

<pre><code class="language-text">E-commerce product pages
News websites
Public profiles
Search result pages
Content platforms
Pages requiring request-time personalization
</code></pre>

<p>It can help when:</p>

<ul>
  <li>Content needs to be available in the initial HTML.</li>
  <li>SEO is important.</li>
  <li>Social previews matter.</li>
  <li>Initial rendering shouldn’t depend entirely on client JavaScript.</li>
  <li>Data must be fresh at request time.</li>
  <li>Server-side access to data simplifies the architecture.</li>
</ul>

<p>But SSR comes with server complexity and shouldn’t be adopted merely because a framework makes it easy.</p>

<hr />

<h2 id="when-should-you-choose-ssg">When Should You Choose SSG?</h2>

<p>Static generation is extremely powerful when content doesn’t need to be regenerated for every request.</p>

<p>Examples include:</p>

<pre><code class="language-text">Blogs
Documentation
Marketing pages
Portfolios
Product documentation
Company websites
</code></pre>

<p>The generated HTML can be distributed through a CDN.</p>

<pre><code class="language-text">                 ┌── London
                 │
Origin ─── CDN ──┼── Nairobi
                 │
                 ├── New York
                 │
                 └── Singapore
</code></pre>

<p>Users receive files from infrastructure close to them without requiring dynamic rendering for every request. For content that changes relatively infrequently, it’s difficult to beat the simplicity and performance characteristics of static HTML.</p>

<hr />

<h2 id="the-wrong-question-which-is-faster">The Wrong Question: “Which Is Faster?”</h2>

<p>Developers often ask:</p>

<blockquote>
  <p>Is CSR or SSR faster?</p>
</blockquote>

<p>That’s too broad. Consider two applications.</p>

<h4 id="application-a">Application A</h4>

<p>CSR dashboard:</p>

<pre><code class="language-text">Small bundle
Fast API
Good caching
Code splitting
Long authenticated sessions
</code></pre>

<h4 id="application-b">Application B</h4>

<p>SSR website:</p>

<pre><code class="language-text">Slow server
Slow database
No caching
Huge hydration bundle
</code></pre>

<p>Application A may easily provide the better experience. Now reverse the conditions: a massive client-rendered marketing website might perform poorly compared with a mostly static or server-rendered equivalent. Rendering strategy doesn’t determine performance by itself; implementation matters.</p>

<hr />

<h2 id="a-better-decision-framework">A Better Decision Framework</h2>

<p>Instead of asking:</p>

<blockquote>
  <p>CSR or SSR?</p>
</blockquote>

<p>Ask a series of smaller questions.</p>

<h4 id="does-the-content-need-seo">Does the content need SEO?</h4>

<p>If yes, delivering meaningful HTML directly is often useful.</p>

<h4 id="is-the-page-highly-personalized">Is the page highly personalized?</h4>

<p>Dynamic server rendering or client-side fetching may make sense depending on the data.</p>

<h4 id="does-the-content-change-frequently">Does the content change frequently?</h4>

<p>If not, static generation may be sufficient.</p>

<h4 id="is-the-application-highly-interactive">Is the application highly interactive?</h4>

<p>Client-side JavaScript will likely play a significant role regardless of how the initial HTML is produced.</p>

<h4 id="is-the-page-mostly-content">Is the page mostly content?</h4>

<p>Avoid shipping a large JavaScript application if simple HTML can solve the problem.</p>

<h4 id="can-the-output-be-cached">Can the output be cached?</h4>

<p>If yes, SSR or static generation can become significantly cheaper.</p>

<h4 id="does-the-user-stay-in-the-application-for-a-long-time">Does the user stay in the application for a long time?</h4>

<p>Paying an initial CSR cost may be perfectly reasonable for a long-lived application session.</p>

<p>Architecture should emerge from these answers.</p>

<hr />

<h2 id="common-mistake-ssr-everything">Common Mistake: SSR Everything</h2>

<p>Once developers discover SSR, it’s tempting to move everything to the server, but that’s not always an improvement.</p>

<p>Imagine an internal drag-and-drop project management application.</p>

<p>It has:</p>

<ul>
  <li>Real-time updates</li>
  <li>Rich client state</li>
  <li>Dragging</li>
  <li>Filtering</li>
  <li>Modals</li>
  <li>Optimistic updates</li>
  <li>Keyboard shortcuts</li>
</ul>

<p>Trying to make every interaction server-driven could introduce unnecessary network latency and complexity.</p>

<p>Some things belong naturally in the browser. The browser isn’t merely a dumb HTML viewer anymore; it’s an extremely capable application runtime. Use it where it makes sense.</p>

<hr />

<h2 id="common-mistake-csr-everything">Common Mistake: CSR Everything</h2>

<p>The opposite extreme created many of the problems that caused SSR to regain popularity. A simple marketing page doesn’t necessarily need:</p>

<pre><code class="language-text">React
+
Router
+
State Library
+
API Layer
+
500 KB JavaScript
</code></pre>

<p>just to display:</p>

<pre><code class="language-text">Company Name
Product Description
Pricing
Contact Form
</code></pre>

<p>Sometimes HTML is enough. One of the signs of frontend engineering maturity is understanding that <strong>more JavaScript isn’t automatically more modern</strong>.</p>

<hr />

<h2 id="common-mistake-choosing-based-on-framework-hype">Common Mistake: Choosing Based on Framework Hype</h2>

<p>A framework may strongly encourage a particular rendering model, but that doesn’t mean every application requires it.</p>

<p>Technology discussions often become:</p>

<pre><code class="language-text">"SSR is the future."

"SPAs are dead."

"Everything should be server components."

"Everything should be static."

</code></pre>

<p>Software architecture rarely works in absolutes, and every rendering strategy optimizes for different constraints.</p>

<p>A better engineering question is:</p>

<blockquote>
  <p><strong>What does this particular page need?</strong></p>
</blockquote>

<p>Not even:</p>

<blockquote>
  <p>What does this application need?</p>
</blockquote>

<p>Different pages inside the same application may deserve different answers.</p>

<hr />

<h2 id="a-practical-architecture">A Practical Architecture</h2>

<p>Imagine we’re building an online learning platform. It contains:</p>

<pre><code class="language-text">Homepage
Courses
Course Details
Student Dashboard
Interactive Code Editor
Documentation
</code></pre>

<p>We don’t need one rendering strategy.</p>

<p>We might choose:</p>

<pre><code class="language-text">Homepage
   │
   └── Static

Documentation
   │
   └── Static

Course Details
   │
   └── Server Rendered / Cached

Student Dashboard
   │
   └── Server + Client

Code Editor
   │
   └── Heavily Client-Side
</code></pre>

<p>Now the architecture follows the product instead of forcing the product into one architectural philosophy, and that’s increasingly what modern frontend engineering looks like.</p>

<hr />

<h2 id="csr-and-ssr-are-not-opponents">CSR and SSR Are Not Opponents</h2>

<p>It’s easy to discuss these approaches as if they’re competing technologies.</p>

<pre><code class="language-text">CSR

     VS.

SSR
</code></pre>

<p>But modern applications often look more like:</p>

<pre><code class="language-text">                    Application
                         │
          ┌──────────────┼──────────────┐
          │              │              │
          ▼              ▼              ▼
       Static          Server         Client
       Content        Rendering     Interaction
          │              │              │
          └──────────────┼──────────────┘
                         │
                         ▼
                    User Experience
</code></pre>

<p>The server can produce the initial document, the browser can take over interaction, and some components can remain server-only while others execute entirely on the client. Some pages can be generated days before anyone requests them, while others are generated for each request.</p>

<p>The question is no longer:</p>

<blockquote>
  <p><strong>Where does my frontend run?</strong></p>
</blockquote>

<p>Increasingly, the answer is:</p>

<blockquote>
  <p><strong>Wherever each piece makes the most sense.</strong></p>
</blockquote>

<hr />

<h2 id="bringing-it-all-together">Bringing It All Together</h2>

<p>Client-Side Rendering and Server-Side Rendering solve the same fundamental problem differently. Both ultimately need to produce something the browser can display.</p>

<p>CSR says:</p>

<pre><code class="language-text">Send the application to the browser
and let the browser construct the UI.
</code></pre>

<p>SSR says:</p>

<pre><code class="language-text">Construct the initial UI on the server
and send the browser meaningful HTML.
</code></pre>

<p>SSG goes one step further:</p>

<pre><code class="language-text">Construct the UI before the user
even requests it.
</code></pre>

<p>And modern hybrid frameworks say:</p>

<pre><code class="language-text">Why choose only one?
</code></pre>

<p>The trade-offs can be summarized like this:</p>

<pre><code class="language-text">                 WHERE IS THE UI CREATED?

Build Time             Server               Browser
    │                    │                     │
    ▼                    ▼                     ▼
   SSG                   SSR                   CSR

Fast static        Fresh request-time      Rich client-side
delivery           HTML                    applications
</code></pre>

<p>None is universally correct. The right choice depends on:</p>

<pre><code class="language-text">Content
Performance
Interactivity
SEO
Personalization
Caching
Infrastructure
User experience
</code></pre>

<p>Understanding those trade-offs is far more valuable than memorizing which rendering strategy is currently fashionable.</p>

<hr />

<h2 id="final-thoughts">Final Thoughts</h2>

<p>Frontend development spent years moving more work into the browser, then the industry rediscovered the advantages of moving some of that work back to the server. That can make it look as though we’ve gone in a circle, but we haven’t.</p>

<p>What changed is that we now have much finer control over <strong>where different parts of an application execute</strong>. We can generate a blog post at build time, render a personalized account page on the server, run an interactive editor in the browser, cache a product page at the edge, and combine all of those approaches inside the same product.</p>

<p>The most useful lesson isn’t that SSR is better than CSR, or that CSR is simpler than SSR. It’s this:</p>

<blockquote>
  <p><strong>Rendering is an architectural decision, not a framework preference.</strong></p>
</blockquote>

<p>Once you understand where the work happens, what it costs, and what the user needs, the choice becomes much easier. Server rendering also introduces one particularly interesting problem: the server can send a page that <strong>looks interactive before the browser has actually made it interactive</strong>. Understanding what happens during that transition brings us to our next topic.</p>

<hr />

<h2 id="whats-next">What’s Next?</h2>

<p>In the next article in <strong>Beyond the UI</strong>, we’ll explore:</p>

<blockquote>
  <p><strong>Hydration Explained: How Server-Rendered Pages Become Interactive</strong></p>
</blockquote>

<p>We’ll follow a server-rendered component from the server to the browser and see how frameworks attach JavaScript behavior to HTML that already exists. We’ll also explore hydration mismatches, why hydration can be expensive, partial and selective hydration, and why newer frontend architectures are trying to ship less JavaScript to the browser.</p>

<p>Because after the server has created your HTML, there’s still one important question:</p>

<blockquote>
  <p><strong>How does that static HTML become a living application?</strong></p>
</blockquote>
]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="Frontend" />
    
    <category term="Performance" />
    
  

  
    
    <category term="Frontend" />
    
    <category term="Performance" />
    
  

    <summary>Client-Side Rendering and Server-Side Rendering are the two most common ways to build user interfaces. This article explains what they are, how they work, and why they are important.</summary>

  </entry>

  
  





  



  


  <entry>
    <title>The JavaScript Event Loop Explained: Why Your UI Freezes</title>
    <link href="https://billyokeyo.dev/posts/javascript-event-loop/" rel="alternate" type="text/html" title="The JavaScript Event Loop Explained: Why Your UI Freezes" />
    <published>2026-08-24T00:00:00+00:00</published>
  
    <updated>2026-08-24T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/javascript-event-loop/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/javascript-event-loop/"><![CDATA[<blockquote>
  <p><em>“Your browser isn’t frozen because JavaScript stopped working. Sometimes it’s frozen because JavaScript won’t stop working long enough for the browser to do anything else.”</em></p>
</blockquote>

<p>In the previous articles in <strong>Beyond the UI</strong>, we followed the browser rendering pipeline from HTML to pixels and explored why reflow and repaint can make certain UI updates expensive. But there’s another reason an interface can feel slow even when rendering itself isn’t particularly complicated: JavaScript.</p>

<p>Consider this button:</p>

<pre><code class="language-html">&lt;button id="generate"&gt;
    Generate Report
&lt;/button&gt;
</code></pre>

<p>When clicked, it performs some expensive work.</p>

<pre><code class="language-javascript">document
    .querySelector("#generate")
    .addEventListener("click", () =&gt; {
        performExpensiveCalculation();
    });
</code></pre>

<p>The user clicks the button, and suddenly everything stops. The button doesn’t respond visually, animations freeze, scrolling becomes unresponsive, and other clicks don’t work. Even a loading spinner you tried to display may refuse to appear. Then, a few seconds later, everything suddenly comes back to life.</p>

<p>What happened? The browser didn’t crash, the network wasn’t necessarily slow, and the rendering pipeline wasn’t necessarily doing too much work. The problem was that JavaScript occupied the browser’s <strong>main thread</strong> for too long.</p>

<p>To understand why that freezes the interface, we need to understand one of the most important concepts in JavaScript:</p>

<blockquote>
  <p><strong>The Event Loop</strong></p>
</blockquote>

<p>At a high level, JavaScript execution in the browser involves several moving parts:</p>

<pre><code class="language-text">JavaScript Code
      │
      ▼
  Call Stack
      │
      ▼
Browser / Web APIs
      │
      ▼
 Task Queues
      │
      ▼
  Event Loop
      │
      └────────────► Call Stack
</code></pre>

<p>But that diagram hides some important details. There are tasks, microtasks, timers, promises, and rendering, and all of them need opportunities to run. Let’s unpack what actually happens.</p>

<hr />

<h2 id="javascript-is-single-threaded">JavaScript Is Single-Threaded</h2>

<p>One of the first things developers learn about JavaScript is that it is <strong>single-threaded</strong>. At least from the perspective of normal JavaScript execution on the browser’s main thread, only one piece of JavaScript executes at a time.</p>

<p>Consider:</p>

<pre><code class="language-javascript">console.log("One");
console.log("Two");
console.log("Three");
</code></pre>

<p>The result is predictable:</p>

<pre><code class="language-text">One
Two
Three
</code></pre>

<p>JavaScript doesn’t normally execute all three statements simultaneously. Instead, execution happens one operation at a time. You can think of it like a single cashier serving customers.</p>

<pre><code class="language-text">Customer A
    │
    ▼
┌──────────┐
│ Cashier  │
└──────────┘
    ▲
    │
Customer B
    │
Customer C
</code></pre>

<p>The cashier can serve only one customer at a time. If Customer A takes ten minutes, Customers B and C wait.</p>

<p>The same basic problem exists with JavaScript. If one function takes five seconds to complete, other JavaScript can’t run on that thread during those five seconds. More importantly, much of the browser’s UI work also depends on the main thread getting time to operate. That is where freezing begins.</p>

<hr />

<h2 id="the-call-stack">The Call Stack</h2>

<p>JavaScript keeps track of currently executing functions using something called the <strong>call stack</strong>.</p>

<p>Consider:</p>

<pre><code class="language-javascript">function greet() {
    console.log("Hello");
}

function start() {
    greet();
}

start();
</code></pre>

<p>Execution begins with <code>start()</code>. Conceptually:</p>

<pre><code class="language-text">Call Stack

┌──────────────┐
│   start()    │
└──────────────┘
</code></pre>

<p><code>start()</code> calls <code>greet()</code>. Now:</p>

<pre><code class="language-text">Call Stack

┌──────────────┐
│   greet()    │
├──────────────┤
│   start()    │
└──────────────┘
</code></pre>

<p><code>greet()</code> runs and finishes, then leaves the stack.</p>

<pre><code class="language-text">┌──────────────┐
│   start()    │
└──────────────┘
</code></pre>

<p>Then <code>start()</code> finishes, and the stack becomes empty.</p>

<pre><code class="language-text">Call Stack

     empty
</code></pre>

<p>This matters because queued asynchronous work cannot simply interrupt JavaScript that is already executing. The event loop generally waits for the current task to finish and the call stack to become available before scheduling more work.</p>

<hr />

<h2 id="so-how-does-asynchronous-javascript-work">So How Does Asynchronous JavaScript Work?</h2>

<p>This creates an obvious question: if JavaScript executes one thing at a time, how can this work?</p>

<pre><code class="language-javascript">setTimeout(() =&gt; {
    console.log("Finished");
}, 2000);
</code></pre>

<p>Surely JavaScript doesn’t sit on the call stack for two seconds doing nothing. It doesn’t. The browser provides capabilities outside the JavaScript engine that can handle operations such as timers, networking, and user events. We often refer to these capabilities collectively as <strong>Web APIs</strong> or browser APIs.</p>

<p>Conceptually:</p>

<pre><code class="language-text">JavaScript
    │
    │ setTimeout(...)
    ▼
Browser Timer
    │
    │ waits independently
    ▼
Callback becomes eligible
</code></pre>

<p>JavaScript registers the timer and continues executing. The browser tracks the timer. Once the timer expires, its callback becomes eligible to run later.</p>

<p>That distinction is important. The callback doesn’t necessarily run immediately when the timer expires. It has to wait until JavaScript is able to execute it.</p>

<hr />

<h2 id="why-settimeout-0-doesnt-mean-immediately">Why <code>setTimeout(..., 0)</code> Doesn’t Mean Immediately</h2>

<p>Consider:</p>

<pre><code class="language-javascript">console.log("A");

setTimeout(() =&gt; {
    console.log("B");
}, 0);

console.log("C");
</code></pre>

<p>Some developers initially expect:</p>

<pre><code class="language-text">A
B
C
</code></pre>

<p>But the result is:</p>

<pre><code class="language-text">A
C
B
</code></pre>

<p>Why? Because <code>setTimeout(..., 0)</code> doesn’t mean:</p>

<blockquote>
  <p>Run this function immediately.</p>
</blockquote>

<p>It means something closer to:</p>

<blockquote>
  <p>After at least the timer delay and once scheduling permits, make this callback available to run as a future task.</p>
</blockquote>

<p>So execution looks roughly like:</p>

<pre><code class="language-text">console.log("A")
        │
        ▼
Register timer
        │
        ▼
console.log("C")
        │
        ▼
Current task finishes
        │
        ▼
Timer callback can run
        │
        ▼
console.log("B")
</code></pre>

<p>The timer delay controls when the callback becomes eligible. It doesn’t guarantee exactly when it executes. If the main thread is busy, it may execute much later.</p>

<hr />

<h2 id="tasks-and-the-task-queue">Tasks and the Task Queue</h2>

<p>When asynchronous work becomes ready, the browser needs somewhere to keep track of it until JavaScript can execute it. One important category of queued work is commonly called <strong>tasks</strong>. You may also hear the older term <strong>macrotasks</strong>.</p>

<p>Examples include work associated with things such as:</p>

<ul>
  <li>Timer callbacks</li>
  <li>User interactions</li>
  <li>Message events</li>
  <li>Certain browser events</li>
</ul>

<p>Conceptually:</p>

<pre><code class="language-text">Task Queue

┌─────────────────────────┐
│ click callback          │
├─────────────────────────┤
│ setTimeout callback     │
├─────────────────────────┤
│ message callback        │
└─────────────────────────┘
</code></pre>

<p>The event loop coordinates when this queued work gets an opportunity to execute. A simplified model is:</p>

<pre><code class="language-text">Is JavaScript currently running?
          │
     ┌────┴────┐
     │         │
    Yes        No
     │         │
    Wait       ▼
          Take eligible task
               │
               ▼
          Execute JavaScript
</code></pre>

<p>But this is still incomplete, because JavaScript has another important queue.</p>

<hr />

<h2 id="enter-microtasks">Enter Microtasks</h2>

<p>Promises introduce another category of work called <strong>microtasks</strong>. Consider:</p>

<pre><code class="language-javascript">console.log("A");

Promise.resolve().then(() =&gt; {
    console.log("B");
});

console.log("C");
</code></pre>

<p>The result is:</p>

<pre><code class="language-text">A
C
B
</code></pre>

<p>That looks similar to <code>setTimeout</code>. But now watch what happens when we combine them.</p>

<pre><code class="language-javascript">console.log("A");

setTimeout(() =&gt; {
    console.log("B");
}, 0);

Promise.resolve().then(() =&gt; {
    console.log("C");
});

console.log("D");
</code></pre>

<p>The output is:</p>

<pre><code class="language-text">A
D
C
B
</code></pre>

<p>Why does the promise callback run before the timer? Because promise reactions are scheduled as <strong>microtasks</strong>, while the timer callback is scheduled as a later task. After the current JavaScript task finishes, the browser drains the microtask queue before moving on to the next task.</p>

<p>A simplified ordering looks like:</p>

<pre><code class="language-text">Current Task
     │
     ▼
JavaScript executes
     │
     ▼
Current stack finishes
     │
     ▼
Drain Microtasks
     │
     ▼
Rendering may get an opportunity
     │
     ▼
Next Task
</code></pre>

<p>So in our example:</p>

<pre><code class="language-text">A
│
├── Timer scheduled ──────────────► Task Queue
│
├── Promise callback ─────────────► Microtask Queue
│
D
│
▼
Current task ends
│
▼
Microtasks
│
└── C
│
▼
Later task
│
└── B
</code></pre>

<p>This distinction between tasks and microtasks explains a surprising amount of JavaScript behavior.</p>

<hr />

<h2 id="what-creates-microtasks">What Creates Microtasks?</h2>

<p>Common sources include:</p>

<pre><code class="language-javascript">Promise.resolve().then(...)
</code></pre>

<p>and code after an awaited promise:</p>

<pre><code class="language-javascript">async function load() {
    await fetchData();

    console.log("Finished");
}
</code></pre>

<p>The continuation after <code>await</code> eventually resumes through promise machinery and is scheduled as a microtask when the awaited promise settles.</p>

<p>Another browser API is:</p>

<pre><code class="language-javascript">queueMicrotask(() =&gt; {
    console.log("Microtask");
});
</code></pre>

<p>These are useful tools, but microtasks have an important characteristic that can become dangerous:</p>

<blockquote>
  <p><strong>The browser drains the microtask queue before moving on.</strong></p>
</blockquote>

<hr />

<h2 id="microtask-starvation">Microtask Starvation</h2>

<p>Consider:</p>

<pre><code class="language-javascript">function repeat() {
    queueMicrotask(repeat);
}

repeat();
</code></pre>

<p>Each microtask creates another microtask.</p>

<p>The browser finishes one:</p>

<pre><code class="language-text">Microtask 1
</code></pre>

<p>but another already exists:</p>

<pre><code class="language-text">Microtask 2
</code></pre>

<p>which creates:</p>

<pre><code class="language-text">Microtask 3
</code></pre>

<p>and so on.</p>

<p>Conceptually:</p>

<pre><code class="language-text">Task finishes
     │
     ▼
Microtask
     │
     ▼
Creates Microtask
     │
     ▼
Microtask
     │
     ▼
Creates Microtask
     │
     ▼
...
</code></pre>

<p>If this continues indefinitely, the browser may struggle to move on to other work. This is called <strong>starvation</strong>.</p>

<p>Promises are asynchronous, but that doesn’t automatically mean promise-heavy code can never block responsiveness. “Asynchronous” and “runs on another thread” are not the same thing. That’s an important distinction.</p>

<hr />

<h2 id="why-your-ui-freezes">Why Your UI Freezes</h2>

<p>Now we can finally return to our original problem. Suppose the user clicks a button and you run:</p>

<pre><code class="language-javascript">button.addEventListener("click", () =&gt; {
    let total = 0;

    for (let i = 0; i &lt; 5_000_000_000; i++) {
        total += i;
    }

    result.textContent = total;
});
</code></pre>

<p>Once that click handler begins executing, the main thread is occupied.</p>

<p>Conceptually:</p>

<pre><code class="language-text">Main Thread

Click Handler
     │
     ▼
Huge Loop
     │
     │
     │  3 seconds
     │
     │
     ▼
Finished
</code></pre>

<p>During that time, the browser may have other work waiting.</p>

<pre><code class="language-text">User scroll
      │
      ├─────────────┐
Button click        │
      │             │
Animation frame     │
      │             ▼
      └──────► WAITING

         Main Thread

      ┌───────────────┐
      │ Expensive JS  │
      │ Expensive JS  │
      │ Expensive JS  │
      │ Expensive JS  │
      └───────────────┘
</code></pre>

<p>The page appears frozen because JavaScript isn’t giving the browser enough opportunity to process interactions and produce frames. This is known as a <strong>long task</strong>.</p>

<hr />

<h2 id="the-loading-spinner-that-never-spins">The Loading Spinner That Never Spins</h2>

<p>Here’s a classic example. You want to show a loading state before performing expensive work.</p>

<pre><code class="language-javascript">button.addEventListener("click", () =&gt; {
    spinner.style.display = "block";

    performExpensiveCalculation();

    spinner.style.display = "none";
});
</code></pre>

<p>Logically, this seems correct: show the spinner, do the work, then hide the spinner. But the user may never see the spinner. Why?</p>

<p>Changing:</p>

<pre><code class="language-javascript">spinner.style.display = "block";
</code></pre>

<p>updates the DOM/style state, but the browser doesn’t necessarily paint the screen immediately after that line. Your JavaScript continues running.</p>

<pre><code class="language-text">Show spinner
     │
     ▼
Expensive JavaScript
     │
     ▼
Hide spinner
     │
     ▼
Task finishes
     │
     ▼
Browser finally gets chance to render
</code></pre>

<p>By the time rendering gets an opportunity, the spinner has already been hidden again. From the user’s perspective, it never appeared.</p>

<p>This connects directly to what we learned in the previous articles:</p>

<blockquote>
  <p>JavaScript execution and rendering must cooperate on the main thread.</p>
</blockquote>

<p>Understanding the rendering pipeline alone isn’t enough. We also need to understand <strong>when the browser gets an opportunity to run it</strong>.</p>

<hr />

<h2 id="rendering-and-the-event-loop">Rendering and the Event Loop</h2>

<p>The browser’s actual scheduling model is sophisticated, and different kinds of work are coordinated according to browser rules. But a useful mental model is:</p>

<pre><code class="language-text">┌─────────────────────────────┐
│ Execute a Task              │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│ Drain Microtasks            │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│ Rendering opportunity       │
│ if needed / appropriate     │
└──────────────┬──────────────┘
               │
               ▼
          Next iteration
</code></pre>

<p>The key idea is that the browser generally cannot just paint halfway through your long-running synchronous JavaScript function. Your code needs to yield control.</p>

<hr />

<h2 id="breaking-expensive-work-into-smaller-pieces">Breaking Expensive Work Into Smaller Pieces</h2>

<p>Suppose we need to process one million records. Instead of:</p>

<pre><code class="language-javascript">function processRecords(records) {
    for (const record of records) {
        expensiveOperation(record);
    }
}
</code></pre>

<p>we could process them in chunks.</p>

<pre><code class="language-javascript">function processInChunks(records) {
    let index = 0;

    function processChunk() {
        const end = Math.min(index + 1000, records.length);

        while (index &lt; end) {
            expensiveOperation(records[index]);
            index++;
        }

        if (index &lt; records.length) {
            setTimeout(processChunk, 0);
        }
    }

    processChunk();
}
</code></pre>

<p>Instead of one giant task:</p>

<pre><code class="language-text">┌──────────────────────────────────────────────┐
│              3000ms JavaScript              │
└──────────────────────────────────────────────┘
</code></pre>

<p>we create smaller pieces:</p>

<pre><code class="language-text">JS     Browser     JS     Browser     JS
│         │         │         │        │
▼         ▼         ▼         ▼        ▼

20ms     work      20ms      work     20ms
</code></pre>

<p>The total computation may not become dramatically smaller. But responsiveness can improve because the browser gets opportunities to process other work between chunks.</p>

<p>This demonstrates a critical performance principle:</p>

<blockquote>
  <p><strong>Sometimes making an application feel faster isn’t about doing less work. It’s about scheduling the work more intelligently.</strong></p>
</blockquote>

<hr />

<h2 id="what-about-async-and-await">What About <code>async</code> and <code>await</code>?</h2>

<p>A common misconception is that adding <code>async</code> automatically moves expensive work away from the main thread. It doesn’t.</p>

<p>Consider:</p>

<pre><code class="language-javascript">async function calculate() {
    let total = 0;

    for (let i = 0; i &lt; 5_000_000_000; i++) {
        total += i;
    }

    return total;
}
</code></pre>

<p>Calling:</p>

<pre><code class="language-javascript">await calculate();
</code></pre>

<p>doesn’t magically make that loop execute on another thread. The synchronous work inside <code>calculate()</code> still runs on the JavaScript thread. <code>async</code> changes how promises and continuations are handled. It doesn’t transform CPU-heavy JavaScript into background work.</p>

<p>This:</p>

<pre><code class="language-javascript">async function freezeUI() {
    while (true) {
        // expensive synchronous work
    }
}
</code></pre>

<p>will still freeze your interface. <code>async</code> is not a synonym for parallel.</p>

<hr />

<h2 id="settimeout-isnt-a-background-thread-either"><code>setTimeout</code> Isn’t a Background Thread Either</h2>

<p>The same misunderstanding often happens with:</p>

<pre><code class="language-javascript">setTimeout(() =&gt; {
    performExpensiveCalculation();
}, 0);
</code></pre>

<p>This doesn’t move the expensive calculation to another thread. It simply schedules the callback to execute as a future task. When that callback eventually runs, the expensive calculation still occupies the main JavaScript thread.</p>

<pre><code class="language-text">Current Task
     │
     ▼
setTimeout scheduled
     │
     ▼
Current Task finishes
     │
     ▼
Timer Task starts
     │
     ▼
EXPENSIVE WORK
     │
     ▼
UI freezes
</code></pre>

<p>You’ve delayed the problem. You haven’t removed it. Chunking can help because each task is smaller, but truly CPU-intensive work may need a different solution.</p>

<hr />

<h2 id="web-workers-actually-moving-work-off-the-main-thread">Web Workers: Actually Moving Work Off the Main Thread</h2>

<p>Browsers provide <strong>Web Workers</strong> for running JavaScript in a background thread separate from the main UI thread. Suppose you need to perform a large calculation. Instead of:</p>

<pre><code class="language-javascript">const result = expensiveCalculation(data);
</code></pre>

<p>you can create a worker.</p>

<pre><code class="language-javascript">const worker = new Worker("worker.js");

worker.postMessage(data);

worker.onmessage = event =&gt; {
    console.log("Result:", event.data);
};
</code></pre>

<p>Inside <code>worker.js</code>:</p>

<pre><code class="language-javascript">self.onmessage = event =&gt; {
    const result = expensiveCalculation(event.data);

    self.postMessage(result);
};
</code></pre>

<p>Now the architecture looks more like:</p>

<pre><code class="language-text">Main Thread                      Worker

UI
 │
 ├── User interactions
 │
 ├── Rendering
 │
 └── Send data ────────────────► Expensive calculation
                                      │
                                      │
                                      ▼
 Result received ◄──────────────── Result
 │
 ▼
Update UI
</code></pre>

<p>The expensive computation no longer needs to monopolize the main thread. The interface can remain responsive while the worker performs the calculation.</p>

<p>Workers aren’t appropriate for everything. There is communication overhead, data may need to be copied or transferred, and workers don’t directly manipulate the DOM. But for genuinely CPU-heavy operations, they can be extremely valuable.</p>

<hr />

<h2 id="requestanimationframe"><code>requestAnimationFrame</code></h2>

<p>Now suppose your JavaScript isn’t performing a large calculation. Instead, you’re animating something. You could write:</p>

<pre><code class="language-javascript">setInterval(() =&gt; {
    moveElement();
}, 16);
</code></pre>

<p>But the browser provides a better mechanism specifically for visual updates:</p>

<pre><code class="language-javascript">requestAnimationFrame(() =&gt; {
    moveElement();
});
</code></pre>

<p><code>requestAnimationFrame</code> tells the browser:</p>

<blockquote>
  <p>“I want to perform work before an upcoming repaint.”</p>
</blockquote>

<p>A typical animation looks like:</p>

<pre><code class="language-javascript">let position = 0;

function animate() {
    position += 2;

    element.style.transform =
        `translateX(${position}px)`;

    requestAnimationFrame(animate);
}

requestAnimationFrame(animate);
</code></pre>

<p>Conceptually:</p>

<pre><code class="language-text">Frame
 │
 ├── requestAnimationFrame callback
 │
 ├── Style / Layout
 │
 ├── Paint
 │
 └── Composite
 │
 ▼
Next Frame
</code></pre>

<p>This allows your visual updates to align more naturally with the browser’s rendering cycle. It doesn’t mean you can perform unlimited work inside the callback. If your callback takes 100 milliseconds, you’ll still miss frames. <code>requestAnimationFrame</code> gives you appropriate timing. It doesn’t give you unlimited processing power.</p>

<hr />

<h2 id="tasks-vs-microtasks-vs-animation-frames">Tasks vs Microtasks vs Animation Frames</h2>

<p>At this point, we have several scheduling mechanisms. A simplified comparison is useful.</p>

<table>
  <thead>
    <tr>
      <th>Mechanism</th>
      <th>Typical Use</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>setTimeout</code></td>
      <td>Schedule future task</td>
    </tr>
    <tr>
      <td>Promise <code>.then()</code></td>
      <td>Promise continuation / microtask</td>
    </tr>
    <tr>
      <td><code>queueMicrotask()</code></td>
      <td>Explicit microtask</td>
    </tr>
    <tr>
      <td><code>requestAnimationFrame()</code></td>
      <td>Work tied to an upcoming visual frame</td>
    </tr>
    <tr>
      <td>Web Worker</td>
      <td>CPU-heavy work away from main UI thread</td>
    </tr>
  </tbody>
</table>

<p>These mechanisms aren’t interchangeable. For example, using a chain of promises to split heavy work may not provide the rendering opportunities you expect because microtasks are drained before the browser moves on.</p>

<p>Consider:</p>

<pre><code class="language-javascript">function process() {
    Promise.resolve().then(process);
}

process();
</code></pre>

<p>This can continually populate the microtask queue. If your goal is to yield so the browser can render, continuously scheduling microtasks may be exactly the wrong strategy. Understanding <strong>which queue your work enters</strong> matters.</p>

<hr />

<h2 id="a-practical-example-processing-a-large-dataset">A Practical Example: Processing a Large Dataset</h2>

<p>Suppose a dashboard receives 100,000 records and needs to calculate statistics. The naive approach:</p>

<pre><code class="language-javascript">button.addEventListener("click", () =&gt; {
    const result = calculateStatistics(records);

    renderResults(result);
});
</code></pre>

<p>If the calculation takes two seconds:</p>

<pre><code class="language-text">Click
 │
 ▼
Calculate Statistics
 │
 │ 2 seconds
 │
 ▼
Render Results
</code></pre>

<p>the UI may become unresponsive. One option is chunking:</p>

<pre><code class="language-text">Chunk 1
   │
   ▼
Yield
   │
   ▼
Chunk 2
   │
   ▼
Yield
   │
   ▼
Chunk 3
</code></pre>

<p>Another option, particularly for CPU-heavy computation, is a worker:</p>

<pre><code class="language-text">                    ┌──────────────────┐
Records ───────────►│    Web Worker    │
                    │                  │
UI remains          │ Calculate stats  │
responsive          │                  │
                    └────────┬─────────┘
                             │
                             ▼
                           Result
</code></pre>

<p>The right approach depends on the workload. But both are better than assuming <code>async</code> will solve the problem automatically.</p>

<hr />

<h2 id="long-tasks-and-the-167ms-frame-budget">Long Tasks and the 16.7ms Frame Budget</h2>

<p>In the previous articles, we discussed the frame budget. On a 60 Hz display, the browser gets a new frame opportunity roughly every:</p>

<pre><code class="language-text">1000ms / 60 ≈ 16.7ms
</code></pre>

<p>Now imagine JavaScript runs for 200 milliseconds.</p>

<pre><code class="language-text">Frame budget

|----16.7ms----|

JavaScript

|----------------------------------------------------|
                       200ms
</code></pre>

<p>Several potential frame opportunities pass while JavaScript is still executing. Animations stop updating smoothly, interactions feel delayed, and the page becomes janky.</p>

<p>This is why long-running JavaScript matters even when the total amount of computation seems reasonable. Users experience responsiveness in small windows of time. A two-second calculation that completely blocks the interface feels much worse than work that can be performed without preventing interaction.</p>

<hr />

<h2 id="the-event-loop-explains-delayed-clicks-too">The Event Loop Explains Delayed Clicks Too</h2>

<p>Freezing isn’t always dramatic. Sometimes the interface simply feels slightly sluggish.</p>

<p>Suppose the main thread is busy for 300 milliseconds. During that period, the user clicks a button. The click doesn’t disappear. It can wait until the browser is able to process the relevant event and run its handler.</p>

<p>Conceptually:</p>

<pre><code class="language-text">User clicks
     │
     ▼
Event waiting
     │
     │
     │ Main thread busy
     │
     ▼
JavaScript finishes
     │
     ▼
Click handler runs
</code></pre>

<p>From the user’s perspective:</p>

<blockquote>
  <p>“I clicked the button and nothing happened.”</p>
</blockquote>

<p>Then, a fraction of a second later, the interface responds. This is one reason JavaScript performance directly affects interaction responsiveness. It’s also why modern web performance metrics care about how quickly pages respond to user interactions, not merely how quickly they initially load.</p>

<hr />

<h2 id="frameworks-still-depend-on-the-event-loop">Frameworks Still Depend on the Event Loop</h2>

<p>Just as React cannot bypass the browser rendering pipeline, frameworks cannot bypass JavaScript scheduling.</p>

<p>Consider:</p>

<pre><code class="language-jsx">function App() {
    const handleClick = () =&gt; {
        performHugeCalculation();
        setResult("Finished");
    };

    return (
        &lt;button onClick={handleClick}&gt;
            Calculate
        &lt;/button&gt;
    );
}
</code></pre>

<p>React can optimize how updates are reconciled. But if <code>performHugeCalculation()</code> occupies the main thread for three seconds, React cannot magically make the browser responsive during that synchronous work. The same principle applies to Vue, Angular, Svelte, Solid, and every other browser-based framework.</p>

<p>Eventually:</p>

<pre><code class="language-text">Framework Event Handler
          │
          ▼
      JavaScript
          │
          ▼
     Main Thread
          │
     ┌────┴─────┐
     │          │
Long work    Short work
     │          │
     ▼          ▼
UI blocked   Browser gets
             opportunities
             to continue
</code></pre>

<p>Understanding the event loop is therefore framework-independent knowledge.</p>

<hr />

<h2 id="common-event-loop-mistakes">Common Event Loop Mistakes</h2>

<p>Several bugs and performance problems become easier to recognize once you understand scheduling. One is assuming this executes immediately:</p>

<pre><code class="language-javascript">setTimeout(callback, 0);
</code></pre>

<p>It doesn’t. Another is assuming this moves CPU work off the main thread:</p>

<pre><code class="language-javascript">async function work() {
    expensiveCalculation();
}
</code></pre>

<p>It doesn’t. Another is creating enormous promise or microtask chains and assuming that because they’re asynchronous, rendering will happen between each one. That isn’t necessarily true.</p>

<p>And perhaps the most common mistake is simply doing too much synchronous work inside event handlers.</p>

<pre><code class="language-javascript">button.addEventListener("click", () =&gt; {
    parseHugeFile();
    calculateStatistics();
    transformRecords();
    generateReport();
    updateDashboard();
});
</code></pre>

<p>Each individual function may look reasonable. Together, they can monopolize the main thread.</p>

<hr />

<h2 id="how-to-keep-the-ui-responsive">How to Keep the UI Responsive</h2>

<p>The goal isn’t to avoid JavaScript. It’s to cooperate with the browser.</p>

<p>For large amounts of work, consider breaking processing into smaller chunks so the browser gets opportunities to handle other tasks. For CPU-heavy work that doesn’t need DOM access, consider Web Workers. For visual updates, use <code>requestAnimationFrame</code> where appropriate. Avoid unnecessarily long synchronous event handlers. Be careful about creating endless microtask chains.</p>

<p>And most importantly, measure. Browser developer tools can show long tasks, scripting time, rendering activity, and frame performance. A slow interface shouldn’t lead immediately to random optimization. First determine whether the bottleneck is:</p>

<pre><code class="language-text">JavaScript execution?
        │
        ├── Long task?
        ├── Too many calculations?
        └── Excessive framework work?

Rendering?
        │
        ├── Layout?
        ├── Paint?
        └── Compositing?

Network?
        │
        └── Waiting for resources?
</code></pre>

<p>Different problems require different solutions.</p>

<hr />

<h2 id="putting-the-event-loop-together">Putting the Event Loop Together</h2>

<p>We can now build a more complete mental model.</p>

<pre><code class="language-text">                 Browser
                    │
       ┌────────────┴─────────────┐
       │                          │
       ▼                          ▼
  Browser APIs               User Events
       │                          │
       └────────────┬─────────────┘
                    │
                    ▼
                Task Queue
                    │
                    ▼
              ┌───────────┐
              │ Event Loop│
              └─────┬─────┘
                    │
                    ▼
               Call Stack
                    │
                    ▼
             JavaScript Runs
                    │
                    ▼
              Task Finishes
                    │
                    ▼
            Drain Microtasks
                    │
                    ▼
         Rendering Opportunity
                    │
                    ▼
               Next Work
</code></pre>

<p>Again, the browser’s actual implementation is more sophisticated than this diagram. But as a mental model, it answers many practical questions.</p>

<p>Why doesn’t <code>setTimeout(..., 0)</code> run immediately? Because it has to wait for a future task opportunity.</p>

<p>Why does a promise callback run before that timer? Because microtasks are processed before moving on to the next task.</p>

<p>Why does a giant loop freeze the interface? Because JavaScript occupies the main thread.</p>

<p>Why didn’t your spinner appear before the expensive calculation? Because the browser didn’t get a rendering opportunity.</p>

<p>Why doesn’t <code>async</code> solve CPU-heavy work? Because asynchronous syntax doesn’t automatically mean another thread.</p>

<p>Why can Web Workers help? Because they allow computation to happen away from the main UI thread.</p>

<hr />

<h2 id="bringing-it-all-together">Bringing It All Together</h2>

<p>The JavaScript event loop isn’t merely an interview question. It’s the scheduling system behind much of the behavior users experience in web applications.</p>

<p>When JavaScript performs small amounts of work and regularly gives control back to the browser, the interface remains responsive.</p>

<pre><code class="language-text">JavaScript
    │
    ▼
Browser
    │
    ▼
JavaScript
    │
    ▼
Browser
    │
    ▼
JavaScript
</code></pre>

<p>But when one task monopolizes the main thread:</p>

<pre><code class="language-text">JavaScript
    │
    │
    │
    │
    │
    │
    ▼
Finally finishes
    │
    ▼
Browser catches up
</code></pre>

<p>everything else has to wait. That’s the heart of the problem.</p>

<p>A responsive frontend isn’t just about writing fast JavaScript. It’s about giving the browser enough opportunities to do everything <strong>other than JavaScript</strong>.</p>

<hr />

<h2 id="final-thoughts">Final Thoughts</h2>

<p>The event loop can seem complicated because several concepts are usually introduced at once: the call stack, Web APIs, tasks, microtasks, promises, timers, rendering, and animation frames. But underneath all of them is a relatively simple idea.</p>

<p>The browser has many responsibilities. It needs to run your JavaScript, respond to users, calculate layouts, paint pixels, animate interfaces, and process network results. And much of that work has to be coordinated around a main thread that can only do so much at once.</p>

<p>If your JavaScript refuses to give that thread back, the browser cannot provide a smooth experience. That’s why the next time your interface freezes, the most useful question may not be:</p>

<blockquote>
  <p><strong>“Why is this function slow?”</strong></p>
</blockquote>

<p>Instead, ask:</p>

<blockquote>
  <p><strong>“How long am I preventing the browser from doing anything else?”</strong></p>
</blockquote>

<p>That question gets much closer to how users actually experience performance.</p>

<hr />

<h2 id="whats-next">What’s Next?</h2>

<p>So far in <strong>Beyond the UI</strong>, we’ve looked underneath frontend frameworks at three fundamental browser concepts:</p>

<pre><code class="language-text">Browser Rendering Pipeline
          │
          ▼
Reflow and Repaint
          │
          ▼
JavaScript Event Loop
</code></pre>

<p>We now understand how the browser creates pixels, why some visual updates are expensive, and why JavaScript can prevent the UI from responding altogether.</p>

<p>Next, we’ll move one level higher and look at a decision that shapes how modern frontend applications are delivered:</p>

<blockquote>
  <p><strong>Client-Side Rendering vs Server-Side Rendering Explained: Where Should Your UI Be Built?</strong></p>
</blockquote>

<p>We’ll explore CSR, SSR, static generation, the trade-offs between them, what happens from the moment a user requests a page, and why frameworks such as Next.js, Nuxt, and modern meta-frameworks increasingly blur the line between client and server.</p>

<p>Because once you understand <strong>how the browser renders</strong>, the next question becomes:</p>

<blockquote>
  <p><strong>How much work should we make the browser do in the first place?</strong></p>
</blockquote>
]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="Frontend" />
    
    <category term="Performance" />
    
  

  
    
    <category term="Frontend" />
    
    <category term="Performance" />
    
  

    <summary>The JavaScript event loop is the process by which the browser converts HTML and CSS into pixels. This article explains what the JavaScript event loop is, how it works, and why it is important.</summary>

  </entry>

  
  





  



  


  <entry>
    <title>Reflow and Repaint Explained: Why Some UI Updates Are Expensive</title>
    <link href="https://billyokeyo.dev/posts/reflow-and-repaint/" rel="alternate" type="text/html" title="Reflow and Repaint Explained: Why Some UI Updates Are Expensive" />
    <published>2026-08-21T00:00:00+00:00</published>
  
    <updated>2026-08-21T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/reflow-and-repaint/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/reflow-and-repaint/"><![CDATA[<blockquote>
  <p><em>“Changing one CSS property can be almost free. Changing another can force the browser to recalculate half the page. Understanding why is the difference between guessing at frontend performance and reasoning about it.”</em></p>
</blockquote>

<p>In the previous article in <strong>Beyond the UI</strong>, we followed a webpage through the browser rendering pipeline. We started with HTML and CSS and eventually arrived at pixels:</p>

<pre><code class="language-text">HTML ──────► DOM
               │
CSS ───────► CSSOM
               │
               ▼
          Render Tree
               │
               ▼
            Layout
               │
               ▼
             Paint
               │
               ▼
          Compositing
               │
               ▼
             Pixels
</code></pre>

<p>That pipeline explains how a page appears for the first time. But modern websites don’t remain still after they’re rendered. A user opens a menu, a notification appears, a modal slides onto the screen, an accordion expands, JavaScript adds another row to a table, an animation moves a card across the page, and a validation message appears underneath a form field. Every one of these interactions changes something the browser has already rendered.</p>

<p>The interesting question is:</p>

<blockquote>
  <p><strong>How much work does the browser have to repeat when something changes?</strong></p>
</blockquote>

<p>The answer depends heavily on <strong>what changed</strong>. Changing an element’s width may affect the position of everything around it. Changing its background color doesn’t affect its geometry, but the browser still needs to redraw it. Changing its <code>transform</code> may, in favorable circumstances, avoid both layout and painting and require mostly compositing work.</p>

<p>Conceptually, these updates can look very different:</p>

<pre><code class="language-text">Width Change

Style
  │
  ▼
Layout
  │
  ▼
Paint
  │
  ▼
Composite
</code></pre>

<p>Compared with:</p>

<pre><code class="language-text">Background Change

Style
  │
  ▼
Paint
  │
  ▼
Composite
</code></pre>

<p>And sometimes:</p>

<pre><code class="language-text">Transform / Opacity

Style
  │
  ▼
Composite
</code></pre>

<p>These are simplified mental models rather than guarantees, but they reveal something fundamental about frontend performance:</p>

<blockquote>
  <p><strong>Not all UI updates cost the browser the same amount of work.</strong></p>
</blockquote>

<p>To understand why, we need to look more closely at two terms that appear constantly in frontend performance discussions: <strong>Reflow</strong> and <strong>Repaint</strong>.</p>

<hr />

<h2 id="what-is-reflow">What Is Reflow?</h2>

<p>Imagine a simple page containing three cards.</p>

<pre><code class="language-text">┌───────────────────────────┐
│ Card A                    │
│ height: 100px             │
└───────────────────────────┘

┌───────────────────────────┐
│ Card B                    │
│ height: 100px             │
└───────────────────────────┘

┌───────────────────────────┐
│ Card C                    │
│ height: 100px             │
└───────────────────────────┘
</code></pre>

<p>The browser has already calculated where every card belongs. Then JavaScript changes the height of Card A.</p>

<pre><code class="language-javascript">const card = document.querySelector(".card-a");

card.style.height = "300px";
</code></pre>

<p>Card A can no longer occupy the same amount of space. That means Card B must move, and Card C must move as well. The browser needs to recalculate the geometry of the affected part of the page.</p>

<pre><code class="language-text">Before

Card A     y = 0
Card B     y = 120
Card C     y = 240


After Card A grows

Card A     y = 0
Card B     y = 320
Card C     y = 440
</code></pre>

<p>That recalculation is commonly called <strong>reflow</strong>. In modern browser terminology, you’ll also frequently see it called <strong>layout</strong>. During layout, the browser may need to recalculate things such as:</p>

<ul>
  <li>Width</li>
  <li>Height</li>
  <li>Position</li>
  <li>Margins</li>
  <li>Padding</li>
  <li>Relationships between parents and children</li>
  <li>Text wrapping</li>
  <li>Available space</li>
</ul>

<p>The important part is that a layout change isn’t always isolated to the element you modified. One element can influence many others.</p>

<hr />

<h2 id="why-reflow-can-become-expensive">Why Reflow Can Become Expensive</h2>

<p>Suppose you change the width of a paragraph.</p>

<pre><code class="language-css">.article {
    width: 600px;
}
</code></pre>

<p>Then later:</p>

<pre><code class="language-javascript">article.style.width = "400px";
</code></pre>

<p>The browser doesn’t simply make the rectangle narrower. Text may wrap differently, which changes the paragraph’s height, and everything below the paragraph may move. If the paragraph is inside another container whose height depends on its children, that container may also change, and now its siblings may need new positions. A single modification can ripple through the page.</p>

<pre><code class="language-text">Change width
     │
     ▼
Text wraps differently
     │
     ▼
Element height changes
     │
     ▼
Parent geometry changes
     │
     ▼
Sibling positions change
     │
     ▼
Layout recalculated
</code></pre>

<p>On a tiny page, this may take almost no noticeable time. On a large dashboard containing thousands of elements, complex grids, tables, charts, and nested components, repeated layout work can become expensive. This is particularly dangerous when it happens many times during a single animation or interaction.</p>

<hr />

<h2 id="what-can-trigger-reflow">What Can Trigger Reflow?</h2>

<p>Many operations can invalidate layout because they change geometry or influence how elements are positioned. Common examples include modifying:</p>

<pre><code class="language-css">width
height
margin
padding
top
left
right
bottom
font-size
line-height
</code></pre>

<p>Adding or removing DOM elements can also require layout.</p>

<pre><code class="language-javascript">container.appendChild(newElement);
</code></pre>

<p>So can changing content.</p>

<pre><code class="language-javascript">title.textContent =
    "This is a much longer title than before";
</code></pre>

<p>The new text may wrap differently, changing the size of the element and potentially shifting everything around it. Even resizing the browser window can trigger significant layout work because responsive layouts may need to be recalculated. But writes aren’t the only thing developers need to think about. Sometimes <strong>reading</strong> information from the DOM can cause performance problems too.</p>

<hr />

<h2 id="the-surprising-cost-of-reading-layout">The Surprising Cost of Reading Layout</h2>

<p>Consider this code:</p>

<pre><code class="language-javascript">const width = element.offsetWidth;
</code></pre>

<p>It looks harmless. We’re only asking the browser for a number. But imagine the browser already knows that something changed.</p>

<pre><code class="language-javascript">element.style.width = "500px";

const width = element.offsetWidth;
</code></pre>

<p>The first line modifies layout. However, browsers often delay expensive rendering work until it is actually needed. Then the second line asks:</p>

<blockquote>
  <p>“What is the element’s width right now?”</p>
</blockquote>

<p>The browser cannot answer accurately using the old layout information. It may therefore need to calculate layout immediately before returning the value. Conceptually:</p>

<pre><code class="language-text">Change width
     │
     ▼
Layout becomes invalid
     │
     ▼
Read offsetWidth
     │
     ▼
Browser needs current geometry
     │
     ▼
Forced Layout
</code></pre>

<p>This becomes especially problematic when reads and writes are repeatedly mixed together. And that leads us to one of the most notorious frontend performance problems.</p>

<hr />

<h2 id="layout-thrashing-explained">Layout Thrashing Explained</h2>

<p>Imagine you have 500 elements. You want to increase each one’s width slightly. You write:</p>

<pre><code class="language-javascript">const items = document.querySelectorAll(".item");

items.forEach(item =&gt; {
    const width = item.offsetWidth;

    item.style.width = `${width + 10}px`;
});
</code></pre>

<p>At first glance, this looks reasonable. Read the current width, add ten pixels, and move to the next element. But look at the pattern:</p>

<pre><code class="language-text">READ
WRITE

READ
WRITE

READ
WRITE

READ
WRITE
</code></pre>

<p>After a write, layout may become invalid. The next read asks the browser for current geometry, so the browser may need to calculate layout. Then another write invalidates it again, and another read may force layout again. You can end up with something conceptually similar to:</p>

<pre><code class="language-text">Read
  │
Write
  │
Layout
  │
Read
  │
Write
  │
Layout
  │
Read
  │
Write
  │
Layout
  │
...
</code></pre>

<p>This repeated invalidation and recalculation is commonly known as <strong>layout thrashing</strong>. Instead, you generally want to group reads together and then group writes together.</p>

<pre><code class="language-javascript">const items = [...document.querySelectorAll(".item")];

const widths = items.map(item =&gt; item.offsetWidth);

items.forEach((item, index) =&gt; {
    item.style.width = `${widths[index] + 10}px`;
});
</code></pre>

<p>Now the pattern becomes:</p>

<pre><code class="language-text">READ
READ
READ
READ

     ↓

WRITE
WRITE
WRITE
WRITE
</code></pre>

<p>This gives the browser much more opportunity to batch its work. The lesson is broader than this particular example:</p>

<blockquote>
  <p><strong>Avoid repeatedly switching between reading layout information and modifying layout inside tight loops.</strong></p>
</blockquote>

<hr />

<h2 id="what-is-repaint">What Is Repaint?</h2>

<p>Now imagine a different situation. You don’t change the size or position of an element. You simply change its background.</p>

<pre><code class="language-javascript">card.style.backgroundColor = "blue";
</code></pre>

<p>The card remains in exactly the same place. Its width doesn’t change, its height doesn’t change, and its siblings don’t move. The browser therefore doesn’t necessarily need to recalculate layout. But the card looks different, so the pixels representing it must be updated. This is where <strong>repaint</strong> comes in. Conceptually:</p>

<pre><code class="language-text">Before

┌─────────────────┐
│                 │
│   Gray Card     │
│                 │
└─────────────────┘

       ↓

background-color changes

       ↓

┌─────────────────┐
│                 │
│   Blue Card     │
│                 │
└─────────────────┘
</code></pre>

<p>The geometry hasn’t changed. The appearance has. The browser needs to paint the affected visual content again.</p>

<hr />

<h2 id="reflow-vs-repaint">Reflow vs Repaint</h2>

<p>This distinction is worth making clear. A <strong>reflow</strong> deals primarily with geometry. A <strong>repaint</strong> deals primarily with appearance. Consider these two updates.</p>

<pre><code class="language-javascript">element.style.width = "500px";
</code></pre>

<p>and:</p>

<pre><code class="language-javascript">element.style.backgroundColor = "red";
</code></pre>

<p>The first can affect layout. The second generally doesn’t. A simplified comparison looks like this:</p>

<table>
  <thead>
    <tr>
      <th>Change</th>
      <th style="text-align: right">Layout</th>
      <th style="text-align: right">Paint</th>
      <th style="text-align: right">Composite</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>width</code></td>
      <td style="text-align: right">Usually</td>
      <td style="text-align: right">Usually</td>
      <td style="text-align: right">Usually</td>
    </tr>
    <tr>
      <td><code>height</code></td>
      <td style="text-align: right">Usually</td>
      <td style="text-align: right">Usually</td>
      <td style="text-align: right">Usually</td>
    </tr>
    <tr>
      <td><code>padding</code></td>
      <td style="text-align: right">Usually</td>
      <td style="text-align: right">Usually</td>
      <td style="text-align: right">Usually</td>
    </tr>
    <tr>
      <td><code>font-size</code></td>
      <td style="text-align: right">Usually</td>
      <td style="text-align: right">Usually</td>
      <td style="text-align: right">Usually</td>
    </tr>
    <tr>
      <td><code>background-color</code></td>
      <td style="text-align: right">No layout in typical cases</td>
      <td style="text-align: right">Usually</td>
      <td style="text-align: right">Usually</td>
    </tr>
    <tr>
      <td><code>box-shadow</code></td>
      <td style="text-align: right">No layout in typical cases</td>
      <td style="text-align: right">Usually</td>
      <td style="text-align: right">Usually</td>
    </tr>
    <tr>
      <td><code>transform</code></td>
      <td style="text-align: right">Often avoidable</td>
      <td style="text-align: right">Often avoidable</td>
      <td style="text-align: right">Often</td>
    </tr>
    <tr>
      <td><code>opacity</code></td>
      <td style="text-align: right">Often avoidable</td>
      <td style="text-align: right">Often avoidable</td>
      <td style="text-align: right">Often</td>
    </tr>
  </tbody>
</table>

<p>This table is intentionally simplified. Browser engines are highly optimized, and exactly what gets recalculated depends on the page, browser, element, layer structure, and other factors. The useful mental model is the hierarchy:</p>

<pre><code class="language-text">Layout
  │
  ▼
Paint
  │
  ▼
Composite
</code></pre>

<p>If you invalidate layout, later stages may also need work. If you only invalidate paint, layout may be avoided. If an update can be handled during compositing, both layout and painting may sometimes be avoided. This is why avoiding unnecessary layout work can be so valuable.</p>

<hr />

<h2 id="compositing-the-cheaper-path">Compositing: The Cheaper Path</h2>

<p>Suppose you want to animate a card from left to right. One approach is changing <code>left</code>.</p>

<pre><code class="language-css">.card {
    position: absolute;
    left: 0;
}
</code></pre>

<p>Then:</p>

<pre><code class="language-javascript">card.style.left = "300px";
</code></pre>

<p>Because <code>left</code> participates in positioning, changing it can require layout work. Now consider:</p>

<pre><code class="language-javascript">card.style.transform = "translateX(300px)";
</code></pre>

<p>A transform changes how the already-rendered element is presented. In many situations, browsers can handle transforms efficiently during compositing, particularly when the element is on its own composited layer. The difference can look conceptually like this:</p>

<pre><code class="language-text">Animating left

JavaScript
    │
    ▼
Layout
    │
    ▼
Paint
    │
    ▼
Composite
</code></pre>

<p>versus:</p>

<pre><code class="language-text">Animating transform

JavaScript
    │
    ▼
Composite
</code></pre>

<p>This is why <code>transform</code> and <code>opacity</code> are commonly recommended for animations. For example:</p>

<pre><code class="language-css">.modal {
    opacity: 0;
    transform: translateY(20px);

    transition:
        opacity 200ms ease,
        transform 200ms ease;
}

.modal.open {
    opacity: 1;
    transform: translateY(0);
}
</code></pre>

<p>Rather than animating:</p>

<pre><code class="language-css">top
left
width
height
</code></pre>

<p>you give the browser a better opportunity to perform the animation without repeatedly recalculating page geometry. But there’s an important warning here.</p>

<hr />

<h2 id="dont-turn-use-transform-into-another-rule-to-memorize">Don’t Turn “Use Transform” Into Another Rule to Memorize</h2>

<p>Frontend performance advice often becomes simplified into statements like:</p>

<blockquote>
  <p>Always animate <code>transform</code>.</p>
</blockquote>

<p>Or:</p>

<blockquote>
  <p><code>transform</code> doesn’t cause repaint.</p>
</blockquote>

<p>Those statements are useful shortcuts, but reality is more nuanced. Browsers make their own decisions about compositing layers. Effects such as filters, clipping, large painted areas, and complex descendants can influence how much work an animation requires. Hardware, browser versions, and the structure of the page matter too.</p>

<p>So instead of memorizing:</p>

<blockquote>
  <p><code>transform = fast</code></p>
</blockquote>

<p>remember the deeper idea:</p>

<blockquote>
  <p><strong>Prefer updates that allow the browser to avoid repeating earlier, more expensive stages of the rendering pipeline.</strong></p>
</blockquote>

<p>Then measure what actually happens.</p>

<hr />

<h2 id="will-change-useful-but-easy-to-abuse"><code>will-change</code>: Useful but Easy to Abuse</h2>

<p>CSS provides a property called <code>will-change</code>. For example:</p>

<pre><code class="language-css">.card {
    will-change: transform;
}
</code></pre>

<p>You’re essentially giving the browser a hint:</p>

<blockquote>
  <p>“This element is likely to change in this way soon.”</p>
</blockquote>

<p>The browser may use that information to prepare optimizations ahead of time, potentially including promoting the element to its own compositing layer. That can be useful for animations that are known to be performance-sensitive. But this does <strong>not</strong> mean you should do this:</p>

<pre><code class="language-css">* {
    will-change: transform;
}
</code></pre>

<p>Compositing layers aren’t free. They consume memory and other resources, and creating unnecessary layers can make performance worse rather than better. <code>will-change</code> should therefore be treated as a targeted optimization, not a default styling strategy.</p>

<hr />

<h2 id="dom-updates-and-reflow">DOM Updates and Reflow</h2>

<p>Another common source of rendering work is repeatedly modifying the DOM. Imagine adding 1,000 rows to a table. A naive implementation might look like:</p>

<pre><code class="language-javascript">for (let i = 0; i &lt; 1000; i++) {
    const row = document.createElement("tr");

    row.innerHTML = `
        &lt;td&gt;${i}&lt;/td&gt;
        &lt;td&gt;Customer ${i}&lt;/td&gt;
    `;

    table.appendChild(row);
}
</code></pre>

<p>Modern browsers are good at batching work, so this doesn’t automatically mean 1,000 complete reflows. Still, repeatedly touching the live DOM can create unnecessary work, especially when your code also performs layout reads or other operations between writes. One option is constructing the changes away from the live document first.</p>

<pre><code class="language-javascript">const fragment = document.createDocumentFragment();

for (let i = 0; i &lt; 1000; i++) {
    const row = document.createElement("tr");

    row.innerHTML = `
        &lt;td&gt;${i}&lt;/td&gt;
        &lt;td&gt;Customer ${i}&lt;/td&gt;
    `;

    fragment.appendChild(row);
}

table.appendChild(fragment);
</code></pre>

<p>The browser receives the collection of new nodes together. The broader principle is more important than <code>DocumentFragment</code> itself:</p>

<blockquote>
  <p><strong>Batch related DOM updates where practical instead of constantly alternating between DOM writes and layout-dependent reads.</strong></p>
</blockquote>

<p>Modern frameworks often help organize updates for you, but they cannot eliminate poor rendering patterns entirely.</p>

<hr />

<h2 id="react-doesnt-make-reflow-disappear">React Doesn’t Make Reflow Disappear</h2>

<p>Suppose you’re using React. You write:</p>

<pre><code class="language-jsx">function Sidebar({ open }) {
    return (
        &lt;aside
            className={open ? "sidebar open" : "sidebar"}
        &gt;
            Menu
        &lt;/aside&gt;
    );
}
</code></pre>

<p>React determines what needs to change in the DOM. But after React updates the DOM, the browser still has to render the result. If your CSS says:</p>

<pre><code class="language-css">.sidebar {
    width: 0;
    transition: width 300ms;
}

.sidebar.open {
    width: 300px;
}
</code></pre>

<p>the browser may need to perform layout repeatedly while that width is being animated. React’s reconciliation algorithm doesn’t remove that cost. The same applies to Vue, Angular, Svelte, Solid, and other frameworks. Frameworks determine <strong>what DOM changes should happen</strong>. The browser determines <strong>how those changes become pixels</strong>.</p>

<pre><code class="language-text">Application State
       │
       ▼
Framework
       │
       ▼
DOM Update
       │
       ▼
Browser
       │
       ├── Layout?
       ├── Paint?
       └── Composite?
</code></pre>

<p>This distinction is important. A highly optimized React component can still produce expensive browser rendering work.</p>

<hr />

<h2 id="a-real-world-example-expanding-an-accordion">A Real-World Example: Expanding an Accordion</h2>

<p>Imagine an FAQ section. When the user clicks a question, the answer expands. A common implementation animates height.</p>

<pre><code class="language-css">.answer {
    height: 0;
    overflow: hidden;
    transition: height 300ms;
}

.answer.open {
    height: 200px;
}
</code></pre>

<p>The animation looks simple. But as the height changes:</p>

<pre><code class="language-text">0px
20px
40px
60px
80px
...
200px
</code></pre>

<p>the elements underneath may need to move during each stage. Conceptually:</p>

<pre><code class="language-text">Answer grows
    │
    ▼
Layout changes
    │
    ▼
Content below moves
    │
    ▼
Paint
    │
    ▼
Composite
</code></pre>

<p>This doesn’t automatically mean the animation is unacceptable. Sometimes layout animation is exactly what the design requires, and modern devices may handle it perfectly well. Performance engineering isn’t about eliminating every reflow. It’s about avoiding <strong>unnecessary</strong> or <strong>excessive</strong> work. That’s an important distinction.</p>

<hr />

<h2 id="reflow-is-not-the-enemy">Reflow Is Not the Enemy</h2>

<p>After learning about layout performance, it’s easy to become afraid of reflow. Don’t. Browsers are designed to perform layout, and changing layouts is a fundamental part of building interactive webpages. Adding a message to the page, opening a navigation menu, rendering search results, or resizing a responsive application may all require layout, and none of these are inherently bad. The problem arises when we force the browser to repeat expensive work unnecessarily.</p>

<p>This:</p>

<pre><code class="language-text">One user action
      │
      ▼
One coordinated DOM update
      │
      ▼
Layout
      │
      ▼
Paint
</code></pre>

<p>is perfectly normal.</p>

<p>This is more concerning:</p>

<pre><code class="language-text">One user action
      │
      ▼
Read
Write
Layout
Read
Write
Layout
Read
Write
Layout
Read
Write
Layout
...
</code></pre>

<p>Optimization is usually about reducing redundant work, not eliminating legitimate rendering work.</p>

<hr />

<h2 id="measuring-reflow-and-repaint">Measuring Reflow and Repaint</h2>

<p>You don’t have to guess whether your page is doing too much rendering work. Modern browsers provide performance profiling tools. In Chrome DevTools, for example, the <strong>Performance</strong> panel can record what happens during an interaction. You may see work categorized around:</p>

<pre><code class="language-text">Scripting

Rendering / Layout

Painting

Compositing
</code></pre>

<p>Suppose clicking a button causes a visible delay. Instead of immediately rewriting your React components, record the interaction. Perhaps JavaScript is the problem, layout takes too long, a huge section of the page is being repainted, or the main thread is busy doing unrelated work. The browser’s profiling tools help answer those questions.</p>

<p>This leads to one of the most useful rules in frontend performance:</p>

<blockquote>
  <p><strong>Measure before you optimize.</strong></p>
</blockquote>

<p>A theoretical optimization that saves 0.2 milliseconds isn’t worth making your code significantly harder to maintain. Focus on bottlenecks users can actually experience.</p>

<hr />

<h2 id="practical-ways-to-reduce-rendering-work">Practical Ways to Reduce Rendering Work</h2>

<p>Once you understand the rendering pipeline, several optimization techniques start to make sense naturally. When animating movement, prefer <code>transform</code> where it achieves the same visual result.</p>

<pre><code class="language-css">transform: translateX(100px);
</code></pre>

<p>When fading elements, prefer <code>opacity</code>.</p>

<pre><code class="language-css">opacity: 0;
</code></pre>

<p>Avoid repeatedly alternating layout reads and writes. Instead of:</p>

<pre><code class="language-text">READ → WRITE → READ → WRITE
</code></pre>

<p>prefer:</p>

<pre><code class="language-text">READ → READ → READ
          │
          ▼
WRITE → WRITE → WRITE
</code></pre>

<p>Batch related DOM updates where possible. Avoid unnecessary manipulation of large parts of the DOM. Be cautious with expensive visual effects on large or frequently changing areas. Use <code>will-change</code> only when profiling suggests it is useful. And most importantly, use browser performance tools to confirm where your application is spending time. These aren’t arbitrary “frontend best practices.” Every one of them follows from the same idea:</p>

<blockquote>
  <p><strong>Give the browser less unnecessary work to do before the next frame must appear.</strong></p>
</blockquote>

<hr />

<h2 id="the-167ms-problem">The 16.7ms Problem</h2>

<p>In the previous article, we introduced the idea of the browser’s frame budget. On a 60 Hz display, a new frame is available roughly every:</p>

<pre><code class="language-text">1000ms / 60 ≈ 16.7ms
</code></pre>

<p>That doesn’t mean your JavaScript gets the entire 16.7 milliseconds. The browser may also need to perform:</p>

<pre><code class="language-text">JavaScript
     │
     ▼
Style Calculation
     │
     ▼
Layout
     │
     ▼
Paint
     │
     ▼
Composite
</code></pre>

<p>If your code triggers repeated layout calculations and expensive paints, the browser may not finish everything before the next frame is due. A frame gets missed, then another. The user sees:</p>

<pre><code class="language-text">Smooth

● ● ● ● ● ● ● ● ● ●


Janky

● ●   ●     ● ●    ●
</code></pre>

<p>This is why rendering performance directly affects how an interface <strong>feels</strong>. Users don’t know that your page suffered a forced synchronous layout. They simply know that dragging the panel felt sluggish.</p>

<hr />

<h2 id="bringing-it-all-together">Bringing It All Together</h2>

<p>Reflow and repaint aren’t mysterious browser behaviors. They’re consequences of how browsers turn changing documents into pixels. When geometry changes, the browser may need to recalculate layout.</p>

<pre><code class="language-text">Change width / height / position
              │
              ▼
            Layout
              │
              ▼
             Paint
              │
              ▼
          Composite
</code></pre>

<p>When only appearance changes, layout may be avoided.</p>

<pre><code class="language-text">Change visual property
          │
          ▼
         Paint
          │
          ▼
      Composite
</code></pre>

<p>And some changes may be handled primarily during compositing.</p>

<pre><code class="language-text">Transform / Opacity
          │
          ▼
      Composite
</code></pre>

<p>Again, these are simplified mental models, not guarantees. But they give us a much better way to reason about frontend performance. Instead of asking:</p>

<blockquote>
  <p>“Which CSS properties are fast?”</p>
</blockquote>

<p>we can ask:</p>

<blockquote>
  <p><strong>“Which parts of the rendering pipeline does this update require the browser to repeat?”</strong></p>
</blockquote>

<p>That’s the question that scales beyond individual tricks.</p>

<hr />

<h2 id="final-thoughts">Final Thoughts</h2>

<p>Frontend performance is often taught as a collection of rules: use <code>transform</code>, avoid changing width, don’t touch the DOM too much, use <code>requestAnimationFrame</code>, and avoid forced layouts. Those recommendations can be useful, but memorizing them without understanding the browser makes them fragile. Once you understand reflow and repaint, the rules start explaining themselves. Changing geometry can require layout. Changing appearance can require painting. Some visual changes can be handled efficiently during compositing. Repeatedly forcing the browser backwards through that pipeline can consume the limited time available for each frame.</p>

<p>The goal isn’t to build an application that never triggers reflow or repaint. That’s unrealistic. The goal is to make those operations <strong>intentional rather than accidental</strong>. And perhaps the most dangerous accidental performance problem is one we’ve already encountered in this article: JavaScript asks the browser for information, changes something, asks for more information, changes something again, and continues doing this while the browser desperately tries to keep its layout up to date.</p>

<p>To understand why that happens, we need to understand how JavaScript itself gets scheduled.</p>

<hr />

<h2 id="whats-next">What’s Next?</h2>

<p>In the next article in <strong>Beyond the UI</strong>, we’ll move from rendering into JavaScript execution:</p>

<blockquote>
  <p><strong>The JavaScript Event Loop Explained: Why Your UI Freezes</strong></p>
</blockquote>

<p>We’ll explore the call stack, Web APIs, tasks, microtasks, promises, timers, and <code>requestAnimationFrame</code>, and see why an innocent-looking piece of JavaScript can prevent an entire interface from responding. Because sometimes your UI isn’t slow because the browser is painting too much. Sometimes the browser simply <strong>doesn’t get a chance to paint at all.</strong></p>
]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="Frontend" />
    
    <category term="Performance" />
    
  

  
    
    <category term="Frontend" />
    
    <category term="Performance" />
    
  

    <summary>Reflow and repaint are the two most common ways to update the UI. This article explains what they are, how they work, and why they are important.</summary>

  </entry>

  
  





  



  


  <entry>
    <title>The Browser Rendering Pipeline Explained: From HTML to Pixels</title>
    <link href="https://billyokeyo.dev/posts/browser-rendering-pipeline/" rel="alternate" type="text/html" title="The Browser Rendering Pipeline Explained: From HTML to Pixels" />
    <published>2026-08-17T00:00:00+00:00</published>
  
    <updated>2026-08-17T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/browser-rendering-pipeline/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/browser-rendering-pipeline/"><![CDATA[<blockquote>
  <p><em>“You write HTML and CSS. The browser’s job is to somehow turn them into pixels. What happens in between is one of the most important things a frontend developer can understand.”</em></p>
</blockquote>

<p>Open a browser and visit almost any website. Within milliseconds, text appears, buttons take shape, images load, colors fill the screen, and complex layouts arrange themselves into something you can interact with.</p>

<p>As developers, we usually think about the code responsible for that interface. We write something like:</p>

<pre><code class="language-html">&lt;div class="card"&gt;
    &lt;h2&gt;Welcome Back&lt;/h2&gt;
    &lt;p&gt;You have 3 new notifications.&lt;/p&gt;
    &lt;button&gt;View Notifications&lt;/button&gt;
&lt;/div&gt;
</code></pre>

<p>Then we add some CSS:</p>

<pre><code class="language-css">.card {
    padding: 24px;
    border-radius: 12px;
}

.card h2 {
    font-size: 24px;
}
</code></pre>

<p>We refresh the browser and see a card. It feels almost instantaneous. But the browser cannot display HTML, and it cannot display CSS either. Your monitor ultimately understands pixels.</p>

<p>Somewhere between receiving this:</p>

<pre><code class="language-html">&lt;h1&gt;Hello World&lt;/h1&gt;
</code></pre>

<p>and displaying <strong>Hello World</strong> on the screen, the browser has to parse the document, understand its structure, determine which CSS rules apply, calculate the size and position of elements, determine what needs to be drawn, organize those drawings into layers, and finally send the result to the screen.</p>

<p>That journey is known as the <strong>browser rendering pipeline</strong>.</p>

<p>At a high level, it looks something like this:</p>

<pre><code class="language-text">HTML
 │
 ▼
DOM

CSS
 │
 ▼
CSSOM

DOM + CSSOM
     │
     ▼
 Render Tree
     │
     ▼
   Layout
     │
     ▼
   Paint
     │
     ▼
Compositing
     │
     ▼
   Pixels
</code></pre>

<p>Understanding this pipeline changes the way you think about frontend development. Suddenly, performance problems such as layout thrashing, expensive animations, unnecessary repaints, and large stylesheets stop feeling mysterious. You begin to understand <strong>why</strong> certain operations are expensive rather than simply memorizing that they should be avoided.</p>

<p>So let’s follow a webpage from the moment the browser receives its HTML to the moment pixels appear on your screen.</p>

<hr />

<h2 id="step-1-the-browser-receives-html">Step 1: The Browser Receives HTML</h2>

<p>Suppose you navigate to:</p>

<pre><code class="language-text">https://example.com
</code></pre>

<p>After the networking work required to obtain the document, the browser begins receiving HTML. Importantly, it doesn’t necessarily wait for the entire document before doing anything. HTML can be processed progressively as bytes arrive over the network.</p>

<p>Imagine the server sends:</p>

<pre><code class="language-html">&lt;!DOCTYPE html&gt;
&lt;html&gt;
&lt;head&gt;
    &lt;title&gt;My Store&lt;/title&gt;
&lt;/head&gt;

&lt;body&gt;
    &lt;main&gt;
        &lt;h1&gt;Products&lt;/h1&gt;

        &lt;div class="product"&gt;
            &lt;h2&gt;Laptop&lt;/h2&gt;
            &lt;p&gt;KES 75,000&lt;/p&gt;
        &lt;/div&gt;
    &lt;/main&gt;
&lt;/body&gt;
&lt;/html&gt;
</code></pre>

<p>To us, this is a text document. To the browser, it’s a set of instructions describing the structure of a page. The first major job is converting that text into something the browser can work with. That something is the <strong>DOM</strong>.</p>

<hr />

<h2 id="step-2-building-the-dom">Step 2: Building the DOM</h2>

<p>DOM stands for <strong>Document Object Model</strong>. The browser parses the HTML and converts its elements into a tree of objects. Our previous HTML becomes conceptually similar to this:</p>

<pre><code class="language-text">Document
│
└── html
    │
    ├── head
    │   └── title
    │       └── "My Store"
    │
    └── body
        │
        └── main
            │
            ├── h1
            │   └── "Products"
            │
            └── div.product
                │
                ├── h2
                │   └── "Laptop"
                │
                └── p
                    └── "KES 75,000"
</code></pre>

<p>This tree is the DOM. The DOM isn’t simply a copy of the HTML file. It’s the browser’s <strong>in-memory representation of the document</strong>. That’s why JavaScript can do things like:</p>

<pre><code class="language-javascript">const title = document.querySelector("h1");

title.textContent = "Featured Products";
</code></pre>

<p>JavaScript isn’t editing your original HTML file. It’s modifying the DOM that the browser constructed from it. Once that DOM changes, the browser may need to perform additional rendering work so the screen reflects the new state.</p>

<p>We’ll come back to that shortly. For now, we have structure. But the browser still doesn’t know what the page should look like. For that, it needs CSS.</p>

<hr />

<h2 id="step-3-building-the-cssom">Step 3: Building the CSSOM</h2>

<p>Suppose our document references a stylesheet.</p>

<pre><code class="language-html">&lt;link rel="stylesheet" href="https://billyokeyo.dev/styles.css"&gt;
</code></pre>

<p>And that stylesheet contains:</p>

<pre><code class="language-css">body {
    font-family: Arial, sans-serif;
}

.product {
    padding: 20px;
    border: 1px solid #ddd;
}

.product h2 {
    font-size: 24px;
}
</code></pre>

<p>Just as the browser doesn’t directly work with raw HTML when rendering the page, it doesn’t simply treat CSS as a collection of strings. It parses the CSS and constructs another representation called the <strong>CSS Object Model</strong>, or <strong>CSSOM</strong>.</p>

<p>Conceptually:</p>

<pre><code class="language-text">CSSOM
│
├── body
│   └── font-family: Arial
│
└── .product
    │
    ├── padding: 20px
    ├── border: 1px solid #ddd
    │
    └── h2
        └── font-size: 24px
</code></pre>

<p>The real CSSOM is considerably more sophisticated because CSS involves inheritance, specificity, cascading rules, media queries, browser defaults, and many other considerations. But the important idea is simple. The browser now has two important pieces of information.</p>

<p>The <strong>DOM</strong> tells it:</p>

<blockquote>
  <p>What exists?</p>
</blockquote>

<p>The <strong>CSSOM</strong> helps determine:</p>

<blockquote>
  <p>What should it look like?</p>
</blockquote>

<p>Now the browser can begin combining them.</p>

<hr />

<h2 id="step-4-creating-the-render-tree">Step 4: Creating the Render Tree</h2>

<p>The browser doesn’t simply draw every node in the DOM. Some elements shouldn’t appear on screen.</p>

<p>Consider:</p>

<pre><code class="language-html">&lt;div class="message"&gt;
    Payment successful
&lt;/div&gt;

&lt;div class="debug"&gt;
    Internal debugging information
&lt;/div&gt;
</code></pre>

<p>With:</p>

<pre><code class="language-css">.debug {
    display: none;
}
</code></pre>

<p>The <code>.debug</code> element exists in the DOM. JavaScript can still find it.</p>

<pre><code class="language-javascript">document.querySelector(".debug");
</code></pre>

<p>But it doesn’t need to be rendered. This is why the browser constructs another structure: the <strong>render tree</strong>. The render tree combines relevant DOM nodes with their computed styles and contains the visual elements that need to participate in layout and painting.</p>

<p>Conceptually:</p>

<pre><code class="language-text">DOM                       CSSOM
 │                          │
 └────────────┬─────────────┘
              │
              ▼
         Render Tree
              │
      Visible elements
      + computed styles
</code></pre>

<p>An element with:</p>

<pre><code class="language-css">display: none;
</code></pre>

<p>doesn’t generate a box in the render tree.</p>

<p>There are some important subtleties here. For example:</p>

<pre><code class="language-css">visibility: hidden;
</code></pre>

<p>is different. The element is invisible, but it still occupies space in the layout. Understanding these differences becomes important when optimizing interfaces.</p>

<p>At this point, the browser knows <strong>what needs to be rendered</strong> and <strong>how it should look</strong>. But there’s still one major question. Where exactly should everything go?</p>

<hr />

<h2 id="step-5-layout-calculating-geometry">Step 5: Layout: Calculating Geometry</h2>

<p>Consider this CSS:</p>

<pre><code class="language-css">.container {
    width: 80%;
}

.card {
    width: 50%;
    padding: 20px;
}
</code></pre>

<p>What does <code>50%</code> actually mean in pixels? That depends on the size of the parent, and the parent’s size might depend on its parent. The browser therefore needs to calculate the geometry of the page. This stage is commonly called <strong>layout</strong>.</p>

<p>During layout, the browser determines things such as:</p>

<ul>
  <li>Element width</li>
  <li>Element height</li>
  <li>X position</li>
  <li>Y position</li>
  <li>Margins</li>
  <li>Padding</li>
  <li>Relationships between elements</li>
</ul>

<p>Imagine a viewport that is 1200 pixels wide.</p>

<p>If:</p>

<pre><code class="language-css">.container {
    width: 80%;
}
</code></pre>

<p>then the container may become:</p>

<pre><code class="language-text">960px
</code></pre>

<p>A child with:</p>

<pre><code class="language-css">width: 50%;
</code></pre>

<p>may therefore become:</p>

<pre><code class="language-text">480px
</code></pre>

<p>The browser performs these calculations throughout the relevant layout tree. The result might conceptually look like:</p>

<pre><code class="language-text">Viewport: 1200 × 800

┌───────────────────────────────────────┐
│ Header                                │
│ x: 0   y: 0                           │
│ width: 1200   height: 80              │
├───────────────────────────────────────┤
│                                       │
│   Product Card                        │
│   x: 120   y: 120                     │
│   width: 480   height: 220            │
│                                       │
└───────────────────────────────────────┘
</code></pre>

<p>The browser now knows exactly where elements belong. And this is where frontend performance starts becoming particularly interesting.</p>

<hr />

<h2 id="why-layout-can-be-expensive">Why Layout Can Be Expensive</h2>

<p>Suppose JavaScript changes the width of an element.</p>

<pre><code class="language-javascript">element.style.width = "800px";
</code></pre>

<p>That change may affect much more than that one element. Its children may need to move. Its siblings may need to move. Its parent’s dimensions might change. Other parts of the page may need to be recalculated. The browser may therefore need to perform layout again. This is commonly referred to as <strong>reflow</strong>.</p>

<p>Consider a list:</p>

<pre><code class="language-text">┌─────────────────────┐
│ Item 1              │
├─────────────────────┤
│ Item 2              │
├─────────────────────┤
│ Item 3              │
├─────────────────────┤
│ Item 4              │
└─────────────────────┘
</code></pre>

<p>If Item 1 suddenly becomes three times taller, Items 2, 3, and 4 may all need new positions. One small change has affected several elements. This is why repeatedly modifying layout-related properties can hurt performance, especially on complex pages.</p>

<p>But calculating positions still doesn’t put anything on the screen. The browser now needs to draw.</p>

<hr />

<h2 id="step-6-paint-turning-elements-into-drawing-instructions">Step 6: Paint: Turning Elements Into Drawing Instructions</h2>

<p>Once layout is complete, the browser knows what should appear and where it belongs. Now it needs to determine how to draw it. This is the <strong>paint</strong> stage.</p>

<p>Consider a button:</p>

<pre><code class="language-css">button {
    background: blue;
    color: white;
    border-radius: 8px;
    box-shadow: 0 4px 10px rgba(0,0,0,.2);
}
</code></pre>

<p>Painting may involve drawing:</p>

<ul>
  <li>The background</li>
  <li>The border</li>
  <li>The text</li>
  <li>The rounded corners</li>
  <li>The shadow</li>
</ul>

<p>The browser creates painting instructions representing these visual operations.</p>

<p>Conceptually:</p>

<pre><code class="language-text">Layout

Button:
x = 100
y = 200
width = 160
height = 48

        │
        ▼

Paint

Draw background
Draw border
Draw shadow
Draw text
</code></pre>

<p>Some visual effects are considerably more expensive to paint than others. Large shadows, complex gradients, filters, and large areas that change frequently can increase rendering work. This is why performance problems aren’t always caused by JavaScript. Sometimes the browser simply has too much visual work to perform.</p>

<hr />

<h2 id="step-7-compositing">Step 7: Compositing</h2>

<p>Modern webpages are often too complicated to paint as one giant flat image every time something changes. Browsers can divide parts of the page into separate compositing layers.</p>

<p>Imagine a page containing:</p>

<pre><code class="language-text">Background

Content

Navigation

Modal

Animation
</code></pre>

<p>Conceptually, the browser might treat these as layers:</p>

<pre><code class="language-text">          ┌─────────────┐
          │    Modal    │
          └─────────────┘
                 ▲
          ┌─────────────┐
          │ Navigation  │
          └─────────────┘
                 ▲
          ┌─────────────┐
          │   Content   │
          └─────────────┘
                 ▲
          ┌─────────────┐
          │ Background  │
          └─────────────┘
</code></pre>

<p>During <strong>compositing</strong>, those layers are assembled in the correct order to produce the final image. This is especially important for animations.</p>

<p>Suppose you animate an element using:</p>

<pre><code class="language-css">transform: translateX(200px);
</code></pre>

<p>In favorable cases, the browser can move an already-painted composited layer rather than recalculating the layout and repainting large parts of the page.</p>

<p>Compare that with repeatedly changing:</p>

<pre><code class="language-css">left: 200px;
</code></pre>

<p>Depending on the page and positioning context, changing <code>left</code> may trigger layout and subsequent rendering work. This is one reason frontend performance advice often recommends animating properties such as:</p>

<pre><code class="language-css">transform
opacity
</code></pre>

<p>when appropriate. The recommendation isn’t arbitrary. It comes directly from understanding how browsers render pages.</p>

<hr />

<h2 id="putting-the-entire-pipeline-together">Putting the Entire Pipeline Together</h2>

<p>We can now see the full journey.</p>

<pre><code class="language-text">                 HTML
                   │
                   ▼
              Parse HTML
                   │
                   ▼
                  DOM

                 CSS
                   │
                   ▼
               Parse CSS
                   │
                   ▼
                 CSSOM

           DOM + CSSOM
                   │
                   ▼
              Render Tree
                   │
                   ▼
                Layout
          Size + Position
                   │
                   ▼
                 Paint
         Drawing Instructions
                   │
                   ▼
              Compositing
            Combine Layers
                   │
                   ▼
                 Pixels
</code></pre>

<p>What started as text has become something visible on a screen. And the process happens incredibly quickly.</p>

<hr />

<h2 id="where-javascript-enters-the-picture">Where JavaScript Enters the Picture</h2>

<p>So far, we’ve mostly discussed HTML and CSS. But modern applications are highly dynamic. JavaScript constantly modifies the page.</p>

<p>Consider:</p>

<pre><code class="language-javascript">const card = document.querySelector(".card");

card.style.width = "600px";
</code></pre>

<p>Changing the width affects geometry. The browser may need to perform:</p>

<pre><code class="language-text">JavaScript
    │
    ▼
DOM / Style Change
    │
    ▼
Layout
    │
    ▼
Paint
    │
    ▼
Composite
</code></pre>

<p>Now consider:</p>

<pre><code class="language-javascript">card.style.backgroundColor = "red";
</code></pre>

<p>The geometry hasn’t changed. The card remains exactly where it was. The browser may therefore avoid layout and perform only the later rendering stages.</p>

<p>Conceptually:</p>

<pre><code class="language-text">JavaScript
    │
    ▼
Style Change
    │
    ▼
Paint
    │
    ▼
Composite
</code></pre>

<p>And for some composited animations:</p>

<pre><code class="language-javascript">card.style.transform = "translateX(100px)";
</code></pre>

<p>the browser may be able to perform primarily compositing work rather than recalculating the entire layout.</p>

<p>Conceptually:</p>

<pre><code class="language-text">JavaScript
    │
    ▼
Transform
    │
    ▼
Composite
</code></pre>

<p>The exact behavior depends on the browser and page, so these diagrams should be treated as useful mental models rather than rigid guarantees. But they reveal an important principle:</p>

<blockquote>
  <p><strong>Not every visual change costs the browser the same amount of work.</strong></p>
</blockquote>

<hr />

<h2 id="why-this-matters-for-frontend-developers">Why This Matters for Frontend Developers</h2>

<p>It’s easy to treat browser performance as something only framework authors need to worry about. But your everyday decisions influence this pipeline. When you manipulate the DOM thousands of times, you’re interacting with it. When you animate dimensions, you’re interacting with it. When you ship enormous stylesheets, you’re interacting with it. When you build deeply nested layouts, you’re interacting with it. When you repeatedly read layout information and immediately modify styles, you’re interacting with it.</p>

<p>Frameworks don’t eliminate the browser rendering pipeline. React still ends up modifying the DOM. Vue still ends up modifying the DOM. Angular still ends up modifying the DOM. Svelte still ends up modifying the DOM. Eventually, every web framework reaches the same destination:</p>

<pre><code class="language-text">Framework

   │

   ▼

DOM Changes

   │

   ▼

Browser Rendering Pipeline

   │

   ▼

Pixels
</code></pre>

<p>Understanding the browser therefore gives you knowledge that survives whichever framework becomes popular next.</p>

<hr />

<h2 id="a-practical-example">A Practical Example</h2>

<p>Imagine you’re building an animation. You write:</p>

<pre><code class="language-javascript">function move() {
    element.style.left =
        `${element.offsetLeft + 1}px`;

    requestAnimationFrame(move);
}

move();
</code></pre>

<p>Every frame, the code reads <code>offsetLeft</code> and then changes <code>left</code>. The browser may need layout information to answer the read, and the subsequent write can invalidate layout again. On a simple page, you may never notice. On a large application with hundreds or thousands of elements, repeated layout work can become expensive.</p>

<p>Now consider an animation using transforms:</p>

<pre><code class="language-javascript">let position = 0;

function move() {
    position += 1;

    element.style.transform =
        `translateX(${position}px)`;

    requestAnimationFrame(move);
}

move();
</code></pre>

<p>This gives the browser more opportunity to handle the animation efficiently through compositing.</p>

<p>Again, the point isn’t:</p>

<blockquote>
  <p>“<code>transform</code> is magically fast.”</p>
</blockquote>

<p>The important lesson is understanding <strong>why</strong> some changes can require less work from the rendering pipeline than others. Once you understand that, frontend optimization becomes reasoning rather than memorization.</p>

<hr />

<h2 id="the-browser-has-a-frame-budget">The Browser Has a Frame Budget</h2>

<p>Smooth interfaces usually aim for approximately <strong>60 frames per second</strong> on a 60 Hz display. That gives the browser roughly:</p>

<pre><code class="language-text">1000ms / 60 ≈ 16.7ms
</code></pre>

<p>to produce each frame.</p>

<p>Within that small window, the browser may need to:</p>

<pre><code class="language-text">JavaScript

↓

Style Calculation

↓

Layout

↓

Paint

↓

Composite

↓

Display Frame
</code></pre>

<p>If the work takes significantly longer than the available frame time, the browser may miss a frame. Users experience that as:</p>

<ul>
  <li>Jank</li>
  <li>Stuttering</li>
  <li>Delayed interactions</li>
  <li>Choppy animations</li>
  <li>An interface that simply feels slow</li>
</ul>

<p>This is why a page can load quickly and still feel terrible to use. Performance isn’t only about how quickly resources download. It’s also about how efficiently the browser can respond to changes after the page has loaded.</p>

<hr />

<h2 id="common-rendering-performance-mistakes">Common Rendering Performance Mistakes</h2>

<p>Understanding the pipeline makes several common frontend mistakes easier to recognize. One is changing layout properties continuously during animations. Another is performing large numbers of DOM operations individually when they could be grouped together. Developers can also accidentally force repeated layout calculations by alternating between reading geometry and modifying styles. Large and unnecessary visual effects can make painting more expensive. Creating too many compositing layers can consume additional memory rather than improving performance.</p>

<p>And perhaps most importantly, developers sometimes optimize based on rules they’ve memorized instead of measuring what the browser is actually doing. Modern browser developer tools can show you layout work, painting, long tasks, frame timings, and other performance information. Use them.</p>

<p>The rendering pipeline gives you the mental model. Profiling tells you what your particular application is actually doing.</p>

<hr />

<h2 id="bringing-it-all-together">Bringing It All Together</h2>

<p>When you write:</p>

<pre><code class="language-html">&lt;button&gt;Buy Now&lt;/button&gt;
</code></pre>

<p>the browser does far more work than the simplicity of that line suggests. It parses the HTML. It constructs the DOM. It processes CSS and builds the CSSOM. It determines which elements need to participate in rendering. It calculates their dimensions and positions. It generates painting instructions. It organizes visual content into layers where appropriate. Finally, it composites everything into the pixels you see on your screen.</p>

<pre><code class="language-text">HTML ──────► DOM
               │
               │
CSS ───────► CSSOM
               │
               ▼
          Render Tree
               │
               ▼
            Layout
               │
               ▼
             Paint
               │
               ▼
          Compositing
               │
               ▼
             Pixels
</code></pre>

<p>And whenever your application changes the page, parts of that process may happen again. That’s why understanding browser rendering is so useful. It transforms frontend performance from a collection of mysterious rules into something you can reason about.</p>

<hr />

<h2 id="final-thoughts">Final Thoughts</h2>

<p>Frontend development is often taught from the framework downward. Learn React. Learn Vue. Learn Angular. Learn Next.js. Those tools are useful, but underneath every one of them sits the browser.</p>

<p>The browser doesn’t know that your application uses React. It doesn’t care whether your state came from Redux, Zustand, Pinia, signals, or a server component. Eventually, something needs to become HTML, styles, layout, drawing instructions, and pixels.</p>

<p>Understanding that journey gives you a foundation that isn’t tied to any particular framework. The next time an animation stutters, a page becomes sluggish after a DOM update, or a seemingly harmless CSS change causes unexpected performance problems, you’ll have a much better question to ask than:</p>

<blockquote>
  <p><strong>“Why is the browser slow?”</strong></p>
</blockquote>

<p>You can ask:</p>

<blockquote>
  <p><strong>“Which part of the rendering pipeline am I forcing the browser to repeat?”</strong></p>
</blockquote>

<p>And that’s a much more useful question.</p>

<hr />

<h2 id="whats-next">What’s Next?</h2>

<p>We’ve seen how the browser transforms HTML and CSS into pixels. But we also discovered something interesting along the way. Changing certain properties can force the browser to calculate layout again. Other changes may require repainting. Some animations can avoid much of that work and happen primarily during compositing.</p>

<p>So what exactly makes one visual update more expensive than another?</p>

<p>That’s where we’ll go next in <strong>Beyond the UI</strong>:</p>

<blockquote>
  <p><strong>Reflow and Repaint Explained: Why Some UI Updates Are Expensive</strong></p>
</blockquote>

<p>We’ll explore what actually happens when the DOM changes, how layout thrashing occurs, why certain CSS properties are more expensive to animate, and how to build interfaces that remain smooth even as they become more complex.</p>
]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="Frontend" />
    
    <category term="Performance" />
    
  

  
    
    <category term="Frontend" />
    
    <category term="Performance" />
    
  

    <summary>The browser rendering pipeline is the process by which the browser converts HTML and CSS into pixels. This article explains what the browser rendering pipeline is, how it works, and why it is important.</summary>

  </entry>

  
  





  



  


  <entry>
    <title>Event-Driven Architecture Explained: Building Systems That React to Events</title>
    <link href="https://billyokeyo.dev/posts/event-driven-architecture/" rel="alternate" type="text/html" title="Event-Driven Architecture Explained: Building Systems That React to Events" />
    <published>2026-07-31T00:00:00+00:00</published>
  
    <updated>2026-07-31T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/event-driven-architecture/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/event-driven-architecture/"><![CDATA[<blockquote>
  <p><em>“The most scalable systems don’t constantly ask what’s happening. They simply react when something happens.”</em></p>
</blockquote>

<p>Imagine you’re building an online marketplace. A customer places an order. At first, the workflow seems straightforward. The application creates the order, charges the customer’s card, reserves inventory, schedules shipment, sends a confirmation email, updates analytics, awards loyalty points, and notifies the warehouse. A traditional implementation might have the Order Service call each of these services directly.</p>

<pre><code class="language-text">Order Service

     │

     ├── Payment Service

     ├── Inventory Service

     ├── Shipping Service

     ├── Email Service

     ├── Analytics Service

     └── Loyalty Service
</code></pre>

<p>At first, this architecture feels perfectly reasonable. Each service performs its work and returns a response. As the business grows, however, the Order Service slowly becomes responsible for more and more integrations. Marketing introduces a Recommendation Service, finance adds an Accounting Service, customer success wants a CRM integration, and fraud detection joins the platform. Before long, every new feature requires modifying the Order Service. A service that originally knew only how to create orders now knows almost everything about the entire company. The result is tight coupling. Every new integration increases complexity, every downstream outage affects the original request, and every deployment becomes slightly more risky.</p>

<p>Eventually, developers begin asking a different question. Instead of asking:</p>

<blockquote>
  <p><strong>“Which services should I call?”</strong></p>
</blockquote>

<p>They begin asking:</p>

<blockquote>
  <p><strong>“What happened?”</strong></p>
</blockquote>

<p>That small change in thinking fundamentally changes the architecture. Instead of directly calling every interested service, the Order Service simply announces:</p>

<blockquote>
  <p><strong>“An order has been created.”</strong></p>
</blockquote>

<p>It doesn’t care who listens and doesn’t even know who listens. It simply publishes an event, and every interested service reacts independently. The Shipping Service prepares delivery, the Email Service sends a confirmation, analytics records another sale, loyalty awards points, fraud detection evaluates the transaction, and recommendation engines update customer preferences. The Order Service never calls any of them directly.</p>

<p>This architectural style is known as <strong>Event-Driven Architecture (EDA)</strong>. Instead of services communicating through tightly coupled request-response interactions, they communicate through events describing things that have already happened. This shift may seem subtle, but in reality, it completely changes how distributed systems evolve, scale, and recover from failure.</p>

<hr />

<h3 id="what-is-an-event">What Is an Event?</h3>

<p>Before discussing Event-Driven Architecture, it’s important to understand what an event actually is. An event is simply a record that something meaningful has already happened. It is not something that might happen, and not something another service should do, but something that has already occurred. Examples include:</p>

<ul>
  <li>Order Created</li>
  <li>Payment Completed</li>
  <li>Customer Registered</li>
  <li>Loan Approved</li>
  <li>Inventory Reserved</li>
  <li>Shipment Delivered</li>
</ul>

<p>Notice the wording: every event is written in the past tense because events describe facts. Once an event has occurred, it becomes part of the system’s history. Unlike commands, events don’t tell another service what to do. They simply communicate what has already happened. This distinction is incredibly important. Consider the difference between these two messages.</p>

<pre><code class="language-text">Command

Charge Customer
</code></pre>

<pre><code class="language-text">Event

Customer Charged
</code></pre>

<p>The first message expects another service to perform work; the second informs the rest of the system that the work has already been completed. Commands ask; events announce. That simple distinction lies at the heart of Event-Driven Architecture.</p>

<hr />

<h3 id="how-event-driven-systems-work">How Event-Driven Systems Work</h3>

<p>Imagine a borrower submits a loan application. The Loan Service validates the request, stores the application, and commits its transaction. Rather than directly calling every downstream service, it publishes a <strong>LoanApplicationSubmitted</strong> event, and from there every interested service works independently.</p>

<pre><code class="language-text">Loan Service

      │

LoanApplicationSubmitted

      │

──────── Event Broker ────────

      │

      ├── Risk Service

      ├── Notification Service

      ├── Fraud Detection

      ├── CRM

      └── Analytics
</code></pre>

<p>Notice what changed: the Loan Service no longer knows anything about these downstream systems. Adding another consumer doesn’t require modifying the Loan Service, and removing one doesn’t either. Every service simply subscribes to the events it cares about. That loose coupling is one of the defining advantages of Event-Driven Architecture.</p>

<hr />

<h3 id="why-this-improves-scalability">Why This Improves Scalability</h3>

<p>Suppose your application suddenly doubles in size. Marketing introduces three new services, operations introduces two more, and finance adds another. In a request-response architecture, every one of those integrations often requires modifying the originating service. In an event-driven architecture, nothing changes. The new services simply subscribe to existing events, and the publisher remains exactly the same. This dramatically reduces coupling and allows applications to evolve much more independently. Instead of building systems that know about one another, you’re building systems that share facts. That distinction becomes increasingly valuable as applications grow.</p>

<h3 id="event-brokers-the-backbone-of-event-driven-systems">Event Brokers: The Backbone of Event-Driven Systems</h3>

<p>At this point, a natural question arises. If services no longer call one another directly, how do events actually travel through the system? The answer is an <strong>event broker</strong>. An event broker acts as the central communication hub for your architecture. Instead of sending events directly to every interested service, a publisher sends the event to the broker, and the broker becomes responsible for delivering it to every subscriber. Conceptually, the architecture looks like this:</p>

<pre><code class="language-text">                Order Service

                     │

      OrderCreated Event

                     │

                     ▼

             Event Broker

     ┌─────────┼─────────┐

     ▼         ▼         ▼

 Inventory   Shipping   Analytics

   Service    Service     Service
</code></pre>

<p>Notice what has disappeared: the Order Service no longer knows how many consumers exist, doesn’t know whether the Analytics Service is online, and doesn’t know whether another team introduces a Recommendation Service next month. Its only responsibility is publishing the event. Everything else becomes someone else’s concern. Several technologies can act as event brokers. Apache Kafka is widely used for high-throughput event streaming. RabbitMQ is popular for traditional message queuing. Cloud platforms offer managed services such as Amazon EventBridge, Amazon SQS, Azure Service Bus, and Google Pub/Sub. Each has different strengths, but they all serve the same purpose: moving events from producers to consumers without tightly coupling the two.</p>

<hr />

<h3 id="why-event-driven-architecture-matters">Why Event-Driven Architecture Matters</h3>

<p>At first glance, publishing events instead of calling APIs might not seem like a revolutionary change. In practice, however, it fundamentally changes how software evolves. Consider our online marketplace again. The Order Service publishes an <strong>OrderCreated</strong> event. Initially, only three services consume it.</p>

<ul>
  <li>Shipping</li>
  <li>Email</li>
  <li>Inventory</li>
</ul>

<p>A year later, the business introduces:</p>

<ul>
  <li>Fraud Detection</li>
  <li>Recommendation Engine</li>
  <li>Customer Rewards</li>
  <li>CRM Integration</li>
  <li>Business Intelligence</li>
  <li>Machine Learning</li>
</ul>

<p>The Order Service doesn’t change. It continues publishing exactly the same event, and the new services simply subscribe. This is one of the greatest strengths of Event-Driven Architecture: applications grow by adding consumers rather than modifying existing publishers, which greatly reduces the ripple effect of change.</p>

<hr />

<h3 id="the-trade-offs">The Trade-Offs</h3>

<p>Like every architectural style, Event-Driven Architecture solves some problems while introducing others. One important difference is that communication becomes asynchronous. When a customer places an order, the application may respond immediately even though several downstream services are still processing events. This improves responsiveness but introduces <strong>eventual consistency</strong>.</p>

<p>For a short period, different services may have slightly different views of the system. The order may already exist while the reporting dashboard hasn’t yet been updated, or the shipment may still be pending while the payment has already completed. This isn’t necessarily a problem; it’s simply a different consistency model, and applications must be designed with that reality in mind. Debugging also becomes more challenging. In a request-response architecture, tracing a workflow often means following a sequence of API calls. In an event-driven architecture, the workflow is distributed across many independent services reacting to events at different times, so good observability becomes essential. Correlation IDs, distributed tracing, structured logging, and monitoring tools become increasingly valuable as systems grow.</p>

<hr />

<h3 id="common-mistakes">Common Mistakes</h3>

<p>One of the biggest mistakes teams make is publishing events for everything. Not every database update deserves an event. Good events represent meaningful business occurrences. Examples include:</p>

<ul>
  <li>Customer Registered</li>
  <li>Order Completed</li>
  <li>Loan Approved</li>
  <li>Payment Received</li>
</ul>

<p>Poor events often expose internal implementation details. Examples include:</p>

<ul>
  <li>CustomerTableUpdated</li>
  <li>RowModified</li>
  <li>AddressFieldChanged</li>
</ul>

<p>Consumers should care about business facts, not database implementation. Another common mistake is assuming events are delivered exactly once. In reality, duplicates can occur, messages can be delayed, and consumers can retry. This is why patterns we’ve already explored, such as <strong>Idempotency</strong>, remain critically important. Reliable event-driven systems assume events may be delivered more than once and design consumers accordingly. Finally, avoid replacing every API with events. Not every interaction should be asynchronous. Some operations naturally require an immediate response. For example:</p>

<ul>
  <li>User authentication</li>
  <li>Payment authorization</li>
  <li>Real-time validation</li>
</ul>

<p>A healthy architecture often combines synchronous APIs with asynchronous events, using each where it makes the most sense.</p>

<hr />

<h3 id="request-response-vs-event-driven">Request-Response vs Event-Driven</h3>

<p>A useful way to compare these architectures is to think about who controls the conversation.</p>

<p>In a request-response system, one service explicitly asks another service to perform work, and the caller waits for an answer before continuing. In an event-driven system, a service simply announces what has already happened. Anyone interested may react, and anyone uninterested simply ignores the event. Neither architecture is universally better. Request-response communication is often simpler and easier to understand, while event-driven communication provides greater flexibility and scalability as systems become more complex. Most modern applications use both. User-facing requests frequently begin as synchronous API calls, and once the business transaction completes, the application publishes events that allow the rest of the system to react independently.</p>

<hr />

<h3 id="how-everything-fits-together">How Everything Fits Together</h3>

<p>If you’ve followed this series from the beginning, you’ve probably noticed a pattern. Each article answered a question created by the previous one.</p>

<table>
  <thead>
    <tr>
      <th>Concept</th>
      <th>Question It Answers</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>Idempotency</strong></td>
      <td>What if the same request arrives twice?</td>
    </tr>
    <tr>
      <td><strong>Race Conditions</strong></td>
      <td>What if multiple requests modify the same data?</td>
    </tr>
    <tr>
      <td><strong>Database Transactions</strong></td>
      <td>How do I keep related database operations atomic?</td>
    </tr>
    <tr>
      <td><strong>Isolation Levels</strong></td>
      <td>What should concurrent transactions be allowed to see?</td>
    </tr>
    <tr>
      <td><strong>Distributed Locks</strong></td>
      <td>How do multiple application instances coordinate work?</td>
    </tr>
    <tr>
      <td><strong>Outbox Pattern</strong></td>
      <td>How do I reliably publish events after committing data?</td>
    </tr>
    <tr>
      <td><strong>Saga Pattern</strong></td>
      <td>How do multiple services complete one business process?</td>
    </tr>
    <tr>
      <td><strong>CQRS</strong></td>
      <td>Should reads and writes use the same model?</td>
    </tr>
    <tr>
      <td><strong>Event-Driven Architecture</strong></td>
      <td>How do independent services communicate and evolve together?</td>
    </tr>
  </tbody>
</table>

<p>Notice that none of these patterns exists in isolation. An event-driven application might use:</p>

<ul>
  <li><strong>Idempotency</strong> to safely handle duplicate events.</li>
  <li><strong>Transactions</strong> to protect local database operations.</li>
  <li>The <strong>Outbox Pattern</strong> to reliably publish domain events.</li>
  <li><strong>Saga Pattern</strong> to coordinate long-running business workflows.</li>
  <li><strong>CQRS</strong> to optimize read and write workloads independently.</li>
  <li><strong>Distributed Locks</strong> where multiple application instances must coordinate exclusive work.</li>
</ul>

<p>The real power doesn’t come from mastering one pattern. It comes from understanding how they complement one another.</p>

<hr />

<h3 id="final-thoughts">Final Thoughts</h3>

<p>Software architecture isn’t about collecting design patterns. It’s about solving real problems with the right level of complexity. Event-Driven Architecture has become popular because it reflects how modern organizations grow. Teams become independent. Services evolve at different speeds. New features appear continuously. Direct dependencies become increasingly expensive to maintain. By allowing services to communicate through events rather than tightly coupled API calls, Event-Driven Architecture enables systems that are more flexible, more scalable, and more resilient to change. Like every pattern we’ve explored, however, it isn’t a silver bullet. Small applications may never need an event broker, and a well-designed monolith may outperform a poorly designed event-driven system. Architecture should always follow business needs, not trends. The goal isn’t to build the most sophisticated system possible. It’s to build the simplest system capable of solving today’s problem while leaving room for tomorrow’s growth.</p>

<hr />

<h3 id="beyond-crud-chapter-one-complete">Beyond CRUD: Chapter One Complete</h3>

<p>When we began this series, we started with a deceptively simple question:</p>

<blockquote>
  <p><strong>What happens if the same request arrives twice?</strong></p>
</blockquote>

<p>From there, we explored race conditions, transactions, concurrency, distributed coordination, reliable messaging, long-running workflows, scalable read models, and event-driven communication. Each article introduced a new piece of the puzzle, and together they form a foundation for understanding how modern backend systems remain reliable under retries, failures, concurrency, and scale.</p>

<p>If there’s one lesson to carry forward, it’s this:</p>

<blockquote>
  <p><strong>Reliable software isn’t built by avoiding failure. It’s built by expecting failure, understanding where it can occur, and designing systems that recover gracefully when it does.</strong></p>
</blockquote>

<p>That mindset, more than any single framework, language, or database, is what separates production-ready systems from code that only works under perfect conditions. The journey beyond CRUD doesn’t end here. It begins here.</p>
]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="Distributed Systems" />
    
    <category term="Concurrency" />
    
  

  
    
    <category term="Distributed Systems" />
    
    <category term="Concurrency" />
    
  

    <summary>Event-Driven Architecture is a pattern for building systems that react to events. This article explains what Event-Driven Architecture is, why it is important, and how it works.</summary>

  </entry>

  
  





  



  


  <entry>
    <title>CQRS Explained: Separating Reads and Writes for Scalable Systems</title>
    <link href="https://billyokeyo.dev/posts/cqrs-explained/" rel="alternate" type="text/html" title="CQRS Explained: Separating Reads and Writes for Scalable Systems" />
    <published>2026-07-27T00:00:00+00:00</published>
  
    <updated>2026-07-27T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/cqrs-explained/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/cqrs-explained/"><![CDATA[<blockquote>
  <p><em>“The way you write data isn’t always the best way to read it.”</em></p>
</blockquote>

<p>Imagine you’re building an online marketplace. Every day, thousands of customers browse products, place orders, track deliveries, and review their purchase history. At the same time, administrators manage inventory, warehouse staff update shipments, finance teams generate reports, and recommendation engines continuously analyze customer behavior.</p>

<p>From a user’s perspective, everything appears seamless. Behind the scenes, however, the application is performing two fundamentally different kinds of work. Some requests are <strong>changing</strong> data: a customer places an order, an administrator updates inventory, a payment is processed, or a shipment is marked as delivered. Other requests simply <strong>read</strong> data: customers search for products, managers open dashboards, support agents review order histories, and executives generate monthly reports.</p>

<p>At first, it’s tempting to handle both using the same database tables and the same application models. After all, an order is an order. Whether you’re creating it or displaying it, why shouldn’t the same model work for both? For many applications, that’s exactly what happens. The same entity is used for inserting records, updating records, validating business rules, and serving data to the user interface.</p>

<p>As applications grow, however, this approach begins to reveal its limitations. The information required to create an order is often very different from the information required to display one. Creating an order might require validating inventory, calculating taxes, applying discounts, verifying payment details, and enforcing business rules. Displaying an order, on the other hand, may require customer information, shipping updates, product images, payment status, warehouse progress, and delivery estimates, all combined into a single view optimized for the user.</p>

<p>Trying to satisfy both responsibilities with one model often leads to increasingly complicated code. The write model becomes cluttered with fields needed only for reporting, the read model becomes constrained by rules that exist only for data modification, queries grow more complex, performance begins to suffer, and developers start adding workarounds that make the system harder to maintain.</p>

<p>Eventually, an important realization emerges.</p>

<blockquote>
  <p><strong>The way we write data isn’t necessarily the best way to read it.</strong></p>
</blockquote>

<p>That simple observation led to a pattern known as <strong>Command Query Responsibility Segregation</strong>, more commonly called <strong>CQRS</strong>. Rather than forcing one model to satisfy two very different responsibilities, CQRS separates them completely. Commands become responsible for changing data, queries become responsible for reading data, and each side can then evolve independently, optimized for its own purpose. Before exploring how CQRS works, let’s first understand why combining reads and writes into the same model eventually becomes a problem.</p>

<h3 id="why-one-model-eventually-becomes-a-problem">Why One Model Eventually Becomes a Problem</h3>

<p>When most applications begin, life is simple. Suppose you’re building a loan management platform. A borrower submits a loan application. The application validates the input, saves the record, and later retrieves the same information whenever a loan officer opens the application. The same model handles both writing and reading.</p>

<pre><code>LoanApplication
</code></pre>

<p>Everything works perfectly. As the platform grows, however, different users begin asking for different views of the same information. A loan officer wants to see repayment history, guarantors, collateral, risk score, and supporting documents on one screen; finance wants reports showing outstanding balances grouped by branch; executives want dashboards displaying portfolio performance; and customers simply want to know whether their application has been approved.</p>

<p>Notice what’s happening: everyone is looking at the same business entity, but nobody wants exactly the same data. To satisfy these different requirements, the application gradually starts joining more tables.</p>

<pre><code class="language-sql">Loan

JOIN Customer

JOIN Branch

JOIN RiskAssessment

JOIN LoanOfficer

JOIN Repayments

JOIN Documents

JOIN Guarantors
</code></pre>

<p>The queries become larger, response times increase, and the code becomes harder to maintain. Ironically, the information required to <strong>display</strong> a loan has become far more complicated than the information required to <strong>create</strong> one. This is where many systems begin struggling. The write model keeps accumulating fields that only reports need, the read model becomes constrained by business rules that only matter during updates, and eventually one model is trying to solve two completely different problems.</p>

<hr />

<h3 id="commands-and-queries-are-different">Commands and Queries Are Different</h3>

<p>One of the core ideas behind CQRS is recognizing that not every request has the same purpose. Some requests change data; others simply read it. These are fundamentally different operations. A <strong>command</strong> tells the system to perform an action. For example:</p>

<ul>
  <li>Create Order</li>
  <li>Approve Loan</li>
  <li>Reserve Inventory</li>
  <li>Charge Payment</li>
  <li>Register Customer</li>
</ul>

<p>Commands represent intent. They usually contain business validation, enforce rules, and modify application state. A <strong>query</strong>, on the other hand, doesn’t change anything. Its only responsibility is returning information. For example:</p>

<ul>
  <li>Get Customer Profile</li>
  <li>List Outstanding Loans</li>
  <li>View Order History</li>
  <li>Search Products</li>
  <li>Display Dashboard</li>
</ul>

<p>Queries don’t perform business logic. They answer questions. This distinction may seem small, but in reality, it changes how applications are designed.</p>

<hr />

<h3 id="what-is-cqrs">What Is CQRS?</h3>

<p>CQRS stands for <strong>Command Query Responsibility Segregation</strong>. Despite the intimidating name, the underlying idea is surprisingly simple. Instead of using one model for everything, CQRS separates the write side from the read side. Commands become responsible for modifying data, and queries become responsible for retrieving it. Conceptually, the architecture looks like this.</p>

<pre><code class="language-text">                Application

                     │

      ┌──────────────┴──────────────┐

      │                             │

   Commands                     Queries

      │                             │

Write Model                  Read Model

      │                             │

Database                 Optimized View
</code></pre>

<p>The important thing to notice is that the read model no longer has to look like the write model. Each side is free to evolve independently.</p>

<hr />

<h3 id="the-write-model">The Write Model</h3>

<p>The write model exists to protect business rules. Suppose a customer places an order. The application needs to verify inventory, calculate discounts, validate payment, reserve stock, and create the order. All of those steps belong on the write side. The write model isn’t concerned with how information will later appear on a dashboard. Its only responsibility is ensuring the business operation is correct. Think of it as the gatekeeper for your data. Nothing enters the system without passing through the write model.</p>

<hr />

<h3 id="the-read-model">The Read Model</h3>

<p>The read model has a completely different job. Its responsibility isn’t enforcing business rules, it’s returning information as efficiently as possible. Imagine displaying an order summary. The customer expects to see:</p>

<ul>
  <li>Order number</li>
  <li>Customer name</li>
  <li>Product images</li>
  <li>Shipping status</li>
  <li>Payment status</li>
  <li>Delivery estimate</li>
  <li>Total price</li>
</ul>

<p>The write model probably stores all of this across multiple tables, but the read model doesn’t have to. Instead, it can store exactly the shape required by the user interface, so instead of executing six joins every time someone opens an order, the read model may already contain everything in one place.</p>

<p>This dramatically simplifies queries while improving performance.</p>

<hr />

<h3 id="why-this-improves-performance">Why This Improves Performance</h3>

<p>Suppose an online store receives ten thousand requests every minute. Only five hundred of those requests create or update orders. The remaining nine thousand five hundred simply display information. Traditional CRUD applications often force both workloads through the same models and database structures. CQRS recognizes that reads and writes have completely different characteristics. Reads are usually far more frequent, while writes are usually more complicated. By separating them, each side can be optimized independently: the write model focuses on correctness, the read model focuses on speed, and neither compromises the other.</p>

<hr />

<h3 id="a-real-world-example">A Real-World Example</h3>

<p>Think about YouTube. Uploading a video and watching a video are two completely different operations. Uploading requires validation, virus scanning, metadata extraction, thumbnail generation, transcoding, and storage. Watching a video requires none of those things. The viewer simply wants the video to start playing immediately. Trying to optimize both operations using exactly the same model would make little sense.</p>

<p>CQRS applies the same principle to business applications. The model responsible for creating data doesn’t have to be the same model responsible for presenting it. Recognizing that difference is the first step toward understanding why CQRS has become such a popular architectural pattern in modern backend systems.</p>

<hr />

<p>At this point, we’ve separated reads from writes conceptually. The next question naturally follows:</p>

<blockquote>
  <p><strong>If the read model and write model are separate, how do they stay synchronized?</strong></p>
</blockquote>

<h3 id="keeping-the-read-model-up-to-date">Keeping the Read Model Up to Date</h3>

<p>One of the first questions developers ask after learning about CQRS is:</p>

<blockquote>
  <p><strong>“If my read model is separate from my write model, how does it stay up to date?”</strong></p>
</blockquote>

<p>The answer depends on the architecture, but in most modern systems, the read model is updated using <strong>events</strong>.</p>

<p>Suppose a customer places an order. The write model validates the request, checks inventory, processes payment, and commits the transaction. Once the transaction succeeds, an event such as <strong>OrderCreated</strong> is published, and one or more components responsible for maintaining the read model receive that event and update their own optimized view of the data.</p>

<p>Conceptually, the flow looks like this:</p>

<pre><code class="language-text">Customer

      │

      ▼

Command

(Create Order)

      │

      ▼

Write Model

      │

      ▼

Database

      │

      ▼

OrderCreated Event

      │

      ▼

Read Model Updated

      │

      ▼

User Queries Data
</code></pre>

<p>Notice something important: the user’s query never touches the write model. Instead, it reads from a model specifically designed for displaying information.</p>

<hr />

<h3 id="eventual-consistency">Eventual Consistency</h3>

<p>Because the read model is updated after the write completes, there is usually a short delay before the latest information becomes visible. This is known as <strong>eventual consistency</strong>. Imagine placing an order on a large e-commerce platform. The checkout page immediately confirms that your purchase was successful, but if you refresh your order history a fraction of a second later, the new order might not appear immediately. A moment later, it does. Nothing is wrong: the write completed instantly, and the read model simply needed a short amount of time to catch up. For many applications, this tiny delay is perfectly acceptable. Users rarely notice a difference measured in milliseconds or even a few seconds, and the benefit is that reads become dramatically faster and easier to scale.</p>

<hr />

<h3 id="does-cqrs-require-microservices">Does CQRS Require Microservices?</h3>

<p>One of the biggest misconceptions about CQRS is that it only works in microservice architectures. It doesn’t. CQRS is simply a design pattern. A single monolithic application can separate its command handlers from its query handlers just as effectively as a distributed system. Likewise, CQRS doesn’t require Kafka, RabbitMQ, Event Sourcing, or multiple databases. Many applications implement CQRS using a single database while maintaining separate command and query models inside the same application. As systems grow, those models may eventually evolve into separate databases or services, but that’s a scaling decision, not a requirement of the pattern itself.</p>

<hr />

<h3 id="when-should-you-use-cqrs">When Should You Use CQRS?</h3>

<p>CQRS isn’t a solution to every problem. Many applications work perfectly well using traditional CRUD architecture. If your application has simple business rules, relatively small datasets, and straightforward queries, introducing CQRS often adds unnecessary complexity. On the other hand, CQRS becomes increasingly valuable when reads and writes have very different characteristics. Common examples include:</p>

<ul>
  <li>High-traffic e-commerce platforms.</li>
  <li>Banking and financial systems.</li>
  <li>Loan management platforms.</li>
  <li>Logistics and supply chain applications.</li>
  <li>Reporting and analytics dashboards.</li>
  <li>SaaS products with complex administrative views.</li>
</ul>

<p>In these systems, the information required to display data is often very different from the information required to modify it. Separating those responsibilities makes the application easier to optimize and easier to maintain.</p>

<hr />

<h3 id="cqrs-vs-traditional-crud">CQRS vs Traditional CRUD</h3>

<p>A useful way to understand CQRS is to compare it with the architecture most developers already know.</p>

<table>
  <thead>
    <tr>
      <th>Traditional CRUD</th>
      <th>CQRS</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>One model for reads and writes</td>
      <td>Separate models for reads and writes</td>
    </tr>
    <tr>
      <td>Simpler to build</td>
      <td>More flexible at scale</td>
    </tr>
    <tr>
      <td>Easier for small systems</td>
      <td>Better suited for complex domains</td>
    </tr>
    <tr>
      <td>Queries often become increasingly complex</td>
      <td>Read models are optimized for specific use cases</td>
    </tr>
    <tr>
      <td>Business rules and presentation concerns frequently mix together</td>
      <td>Responsibilities remain clearly separated</td>
    </tr>
  </tbody>
</table>

<p>Neither approach is universally better. CRUD is an excellent choice for many applications. CQRS becomes valuable when the complexity of the domain begins to outweigh the simplicity of using a single model.</p>

<hr />

<h3 id="common-mistakes">Common Mistakes</h3>

<p>One mistake developers frequently make is adopting CQRS simply because they’ve heard it’s a “best practice.” Like every architectural pattern, CQRS introduces additional moving parts. You’ll often have separate models, additional event handling, and the possibility of eventual consistency. If those complexities don’t solve a real business problem, they’re simply unnecessary overhead. Another common mistake is trying to create one read model that satisfies every possible screen. The real strength of CQRS lies in allowing each query to have a model optimized for its own purpose. A customer dashboard, an administrative report, and a mobile application may each deserve different read models. Finally, don’t confuse CQRS with Event Sourcing. Although the two patterns are often used together, they solve different problems. CQRS separates reads from writes, while Event Sourcing stores state as a sequence of events. You can implement one without the other.</p>

<hr />

<h3 id="bringing-it-all-together">Bringing It All Together</h3>

<p>Throughout this series, we’ve gradually built a collection of patterns that solve different reliability and scalability challenges.</p>

<table>
  <thead>
    <tr>
      <th>Concept</th>
      <th>Question It Answers</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>Idempotency</strong></td>
      <td>What if the same request arrives twice?</td>
    </tr>
    <tr>
      <td><strong>Race Conditions</strong></td>
      <td>What if multiple requests modify the same data simultaneously?</td>
    </tr>
    <tr>
      <td><strong>Database Transactions</strong></td>
      <td>How do I keep database operations atomic?</td>
    </tr>
    <tr>
      <td><strong>Isolation Levels</strong></td>
      <td>What should concurrent transactions be allowed to see?</td>
    </tr>
    <tr>
      <td><strong>Distributed Locks</strong></td>
      <td>How do multiple application instances coordinate work?</td>
    </tr>
    <tr>
      <td><strong>Outbox Pattern</strong></td>
      <td>How do I reliably publish events after committing data?</td>
    </tr>
    <tr>
      <td><strong>Saga Pattern</strong></td>
      <td>How do multiple services complete one business process reliably?</td>
    </tr>
    <tr>
      <td><strong>CQRS</strong></td>
      <td>Should the same model be responsible for both reading and writing data?</td>
    </tr>
  </tbody>
</table>

<p>Notice how the series has gradually expanded in scope. We began by making individual API requests reliable, then learned how to coordinate transactions, communicate between services, and manage distributed business workflows. CQRS adds another important lesson: sometimes the best way to scale an application isn’t by making one model do everything, but by giving different responsibilities to different models.</p>

<hr />

<h3 id="final-thoughts">Final Thoughts</h3>

<p>One of the biggest lessons in software architecture is that different problems deserve different solutions. Reading data and writing data may involve the same business entity, but they rarely have the same requirements. Writes prioritize correctness, validation, and enforcing business rules; reads prioritize speed, simplicity, and delivering information in the shape users actually need. CQRS embraces this difference instead of trying to hide it. For small applications, a traditional CRUD architecture is often the right choice. As systems become larger and business requirements become more demanding, separating reads from writes can lead to simpler queries, clearer responsibilities, and applications that scale far more gracefully. Like every pattern we’ve explored in the <strong>Beyond CRUD</strong> series, CQRS isn’t about making software more complicated. It’s about choosing the right level of complexity to solve the problem in front of you.</p>

<hr />

<h3 id="whats-next">What’s Next?</h3>

<p>So far, we’ve explored several patterns that improve reliability, scalability, and maintainability. One question still remains: how do all these patterns fit together to build applications where services communicate entirely through events instead of direct API calls?</p>

<p>In the next article, we’ll explore <strong>Event-Driven Architecture Explained: Building Systems That React to Events</strong>, where we’ll connect concepts like the Outbox Pattern, Saga Pattern, and CQRS into a cohesive architectural style used by many modern distributed systems.</p>

]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="Distributed Systems" />
    
    <category term="Concurrency" />
    
  

  
    
    <category term="Distributed Systems" />
    
    <category term="Concurrency" />
    
  

    <summary>CQRS is a pattern for separating reads and writes for scalable systems. This article explains what CQRS is, why it is important, and how it works.</summary>

  </entry>

  
  





  



  


  <entry>
    <title>Saga Pattern Explained: Managing Distributed Transactions Across Microservices</title>
    <link href="https://billyokeyo.dev/posts/saga-pattern-explained/" rel="alternate" type="text/html" title="Saga Pattern Explained: Managing Distributed Transactions Across Microservices" />
    <published>2026-07-24T00:00:00+00:00</published>
  
    <updated>2026-07-24T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/saga-pattern-explained/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/saga-pattern-explained/"><![CDATA[<blockquote>
  <p><em>“A transaction can roll back one database. A Saga coordinates many databases that have never even met.”</em></p>
</blockquote>

<p>Imagine you’re building an online marketplace. A customer clicks <strong>Place Order</strong>, expecting what feels like a single operation. Behind the scenes, however, that simple button sets off a chain of events involving several independent services. The Order Service creates a new order, the Inventory Service reserves the purchased items, the Payment Service charges the customer’s card, the Shipping Service schedules delivery, and the Notification Service sends a confirmation email.</p>

<p>From the customer’s perspective, it’s one transaction. From your system’s perspective, it’s anything but. Each service owns its own database, each commits its own transaction independently, none of them has direct control over the others, and no single database transaction can span all of them.</p>

<p>Now imagine the following sequence: the Order Service successfully creates the order, the Inventory Service reserves the last laptop in stock, and the Payment Service charges the customer’s credit card. Then, just as the Shipping Service begins preparing the shipment, it discovers that delivery isn’t available to the customer’s location. The order already exists, the customer’s card has already been charged, and inventory has already been reserved, but the shipment can never be created. Unlike a traditional database transaction, there is no single <strong>ROLLBACK</strong> command capable of undoing work performed across multiple independent databases.</p>

<p>This is one of the defining challenges of distributed systems. As applications evolve from monoliths into microservices, business processes increasingly span services that are independently deployed, independently scaled, and independently owned. While this architecture offers tremendous flexibility, it also introduces a difficult question:</p>

<blockquote>
  <p><strong>How do you maintain business consistency when a workflow spans multiple services and one of them fails halfway through?</strong></p>
</blockquote>

<p>The answer is not a larger transaction. It’s a different way of thinking. Instead of trying to make every service commit simultaneously, modern distributed systems break long-running business processes into a sequence of smaller local transactions. If every step succeeds, the workflow completes successfully. If a step fails, previously completed work is undone using carefully designed <strong>compensating actions</strong> rather than database rollbacks.</p>

<p>This approach is known as the <strong>Saga Pattern</strong>. Like the Outbox Pattern, the Saga Pattern embraces the reality that failures are inevitable. Rather than pretending distributed transactions behave like local database transactions, it provides a practical way to recover when things don’t go according to plan. Before we explore how Sagas work, it’s important to understand why traditional transactions stop working once your application crosses service boundaries.</p>

<hr />

<h3 id="why-database-transactions-dont-scale-across-microservices">Why Database Transactions Don’t Scale Across Microservices</h3>

<p>Earlier in this series, we explored database transactions and learned how they guarantee that multiple operations either succeed together or fail together. If an online banking application deducts money from one account and credits another within the same database, a transaction ensures that both operations are treated as a single unit of work. If anything fails before the transaction commits, every change is rolled back automatically, leaving the database in a consistent state.</p>

<p>That model works beautifully when everything happens inside one database, but microservices change the picture completely. Imagine an order workflow involving four independent services.</p>

<pre><code class="language-text">Customer

      │

      ▼

Order Service

      │

      ▼

Inventory Service

      │

      ▼

Payment Service

      │

      ▼

Shipping Service
</code></pre>

<p>Each service owns its own database. The Order Service cannot directly roll back changes made by the Payment Service, the Payment Service cannot undo inventory reservations, and the Shipping Service has no authority over the Order database. Every service commits its own transaction independently. This independence is one of the greatest strengths of microservices, and it’s also one of their biggest challenges. Suppose the workflow progresses like this:</p>

<pre><code class="language-text">Create Order ✅

↓

Reserve Inventory ✅

↓

Charge Payment ✅

↓

Create Shipment ❌
</code></pre>

<p>At this point, three services have already committed their work, and nothing can simply “roll back.” Unlike a single database transaction, there is no global undo button. This challenge is often referred to as a <strong>distributed transaction</strong>, and solving it using traditional database techniques quickly becomes impractical.</p>

<p>Years ago, distributed systems experimented with approaches such as <strong>Two-Phase Commit (2PC)</strong>, where every participating system agreed to either commit or roll back together. While theoretically elegant, 2PC introduced significant coordination overhead, reduced availability, increased latency, and created situations where entire systems could become blocked waiting for slow or unavailable participants. Modern cloud-native architectures generally avoid this approach. Instead of attempting to make every service commit simultaneously, they accept that each service commits independently and focus on coordinating the overall business process.</p>

<p>That’s exactly what the Saga Pattern does. Instead of one large transaction, a Saga is a sequence of smaller transactions linked together by business logic. If every step succeeds, the Saga completes successfully; if one step fails, previously completed steps are compensated through additional business actions designed to reverse their effects. That distinction is subtle but incredibly important: a Saga doesn’t roll back database transactions, it performs new transactions whose purpose is to restore the system to a valid business state. Understanding that difference is the key to understanding everything else about the Saga Pattern.</p>

<h3 id="understanding-compensating-transactions">Understanding Compensating Transactions</h3>

<p>One of the biggest misconceptions developers have when they first encounter the Saga Pattern is assuming it somehow provides a distributed version of <code>ROLLBACK</code>. It doesn’t, and in fact, that’s one of the defining characteristics of a Saga. Once a service commits its local transaction, that transaction is permanent. The database has already saved the changes, and there is no mechanism for another service to rewind history. Instead of rolling back completed work, a Saga performs <strong>compensating transactions</strong>. A compensating transaction is simply another business operation whose purpose is to undo the effects of a previous one.</p>

<p>Suppose an order has already been created, inventory has been reserved, and payment has been successfully processed. If shipping later fails because the customer’s address falls outside the delivery area, the system cannot ask every database to roll back, because those transactions finished long ago. Instead, the application performs a series of new operations: the payment service issues a refund, the inventory service releases the reserved stock, and the order service changes the order status from <strong>Pending</strong> to <strong>Cancelled</strong>.</p>

<p>Notice something important: nothing has been deleted and nothing has been rolled back. The system simply performs additional work that restores the business to a valid state.</p>

<p>Conceptually, the workflow now looks like this:</p>

<pre><code class="language-text">Create Order ✅

↓

Reserve Inventory ✅

↓

Charge Payment ✅

↓

Create Shipment ❌

↓

Refund Payment

↓

Release Inventory

↓

Cancel Order
</code></pre>

<p>This is the heart of the Saga Pattern. Rather than pretending failures never happened, the system accepts them and responds with carefully designed business actions. This approach is much more realistic because, in distributed systems, failures aren’t exceptional, they’re inevitable.</p>

<hr />

<h3 id="a-banking-example">A Banking Example</h3>

<p>Imagine a customer applies for a personal loan. Several independent services participate in the approval process: the Loan Service creates the application, the Credit Service performs a credit check, the Risk Service evaluates affordability, and the Notification Service informs the customer of the decision. Everything proceeds normally until the Risk Service determines that the customer’s debt-to-income ratio exceeds the organization’s lending policy. At this point, the application cannot continue. If this were a single database transaction, we would simply issue a rollback.</p>

<p>In a microservice architecture, however, the Loan Service has already committed the new application and the Credit Service has already stored the completed credit assessment. Neither service can magically erase its work because another service encountered a problem. Instead, the Saga performs compensating actions: the Loan Service marks the application as withdrawn, the Credit Service archives its assessment, and the Notification Service informs the customer that the application could not proceed. Each action is itself a normal transaction, and collectively they restore the overall business process to a consistent state.</p>

<hr />

<h3 id="rollback-vs-compensation">Rollback vs Compensation</h3>

<p>Although these ideas sound similar, they’re fundamentally different. A database rollback behaves like this:</p>

<pre><code class="language-text">BEGIN

↓

Update Balance

↓

Insert Payment

↓

Failure

↓

ROLLBACK
</code></pre>

<p>When the rollback occurs, the database behaves as though none of the changes ever happened. It’s as if the transaction never existed. A Saga works very differently.</p>

<pre><code class="language-text">Reserve Inventory

↓

Charge Payment

↓

Shipment Fails

↓

Refund Payment

↓

Release Inventory
</code></pre>

<p>The original payment really happened, the refund also really happened, and both become part of the permanent history of the system. That’s an important distinction, and many business domains actually require this behavior. Consider financial systems. Deleting payment records would make auditing impossible, so recording both the payment and the subsequent refund creates a complete, traceable history of what occurred. Compensation isn’t about pretending mistakes never happened, it’s about correcting them transparently.</p>

<hr />

<h3 id="designing-good-compensating-actions">Designing Good Compensating Actions</h3>

<p>Writing a compensating transaction isn’t simply a matter of reversing database changes. You’re reversing business operations. For example, suppose a hotel booking system reserves a room.</p>

<p>The compensating action isn’t:</p>

<blockquote>
  <p>Delete reservation row.</p>
</blockquote>

<p>It’s:</p>

<blockquote>
  <p>Release the room back into available inventory.</p>
</blockquote>

<p>Similarly, if an airline charges a customer’s credit card, the compensation isn’t:</p>

<blockquote>
  <p>Delete payment record.</p>
</blockquote>

<p>It’s:</p>

<blockquote>
  <p>Create a refund transaction.</p>
</blockquote>

<p>This distinction matters because business systems are usually audited. Historical events should remain visible, and what changes is the current business state. Whenever you design a Saga, a useful question to ask is:</p>

<blockquote>
  <p><strong>“If this step succeeds but a later step fails, what business action restores the system to a valid state?”</strong></p>
</blockquote>

<p>Thinking in terms of business operations rather than database updates leads to much more reliable designs.</p>

<hr />

<h3 id="every-step-is-independent">Every Step Is Independent</h3>

<p>Another characteristic of Sagas is that every step represents a complete, independent transaction. Suppose an order workflow consists of four services.</p>

<pre><code class="language-text">Order Service

↓

Inventory Service

↓

Payment Service

↓

Shipping Service
</code></pre>

<p>Each service commits its own database transaction before the next service begins, which means failures are isolated. If the Shipping Service experiences an outage, it doesn’t corrupt the Payment Service’s database; likewise, if the Payment Service fails, it doesn’t leave the Inventory Service with an unfinished SQL transaction.</p>

<p>Each service remains responsible for its own data, and the Saga simply coordinates how those independent pieces fit together. This separation of responsibility is one of the reasons microservice architectures scale so well. Services remain loosely coupled while still participating in larger business workflows.</p>

<hr />

<h3 id="thinking-in-business-processes">Thinking in Business Processes</h3>

<p>One of the biggest mindset shifts when working with Sagas is realizing that you’re no longer designing database transactions. You’re designing business processes. Database transactions answer questions like:</p>

<blockquote>
  <p>“How do I keep these SQL statements consistent?”</p>
</blockquote>

<p>Sagas answer a much broader question:</p>

<blockquote>
  <p>“How does my business recover when part of this workflow succeeds and another part fails?”</p>
</blockquote>

<p>That’s why Sagas often involve business concepts rather than technical ones: refunds, reservation cancellations, order cancellations, inventory releases, and account reversals. These aren’t database operations; they’re business operations that happen to involve databases. Once you begin thinking at that level, the Saga Pattern becomes much easier to understand because it mirrors how real businesses operate. Companies don’t erase history when something goes wrong, they perform additional actions to correct it, and software simply follows the same principle.</p>

<h3 id="two-ways-to-coordinate-a-saga">Two Ways to Coordinate a Saga</h3>

<p>Now that we understand what a Saga is, another important question emerges: <strong>Who is responsible for coordinating all these steps?</strong></p>

<p>Imagine once again that a customer places an order. The Order Service creates the order, the Inventory Service reserves the stock, the Payment Service charges the customer, and the Shipping Service prepares the shipment. If everything succeeds, the Saga completes; if one step fails, compensating transactions begin. Someone, or something, must decide what happens next.</p>

<p>There are two common ways to achieve this coordination:</p>

<ul>
  <li><strong>Choreography</strong></li>
  <li><strong>Orchestration</strong></li>
</ul>

<p>Both accomplish the same goal, but they do so in very different ways.</p>

<hr />

<h3 id="choreography">Choreography</h3>

<p>Think about a group of experienced dancers performing together. Nobody stands at the front giving instructions. Each dancer knows exactly when to move because they respond to the music and to one another. Saga choreography works in much the same way. Instead of a central coordinator directing every step, each service reacts to events published by other services. Consider our order workflow.</p>

<pre><code class="language-text">Customer Places Order

        │

        ▼

Order Service

Publishes

OrderCreated

        │

        ▼

Inventory Service

Publishes

InventoryReserved

        │

        ▼

Payment Service

Publishes

PaymentCompleted

        │

        ▼

Shipping Service

Publishes

ShipmentCreated
</code></pre>

<p>Every service only knows two things:</p>

<ul>
  <li>The events it listens for.</li>
  <li>The events it publishes.</li>
</ul>

<p>The Payment Service doesn’t know the Shipping Service exists, and the Shipping Service doesn’t know anything about the Inventory Service. Each service simply reacts whenever an event arrives. This loose coupling is one of choreography’s greatest strengths. Because services know very little about one another, adding or removing services often becomes much easier.</p>

<p>Suppose your business introduces a Loyalty Service that awards reward points whenever an order is completed. Nothing else needs to change. The new service simply subscribes to the <strong>PaymentCompleted</strong> event, and the rest of the system continues operating exactly as before. This flexibility makes choreography extremely attractive in event-driven architectures. However, it comes with a cost. As systems grow, understanding the overall business workflow becomes increasingly difficult. Instead of one visible process, the Saga becomes scattered across many services.</p>

<p>To understand why a shipment wasn’t created, you may need to inspect logs from the Order Service, Inventory Service, Payment Service, Shipping Service, and Notification Service. The workflow still exists, it’s simply distributed across the entire system.</p>

<hr />

<h3 id="orchestration">Orchestration</h3>

<p>Now imagine the same dancers performing with a conductor standing at the front. Instead of reacting to one another, every performer follows instructions from a single leader. This is orchestration. Rather than allowing services to coordinate themselves, a dedicated component, often called the <strong>Saga Orchestrator</strong>, controls the entire workflow. The orchestrator tells each service what to do next.</p>

<pre><code class="language-text">Saga Orchestrator

        │

        ▼

Create Order

        │

        ▼

Reserve Inventory

        │

        ▼

Charge Payment

        │

        ▼

Create Shipment
</code></pre>

<p>If every step succeeds, the orchestrator declares the Saga complete. If a failure occurs, it explicitly instructs previous services to execute their compensating transactions.</p>

<pre><code class="language-text">Shipment Failed

        │

        ▼

Refund Payment

        │

        ▼

Release Inventory

        │

        ▼

Cancel Order
</code></pre>

<p>Unlike choreography, every decision is visible in one place. Need to understand the business process? Read the orchestrator. Need to change the workflow? Modify one component instead of updating several independent services. This centralized view makes orchestration particularly appealing for complex business processes involving many steps, conditional logic, or approval workflows. The trade-off, however, is tighter coupling. The orchestrator must understand every participating service, making it more aware of the overall system than any individual service would be in a choreographed Saga. Neither approach is universally better. The right choice depends on the complexity of the workflow and the level of control your application requires.</p>

<hr />

<h3 id="choreography-vs-orchestration">Choreography vs Orchestration</h3>

<p>A useful way to compare them is to think about where the business logic lives. With choreography, the workflow is distributed across many services, and every service contributes a small piece of the overall process by responding to events. With orchestration, the workflow lives inside a single coordinator that explicitly directs every participant.</p>

<table>
  <thead>
    <tr>
      <th>Choreography</th>
      <th>Orchestration</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Event-driven</td>
      <td>Command-driven</td>
    </tr>
    <tr>
      <td>Highly decoupled</td>
      <td>Central coordinator</td>
    </tr>
    <tr>
      <td>Easy to extend</td>
      <td>Easy to understand</td>
    </tr>
    <tr>
      <td>Workflow spread across services</td>
      <td>Workflow visible in one place</td>
    </tr>
    <tr>
      <td>Can become difficult to trace</td>
      <td>Coordinator becomes more complex</td>
    </tr>
  </tbody>
</table>

<p>Small event-driven systems often benefit from choreography because new consumers can easily subscribe to existing events. Larger enterprise workflows frequently choose orchestration because business rules remain easier to understand and maintain.</p>

<hr />

<h3 id="real-world-examples">Real-World Examples</h3>

<p>By now, you’ve probably encountered situations where the Saga Pattern would be useful without realizing it. An online retailer processing orders, a loan management platform approving applications, an airline booking system reserving flights, or a hotel reservation platform coordinating room availability all involve multiple independent services participating in a single business process. Consider a digital lending platform. When a borrower accepts a loan offer, several services may participate:</p>

<ul>
  <li>The Loan Service creates the loan account.</li>
  <li>The Disbursement Service sends funds.</li>
  <li>The Accounting Service records journal entries.</li>
  <li>The Notification Service sends an SMS.</li>
  <li>The Credit Bureau Service updates the borrower’s status.</li>
</ul>

<p>If the disbursement fails because the customer’s bank account is invalid, the system shouldn’t leave behind a partially created loan. Instead, compensating actions mark the loan as cancelled, reverse accounting entries where necessary, and notify the customer that disbursement was unsuccessful. No database rollback spans all these services, and the Saga restores business consistency through coordinated business actions.</p>

<hr />

<h3 id="common-mistakes">Common Mistakes</h3>

<p>The Saga Pattern is powerful, but it’s not a silver bullet. One common mistake is trying to treat compensating transactions as database rollbacks. They aren’t. Compensation should reverse business effects, not erase history. Another mistake is making Saga steps too large. Every local transaction should remain focused and complete quickly. Long-running database transactions reduce scalability and increase the likelihood of contention. It’s also important to remember that messaging is rarely perfect. Duplicate events, delayed delivery, and retries are normal in distributed systems. Every participating service should therefore be designed with idempotency in mind. Finally, don’t introduce a Saga simply because your application uses microservices. If a workflow only involves one service and one database, a normal database transaction is usually the simpler and better solution. Sagas solve distributed coordination problems, not ordinary CRUD operations.</p>

<hr />

<h3 id="saga-pattern-vs-traditional-transactions">Saga Pattern vs Traditional Transactions</h3>

<p>At first glance, Sagas and database transactions appear to solve similar problems. In reality, they operate at completely different levels. A database transaction guarantees consistency within a single database; a Saga guarantees business consistency across multiple independent services. One relies on rollback, the other relies on compensation. One typically completes in milliseconds, while the other may run for several minutes, or even hours, depending on the business process. They’re not competing approaches. As you’ve seen throughout this series, they complement one another. In fact, a single Saga step usually contains its own local database transaction.</p>

<hr />

<h3 id="bringing-it-all-together">Bringing It All Together</h3>

<p>At this point in the <strong>Beyond CRUD</strong> series, we’ve gradually built a toolkit for designing reliable backend systems. Each concept answers a different engineering question.</p>

<table>
  <thead>
    <tr>
      <th>Concept</th>
      <th>Question It Answers</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>Idempotency</strong></td>
      <td>What if the same request arrives twice?</td>
    </tr>
    <tr>
      <td><strong>Race Conditions</strong></td>
      <td>What if multiple requests modify the same data simultaneously?</td>
    </tr>
    <tr>
      <td><strong>Database Transactions</strong></td>
      <td>How do I keep multiple database operations atomic?</td>
    </tr>
    <tr>
      <td><strong>Isolation Levels</strong></td>
      <td>What should concurrent transactions be allowed to see?</td>
    </tr>
    <tr>
      <td><strong>Distributed Locks</strong></td>
      <td>How do multiple application instances coordinate shared work?</td>
    </tr>
    <tr>
      <td><strong>Outbox Pattern</strong></td>
      <td>How do I reliably publish events after committing data?</td>
    </tr>
    <tr>
      <td><strong>Saga Pattern</strong></td>
      <td>How do multiple services complete one business process reliably?</td>
    </tr>
  </tbody>
</table>

<p>Notice how every concept builds upon the previous one. None replaces the others, and reliable distributed systems emerge when these patterns work together.</p>

<hr />

<h3 id="final-thoughts">Final Thoughts</h3>

<p>Building software inside a single database is relatively straightforward. Building software that spans dozens of independent services is something else entirely. The challenge isn’t simply writing correct code, it’s ensuring that business processes continue making sense even when networks fail, services restart, or one step succeeds while another doesn’t.</p>

<p>The Saga Pattern embraces these realities rather than fighting them. Instead of relying on one enormous transaction that spans every service, it coordinates many smaller transactions while providing a structured way to recover when failures occur. That mindset has become one of the defining characteristics of modern cloud-native architecture. As your systems continue growing, you’ll discover that reliable software isn’t built by eliminating failures, it’s built by designing systems that expect failures and know exactly how to recover from them.</p>

<hr />

<h3 id="whats-next">What’s Next?</h3>

<p>So far, we’ve focused primarily on making writes reliable, but as applications grow, another challenge begins to emerge. Reading data efficiently often requires very different models from writing it. Should the same model be responsible for both, or should we optimize reads and writes independently?</p>

<p>In the next article, we’ll explore <strong>CQRS Explained: Separating Reads and Writes for Scalable Systems</strong>, a pattern that allows applications to scale, simplify complex queries, and build richer user experiences without overloading their write models.</p>
]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="Distributed Systems" />
    
    <category term="Concurrency" />
    
  

  
    
    <category term="Distributed Systems" />
    
    <category term="Concurrency" />
    
  

    <summary>The Saga Pattern is a pattern for managing distributed transactions across microservices. This article explains what the Saga Pattern is, why it is important, and how it works.</summary>

  </entry>

  
  





  



  


  <entry>
    <title>The Outbox Pattern Explained: Publishing Events Without Losing Data</title>
    <link href="https://billyokeyo.dev/posts/outbox-patterns-explained/" rel="alternate" type="text/html" title="The Outbox Pattern Explained: Publishing Events Without Losing Data" />
    <published>2026-07-20T00:00:00+00:00</published>
  
    <updated>2026-07-20T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/outbox-patterns-explained/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/outbox-patterns-explained/"><![CDATA[<blockquote>
  <p><em>“A database transaction can guarantee your data is correct. It cannot guarantee the rest of your system knows about it.”</em></p>
</blockquote>

<p>Imagine you’re building an e-commerce platform. A customer places an order, and your application begins processing the request. Inside a database transaction, it creates the order, deducts the purchased items from inventory, records the payment, and commits the transaction successfully. From the perspective of the database, everything has gone exactly as planned. Every change has been saved, every business rule has been respected, and the transaction completes without error.</p>

<p>If this were a monolithic application, the story might end there, but modern software rarely consists of a single application. The moment an order is created, several other systems need to react. A shipping service must prepare the package, an email service needs to send an order confirmation, an analytics platform wants to record another sale, a loyalty service may award reward points, and an accounting system might need to generate journal entries. Rather than constantly querying the orders table looking for changes, these services usually rely on events published through a message broker such as Kafka, RabbitMQ, Azure Service Bus, or Amazon SQS.</p>

<p>A straightforward implementation seems almost obvious: once the transaction commits successfully, publish an <strong>OrderCreated</strong> event.</p>

<pre><code class="language-text">BEGIN TRANSACTION

↓

Create Order

↓

Reduce Inventory

↓

Record Payment

↓

COMMIT

↓

Publish OrderCreated Event
</code></pre>

<p>At first glance, there’s nothing wrong with this approach, until something fails. Suppose the database transaction commits successfully, permanently saving the customer’s order. A fraction of a second later, however, Kafka becomes temporarily unavailable. Perhaps RabbitMQ disconnects, or maybe the application crashes before it can publish the event.</p>

<p>The order now exists in the database, the customer’s payment has been processed, and inventory has already been reduced, yet none of the downstream services know the purchase ever happened. The warehouse never receives instructions to prepare the shipment, the customer never receives a confirmation email, the analytics dashboard quietly reports incorrect sales figures, and the accounting system never records the transaction.</p>

<p>Nothing inside the database is inconsistent. The inconsistency exists <strong>between systems</strong>.</p>

<p>This subtle failure is one of the most common reliability problems in distributed architectures. It’s known as the <strong>Dual-Write Problem</strong>, and it’s surprisingly easy to introduce because writing to a database and publishing an event are two completely independent operations. One can succeed while the other fails, leaving different parts of the system with different versions of reality.</p>

<p>In our previous articles, we’ve explored how transactions protect database operations, how isolation levels govern concurrent access to data, and how distributed locks coordinate work across multiple application servers. The Outbox Pattern builds on those concepts by solving a different challenge: ensuring that once your database commits a change, the rest of your system will eventually learn about it as well.</p>

<p>Before we look at the solution, let’s first understand why this seemingly simple problem is much harder than it appears.</p>

<hr />

<h4 id="the-dual-write-problem">The Dual-Write Problem</h4>

<p>The Dual-Write Problem occurs whenever an application attempts to update two independent systems as part of a single business operation. One system is usually your database; the other is typically a message broker, search index, cache, analytics platform, or another external service. Although these updates feel like one logical operation, they are technically two completely separate actions.</p>

<p>Consider an online banking application. When a customer transfers money, the application updates account balances inside the database. Afterward, it publishes a <strong>MoneyTransferred</strong> event so other services can respond. A fraud detection system may inspect the transaction, a notification service may send an SMS, and an accounting platform may update its ledgers.</p>

<p>Conceptually, all of this represents one business event, but technically, it looks more like this:</p>

<pre><code class="language-text">Update Database

↓

Publish Event
</code></pre>

<p>The problem is that neither system knows anything about the other. Your database has no idea whether Kafka accepted the message, and Kafka has no knowledge of whether your SQL transaction committed successfully. They’re completely independent, and that independence creates four possible outcomes.</p>

<table>
  <thead>
    <tr>
      <th>Database</th>
      <th>Event</th>
      <th>Result</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>✅ Success</td>
      <td>✅ Success</td>
      <td>Everything works correctly.</td>
    </tr>
    <tr>
      <td>❌ Failure</td>
      <td>❌ Failure</td>
      <td>Nothing happens, which is acceptable.</td>
    </tr>
    <tr>
      <td>❌ Failure</td>
      <td>✅ Success</td>
      <td>Downstream systems react to an event for data that doesn’t exist.</td>
    </tr>
    <tr>
      <td>✅ Success</td>
      <td>❌ Failure</td>
      <td>The database is correct, but no other service knows the change occurred.</td>
    </tr>
  </tbody>
</table>

<p>The first two outcomes are easy to reason about, but it’s the final two that create serious problems. If an event is published for data that never commits, downstream services begin processing information that doesn’t actually exist. Equally dangerous is the opposite scenario, where the database commits successfully but the event is never published. From that moment onward, every service in the architecture has a different understanding of reality. This isn’t merely an inconvenience; it’s a consistency problem that becomes increasingly difficult to detect as systems grow.</p>

<hr />

<h3 id="why-transactions-cant-solve-this">Why Transactions Can’t Solve This</h3>

<p>A natural question follows: why not simply include the message broker inside the database transaction? Unfortunately, that’s not how database transactions work. Transactions provide atomicity because every operation is coordinated by the same database engine. The database controls when the transaction begins, when it commits, and when it rolls back. Every SQL statement participates in that process because they’re all executed by the same system.</p>

<p>A message broker lives outside that boundary. Kafka doesn’t participate in your PostgreSQL transaction, RabbitMQ doesn’t know your SQL Server transaction exists, and PostgreSQL has no mechanism for asking Kafka whether a message was published successfully before committing the transaction. In other words, there is no shared transaction manager coordinating both systems.</p>

<p>Years ago, technologies such as <strong>Two-Phase Commit (2PC)</strong> attempted to solve this problem by coordinating transactions across multiple systems. Although theoretically appealing, they introduced significant complexity, increased latency, reduced availability, and often became bottlenecks in distributed environments.</p>

<p>As microservices became more popular, the industry gradually moved toward simpler, more resilient approaches. Rather than trying to make two systems commit simultaneously, engineers began asking a different question:</p>

<blockquote>
  <p><strong>What if we only committed to one system first and made the second system eventually consistent?</strong></p>
</blockquote>

<p>That shift in thinking led to one of the most influential patterns in modern backend architecture: the <strong>Outbox Pattern</strong>.</p>

<h3 id="what-is-the-outbox-pattern">What Is the Outbox Pattern?</h3>

<p>The Outbox Pattern solves the Dual-Write Problem by changing the order in which work is performed. Instead of attempting to update the database and publish an event as part of the same operation, the application first commits everything it needs to the database, including the event itself. That last part is the key. Rather than sending the event directly to Kafka or RabbitMQ, the application writes the event into a dedicated database table commonly known as the <strong>outbox</strong>.</p>

<p>Because the business data and the outbox record are written inside the <strong>same database transaction</strong>, they succeed or fail together. If the transaction commits, both the business data and the event are safely stored; if it rolls back, neither exists. Only after the transaction has completed does another process read events from the outbox table and publish them to the message broker.</p>

<p>Conceptually, the workflow changes from this:</p>

<pre><code class="language-text">Update Database

↓

Publish Event
</code></pre>

<p>to this:</p>

<pre><code class="language-text">BEGIN TRANSACTION

↓

Update Business Data

↓

Insert Event Into Outbox

↓

COMMIT

↓

Background Publisher Reads Outbox

↓

Publish Event

↓

Mark Event As Published
</code></pre>

<p>At first glance, this may seem like a small adjustment, but in reality, it completely changes the reliability characteristics of your application. The application is no longer trying to coordinate two independent systems within the same request. Instead, it commits to a single source of truth, the database, and lets another process handle communication with external systems afterward. If the message broker is temporarily unavailable, nothing is lost. The event is already safely stored inside the database and simply waits until the publisher can deliver it.</p>

<hr />

<h3 id="understanding-the-outbox-table">Understanding the Outbox Table</h3>

<p>The outbox itself is usually nothing more than a normal database table. A simplified version might look like this:</p>

<table>
  <thead>
    <tr>
      <th style="text-align: right">id</th>
      <th>event_type</th>
      <th>payload</th>
      <th>created_at</th>
      <th>published_at</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: right">1</td>
      <td>OrderCreated</td>
      <td>{…}</td>
      <td>2026-07-01 10:15</td>
      <td>NULL</td>
    </tr>
    <tr>
      <td style="text-align: right">2</td>
      <td>PaymentReceived</td>
      <td>{…}</td>
      <td>2026-07-01 10:16</td>
      <td>NULL</td>
    </tr>
    <tr>
      <td style="text-align: right">3</td>
      <td>UserRegistered</td>
      <td>{…}</td>
      <td>2026-07-01 10:18</td>
      <td>2026-07-01 10:18</td>
    </tr>
  </tbody>
</table>

<p>Each row represents an event that should eventually be delivered. Notice the <code>published_at</code> column: rows where this value is <code>NULL</code> haven’t yet been published, while rows with a timestamp have already been successfully delivered.</p>

<p>The outbox isn’t intended to become a permanent event store. Instead, it acts as a reliable staging area between your transactional database and your messaging infrastructure. Once an event has been published successfully, and your retention policy allows, it can be archived or deleted.</p>

<hr />

<h3 id="a-complete-walkthrough">A Complete Walkthrough</h3>

<p>Let’s revisit our e-commerce example. A customer purchases a laptop. Inside a single transaction, the application performs three operations: first, it creates the order; second, it deducts one item from inventory; and finally, instead of publishing an event immediately, it inserts a new row into the outbox table describing what happened.</p>

<pre><code class="language-text">BEGIN TRANSACTION

↓

INSERT Order

↓

UPDATE Inventory

↓

INSERT Outbox Event

↓

COMMIT
</code></pre>

<p>At this point, the customer’s purchase has been committed successfully, and just as importantly, the event describing that purchase has also been committed. Suppose Kafka goes offline immediately afterward: the request still succeeds, nothing has been lost, and the application doesn’t need to roll back the order because the event hasn’t disappeared. It is sitting safely inside the outbox table waiting to be delivered.</p>

<p>A separate publisher service periodically checks the outbox. When Kafka becomes available again, it publishes the event and updates the record to indicate that delivery succeeded.</p>

<pre><code class="language-text">Outbox Publisher

↓

Read Unpublished Events

↓

Publish To Kafka

↓

Success?

      │

   Yes │ No

      │

Mark Published

      │

Retry Later
</code></pre>

<p>Notice something important: the user’s request is no longer responsible for talking to Kafka. Its only responsibility is ensuring that the event is safely recorded, and publishing becomes a separate concern. That separation dramatically improves reliability because temporary failures in external systems no longer affect the original business transaction.</p>

<hr />

<h3 id="why-this-works">Why This Works</h3>

<p>The elegance of the Outbox Pattern comes from the fact that it reduces a distributed systems problem to a database problem. Earlier in this series, we spent considerable time discussing transactions and learned that they guarantee a group of related database operations either all succeed or all fail together. The Outbox Pattern deliberately takes advantage of that guarantee: instead of asking a database and a message broker to commit simultaneously, a task they were never designed to perform, it asks only the database to commit. Since both the business data and the outbox record live inside the same database, the transaction naturally guarantees their consistency.</p>

<p>Everything after that becomes a delivery problem rather than a consistency problem. Even if the publisher crashes, Kafka becomes unavailable, or the network experiences intermittent failures, the event remains safely stored. The publisher will eventually retry, and the event will eventually be delivered. The system moves from requiring <strong>immediate consistency</strong> between the database and the message broker to achieving <strong>eventual consistency</strong> in a reliable and predictable way. That single shift in mindset is what has made the Outbox Pattern one of the most widely adopted reliability patterns in modern distributed systems.</p>

<hr />

<h3 id="why-not-publish-immediately-after-the-commit">Why Not Publish Immediately After the Commit?</h3>

<p>Some developers look at the Outbox Pattern and ask a reasonable question: “If the transaction has already committed successfully, why not simply publish the event right afterward and retry if it fails?” The problem is that retries only work if the application survives long enough to perform them.</p>

<p>Imagine the following sequence of events:</p>

<pre><code class="language-text">COMMIT Transaction

↓

Application Crashes

↓

Restart
</code></pre>

<p>The order exists, the event was never published, and the application has no memory that it still owes Kafka an event because that information was never persisted anywhere. With an outbox table, the event survives the crash because it was committed alongside the business data. When the publisher starts again, it simply resumes reading unpublished events from the database. The application doesn’t have to remember what happened because the database already does.</p>

<p>This is one of the reasons the Outbox Pattern is so resilient. It relies on durable storage rather than application memory, making it naturally tolerant of crashes, restarts, and temporary infrastructure failures.</p>

<h3 id="how-events-leave-the-outbox">How Events Leave the Outbox</h3>

<p>By now, we’ve established that the application’s responsibility ends once the business data and the corresponding event have been committed to the database. The next challenge is equally important: <strong>How do those events actually reach Kafka, RabbitMQ, or another messaging system?</strong></p>

<p>Broadly speaking, there are two common approaches. The first is a <strong>Polling Publisher</strong>, where a background worker periodically checks the outbox table for unpublished events. Every few seconds, or even every few milliseconds, it queries the database, publishes any pending events, and marks them as successfully delivered.</p>

<p>Conceptually, the process looks like this:</p>

<pre><code class="language-text">Background Publisher

↓

Query Outbox

↓

Find Unpublished Events

↓

Publish Event

↓

Success?

     │

 Yes │ No

     │

Mark Published

     │

Retry Later
</code></pre>

<p>This approach is simple to understand, easy to implement, and works well for many applications. Since the publisher operates independently of the original request, temporary failures in Kafka or RabbitMQ don’t affect users. If publishing fails, the worker simply retries later.</p>

<p>The second approach is <strong>Change Data Capture (CDC)</strong>. Instead of periodically querying the outbox table, a CDC tool monitors the database’s transaction log and automatically detects newly inserted outbox records. As soon as a new event appears, the tool publishes it to the message broker.</p>

<p>One of the most popular CDC solutions is <strong>Debezium</strong>, which integrates with databases such as PostgreSQL, MySQL, and SQL Server. Rather than polling the database repeatedly, Debezium continuously streams database changes, reducing unnecessary queries while providing near real-time event publication. Both approaches solve the same problem. Polling is generally simpler and perfectly adequate for many systems, while CDC becomes attractive when applications process very large numbers of events or require lower publishing latency.</p>

<hr />

<h3 id="real-world-examples">Real-World Examples</h3>

<p>The Outbox Pattern appears in many more places than developers often realize. Once you begin recognizing the Dual-Write Problem, you start seeing it almost everywhere.</p>

<h4 id="e-commerce">E-Commerce</h4>

<p>A customer places an order. The transaction creates the order, updates inventory, and inserts an <strong>OrderCreated</strong> event into the outbox. Later, the publisher delivers that event to Kafka, and other services respond independently:</p>

<ul>
  <li>Shipping prepares the package.</li>
  <li>Email sends the confirmation.</li>
  <li>Analytics records the sale.</li>
  <li>Loyalty awards points.</li>
</ul>

<p>Every service receives exactly the same event without the original request needing to coordinate them.</p>

<hr />

<h4 id="loan-management-systems">Loan Management Systems</h4>

<p>Suppose a borrower makes a repayment. Inside a transaction, the application updates the loan balance, records the payment, recalculates outstanding interest, and inserts a <strong>LoanRepaymentReceived</strong> event into the outbox. Once published, other systems can react independently. The accounting service posts journal entries, the notification service sends an SMS receipt, reporting dashboards update repayment statistics, and credit scoring services refresh customer profiles. The repayment itself remains fast because none of these downstream systems participate in the original transaction.</p>

<hr />

<h4 id="user-registration">User Registration</h4>

<p>A customer creates a new account. The application stores the user’s information and writes a <strong>UserRegistered</strong> event into the outbox. Later, other services consume the event. An email service sends a welcome message, a CRM platform creates a customer profile, a marketing system subscribes the user to onboarding campaigns, and a recommendation engine begins generating personalized suggestions. The registration endpoint doesn’t need to know anything about those systems; its only responsibility is recording that the registration occurred.</p>

<hr />

<h4 id="payment-processing">Payment Processing</h4>

<p>Imagine a payment gateway confirms a successful transaction. The payment service updates account balances, records the payment, and inserts a <strong>PaymentCompleted</strong> event. Even if Kafka becomes unavailable immediately afterward, the payment itself isn’t lost. Once messaging resumes, the event is delivered and downstream systems continue exactly where they left off.</p>

<hr />

<h3 id="benefits-of-the-outbox-pattern">Benefits of the Outbox Pattern</h3>

<p>One of the reasons the Outbox Pattern has become so widely adopted is that it solves several problems simultaneously. First, it provides <strong>reliability</strong>. Once an event has been written into the outbox, it becomes durable. Temporary network failures, message broker outages, or application crashes no longer result in permanently lost events. Second, it simplifies application code. Rather than forcing every request to coordinate database updates and message publication, the request focuses exclusively on committing business data, and event publication becomes the responsibility of a dedicated background process. Third, it improves scalability. Because event publication happens asynchronously, user requests complete more quickly, and slow downstream systems no longer delay the original transaction. Finally, it naturally embraces <strong>eventual consistency</strong>. Instead of requiring every service to update simultaneously, the system guarantees that every interested service will eventually receive the event once communication becomes available.</p>

<hr />

<h3 id="common-mistakes">Common Mistakes</h3>

<p>Like every architectural pattern, the Outbox Pattern can be implemented incorrectly.</p>

<p>One common mistake is assuming that publishing an event means the work is finished. Publishing only guarantees that the message reached the broker. Consumers may still fail, messages may still be retried, and downstream services must therefore remain resilient and, where appropriate, idempotent.</p>

<p>Another common mistake is forgetting to clean up the outbox table. If events remain forever, the table will continue growing until queries become unnecessarily expensive. Most production systems archive or remove published events after an appropriate retention period.</p>

<p>Developers also sometimes attempt to perform expensive business logic inside the publisher. The publisher should remain intentionally simple. Its responsibility is publishing events, not recalculating business rules or modifying application state.</p>

<p>Finally, don’t assume every database change requires an event. Publishing unnecessary events creates noise, increases infrastructure costs, and makes systems more difficult to understand. Good events represent meaningful business occurrences, not individual SQL statements.</p>

<hr />

<h3 id="outbox-pattern-vs-distributed-transactions">Outbox Pattern vs Distributed Transactions</h3>

<p>At first glance, the Outbox Pattern and distributed transactions appear to solve the same problem. Both attempt to coordinate work across multiple systems, but the difference lies in how they approach consistency. Distributed transactions attempt to make every participating system commit or roll back together. The Outbox Pattern accepts that this is often impractical in distributed architectures. Instead, it commits business data first and guarantees that events will eventually be delivered. This approach sacrifices immediate consistency in exchange for simplicity, resilience, and availability. For modern cloud-native applications, that trade-off is often the better engineering decision.</p>

<hr />

<h3 id="outbox-pattern-vs-event-sourcing">Outbox Pattern vs Event Sourcing</h3>

<p>The Outbox Pattern is also frequently confused with Event Sourcing. Although both involve events, they solve entirely different problems. With the Outbox Pattern, the database remains the primary source of truth, and events simply communicate that something has happened. With Event Sourcing, events <strong>are</strong> the source of truth. Instead of storing the current state of an order or account, the system stores every event that led to its current state, and the application reconstructs state by replaying those events.</p>

<p>An outbox event might say:</p>

<blockquote>
  <p>Order Created.</p>
</blockquote>

<p>An event-sourced system would permanently record every event throughout the order’s lifetime:</p>

<ul>
  <li>Order Created</li>
  <li>Payment Authorized</li>
  <li>Inventory Reserved</li>
  <li>Shipment Prepared</li>
  <li>Order Delivered</li>
</ul>

<p>Both patterns involve events, but only Event Sourcing uses them to reconstruct application state.</p>

<hr />

<h3 id="best-practices">Best Practices</h3>

<p>If you’re considering adopting the Outbox Pattern, several practices consistently lead to reliable implementations.</p>

<p>Keep the outbox in the same database as your business data so that both participate in the same transaction.</p>

<p>Design your publisher to be idempotent wherever possible. Network failures and retries are inevitable, and duplicate publication attempts should never produce incorrect results.</p>

<p>Monitor the outbox table. A growing backlog of unpublished events is often the earliest warning sign that something is wrong with your messaging infrastructure.</p>

<p>Treat event schemas as part of your public contract. Once other services depend on them, changing them carelessly becomes just as risky as changing a public API.</p>

<p>Finally, remember that publishing an event doesn’t guarantee it has been processed. Downstream services should always be designed to handle retries, duplicates, and temporary failures gracefully.</p>

<hr />

<h3 id="bringing-it-all-together">Bringing It All Together</h3>

<p>At this point in the series, we’ve explored several techniques for building reliable software systems. Each one addresses a different question.</p>

<table>
  <thead>
    <tr>
      <th>Concept</th>
      <th>Question It Answers</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>Idempotency</strong></td>
      <td>What if the same request is sent twice?</td>
    </tr>
    <tr>
      <td><strong>Race Conditions</strong></td>
      <td>What if multiple requests modify the same data simultaneously?</td>
    </tr>
    <tr>
      <td><strong>Database Transactions</strong></td>
      <td>What if part of my database operation fails?</td>
    </tr>
    <tr>
      <td><strong>Isolation Levels</strong></td>
      <td>What should concurrent transactions be allowed to see?</td>
    </tr>
    <tr>
      <td><strong>Distributed Locks</strong></td>
      <td>How do multiple servers coordinate work?</td>
    </tr>
    <tr>
      <td><strong>Outbox Pattern</strong></td>
      <td>How do I reliably notify other systems after committing data?</td>
    </tr>
  </tbody>
</table>

<p>Notice the progression: the concepts don’t replace one another, they build upon one another. Modern backend systems are reliable precisely because they combine multiple patterns, each solving a different class of failure.</p>

<hr />

<h3 id="final-thoughts">Final Thoughts</h3>

<p>One of the defining characteristics of distributed systems is that communication eventually fails. Networks become unreliable, applications restart, and message brokers experience outages. Trying to eliminate these failures entirely is unrealistic.</p>

<p>The Outbox Pattern embraces this reality by changing the problem. Instead of attempting to guarantee that two independent systems succeed simultaneously, it guarantees that business data is safely committed first and that communication will eventually catch up. This seemingly small architectural decision dramatically improves reliability because it removes timing from the equation. Your application no longer depends on Kafka, RabbitMQ, or another messaging system being available at the exact moment a customer submits a request. Instead, it relies on something your database already does exceptionally well: storing data reliably.</p>

<p>The next time you find yourself writing code that updates a database and immediately publishes an event, pause for a moment and ask yourself:</p>

<blockquote>
  <p><strong>“What happens if my database succeeds but my message broker doesn’t?”</strong></p>
</blockquote>

<p>If the answer is “my systems become inconsistent,” you’ve probably found a place where the Outbox Pattern belongs.</p>

<hr />

<h3 id="whats-next">What’s Next?</h3>

<p>So far in this series, we’ve focused on making individual operations reliable. But what happens when a single business process spans <strong>multiple microservices</strong>, each with its own database and transaction?</p>

<p>Imagine placing an order that requires the payment service, inventory service, shipping service, and notification service to all complete successfully. What happens if one of those services fails halfway through?</p>

<p>In the next article, we’ll explore the <strong>Saga Pattern</strong>, one of the most widely used approaches for coordinating long-running business transactions across distributed systems.</p>

]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="Distributed Systems" />
    
    <category term="Concurrency" />
    
  

  
    
    <category term="Distributed Systems" />
    
    <category term="Concurrency" />
    
  

    <summary>The Outbox Pattern is a technique for ensuring that a database update and an event publication either happen together, or are eventually made consistent. This article explains what the Outbox Pattern is, why it is important, and how it works.</summary>

  </entry>

  
  





  



  


  <entry>
    <title>Distributed Locks Explained: Technologies That Implement Distributed Locks</title>
    <link href="https://billyokeyo.dev/posts/distributed-locks-explained-part-2/" rel="alternate" type="text/html" title="Distributed Locks Explained: Technologies That Implement Distributed Locks" />
    <published>2026-07-17T00:00:00+00:00</published>
  
    <updated>2026-07-17T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/distributed-locks-explained-part-2/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/distributed-locks-explained-part-2/"><![CDATA[<p>Now that we understand how distributed locks work conceptually, the next question becomes:</p>

<blockquote>
  <p><strong>Where do these locks actually live?</strong></p>
</blockquote>

<p>Unlike database transactions, distributed locks cannot rely on the memory of a single application server. Remember, our application might be running on five, ten, or even hundreds of machines, and every server must consult the same source of truth before deciding whether it may perform a particular operation.</p>

<p>Over the years, several technologies have emerged to solve this coordination problem. Although they all provide distributed locking capabilities, they were designed with slightly different goals in mind. Let’s look at the most common ones.</p>

<hr />

<h2 id="redis">Redis</h2>

<p>For most web applications, <strong>Redis</strong> is by far the most popular choice. Originally designed as an in-memory data store, Redis is incredibly fast, making it an excellent candidate for lightweight coordination tasks.</p>

<p>Acquiring a lock in Redis is surprisingly straightforward. A server attempts to create a key using an atomic command that says, in effect:</p>

<blockquote>
  <p>“Create this key only if it doesn’t already exist.”</p>
</blockquote>

<p>If Redis successfully creates the key, the server owns the lock; if the key already exists, another server is already performing the work. Because Redis executes this operation atomically, two servers can never successfully create the same lock at the same time.</p>

<p>A simplified example looks like this:</p>

<pre><code class="language-text">SET invoice-generation

Server-A

NX

EX 30
</code></pre>

<p>The command says:</p>

<ul>
  <li>Create the key only if it doesn’t already exist (<code>NX</code>).</li>
  <li>Automatically expire it after thirty seconds (<code>EX 30</code>).</li>
</ul>

<p>In one atomic operation, Redis both acquires the lock and ensures it won’t remain forever if the server crashes. For many applications, this is all that’s needed.</p>

<hr />

<h2 id="why-redis-is-so-popular">Why Redis Is So Popular</h2>

<p>Redis has become the default choice for distributed locks because it satisfies three important requirements. First, it’s extremely fast: since Redis stores data in memory rather than on disk, lock acquisition usually takes only a few milliseconds. Second, many applications already use Redis for caching, sessions, queues, or rate limiting, so adding distributed locking often requires little additional infrastructure. Finally, Redis has mature client libraries for virtually every programming language, with Laravel, Django, Spring Boot, .NET, Node.js, and Go all providing excellent Redis support.</p>

<p>For the vast majority of business applications, Redis offers an excellent balance between simplicity, performance, and reliability.</p>

<hr />

<h2 id="the-challenge-with-a-single-redis-instance">The Challenge with a Single Redis Instance</h2>

<p>Suppose your entire application depends on one Redis server. Everything works perfectly, then Redis crashes. Suddenly, no application server can acquire new locks, and even worse, if Redis loses its in-memory state during a restart, locks may disappear unexpectedly.</p>

<p>This introduces a new challenge: the coordinator itself has become a single point of failure. For many applications, this risk is acceptable. For others, particularly financial systems or globally distributed services, it isn’t. This challenge led to one of the most discussed topics in distributed systems: the <strong>Redlock algorithm</strong>.</p>

<hr />

<h2 id="the-redlock-algorithm">The Redlock Algorithm</h2>

<p>Redlock was proposed by Redis creator <strong>Salvatore Sanfilippo</strong> as a way to make Redis-based distributed locks more resilient. Instead of relying on one Redis server, Redlock uses multiple independent Redis instances.</p>

<p>Imagine five Redis servers.</p>

<pre><code>Redis 1

Redis 2

Redis 3

Redis 4

Redis 5
</code></pre>

<p>When acquiring a lock, the application attempts to obtain it from all five servers, and the lock is considered successful only if a majority agree.</p>

<p>For example:</p>

<pre><code>Acquire Lock

↓

Redis 1 ✅

Redis 2 ✅

Redis 3 ✅

Redis 4 ❌

Redis 5 ❌
</code></pre>

<p>Three out of five succeeded, so the application proceeds. If only two servers grant the lock, the operation fails because a majority wasn’t reached. This approach significantly reduces the impact of individual Redis failures.</p>

<p>However, Redlock is also one of the most debated algorithms in distributed systems. Some engineers argue that it’s sufficient for many practical systems, while others, including Martin Kleppmann, have published detailed critiques explaining situations where Redlock may not provide the guarantees developers expect. The important lesson isn’t that Redlock is good or bad; it’s that distributed systems involve trade-offs, and understanding those trade-offs matters more than memorizing algorithms.</p>

<hr />

<h2 id="zookeeper">ZooKeeper</h2>

<p>Long before Redis became popular for distributed locking, many large distributed systems relied on <strong>Apache ZooKeeper</strong>. ZooKeeper was designed specifically for coordination. Rather than functioning as a cache, it provides services such as:</p>

<ul>
  <li>Distributed locks</li>
  <li>Leader election</li>
  <li>Configuration management</li>
  <li>Service discovery</li>
</ul>

<p>Think of ZooKeeper as a highly reliable coordinator for distributed applications. Its primary goal isn’t speed, it’s correctness. Large systems such as Apache Kafka, Hadoop, and HBase have historically relied on ZooKeeper to coordinate clusters of machines. If your application requires complex distributed coordination rather than simple locking, ZooKeeper remains an excellent choice.</p>

<hr />

<h2 id="etcd">etcd</h2>

<p>If you’ve worked with Kubernetes, you’ve already encountered <strong>etcd</strong>, even if you didn’t realize it. Every Kubernetes cluster stores its configuration inside etcd. Like ZooKeeper, etcd is a distributed key-value store designed for coordination rather than caching. It provides:</p>

<ul>
  <li>Distributed locks</li>
  <li>Leader election</li>
  <li>Configuration storage</li>
  <li>Consensus</li>
  <li>Service coordination</li>
</ul>

<p>Unlike Redis, etcd prioritizes consistency over raw performance. Its API is also designed around long-lived leases, making lock management particularly elegant. Modern cloud-native applications frequently choose etcd when they already operate within Kubernetes ecosystems.</p>

<hr />

<h2 id="consul">Consul</h2>

<p>HashiCorp <strong>Consul</strong> occupies a similar space. Although many developers know Consul for service discovery, it also provides distributed locking capabilities through sessions. Organizations using Consul often rely on it for:</p>

<ul>
  <li>Service registration</li>
  <li>Health checks</li>
  <li>Distributed configuration</li>
  <li>Leader election</li>
  <li>Distributed locks</li>
</ul>

<p>Like ZooKeeper and etcd, Consul focuses on reliable coordination across distributed infrastructure.</p>

<hr />

<h2 id="which-technology-should-you-choose">Which Technology Should You Choose?</h2>

<p>There isn’t a universal answer. Instead, the right choice depends on your application’s requirements. If you’re building a typical web application that already uses Redis, implementing distributed locks with Redis is usually the simplest and most practical solution. If you’re coordinating hundreds of services across a Kubernetes cluster, etcd may integrate more naturally with your infrastructure. If your organization already uses Consul or ZooKeeper for service coordination, leveraging those existing systems often makes more sense than introducing Redis solely for locking.</p>

<p>Choosing a technology isn’t just about features. It’s also about operational complexity, existing infrastructure, and the guarantees your business requires. The important thing to remember is this: distributed locks are a concept, while Redis, ZooKeeper, etcd, and Consul are simply different tools for implementing that concept. Understanding the underlying idea is far more valuable than becoming attached to a specific technology.</p>

<hr />

<h2 id="do-you-always-need-a-distributed-lock">Do You Always Need a Distributed Lock?</h2>

<p>Reading this article, it might be tempting to conclude that distributed locks are the solution to every concurrency problem. They’re not. In fact, many applications never need them. If your application runs on a single server, ordinary in-memory locks are often sufficient, and if your database transaction already guarantees correctness, introducing a distributed lock may simply add unnecessary complexity.</p>

<p>Distributed locks are powerful, but they should be introduced only when multiple independent application instances genuinely need to coordinate shared work. Like every distributed systems technique, they solve a very specific class of problems, and the best engineering decision is often knowing when <strong>not</strong> to use them.</p>

<h2 id="common-mistakes-when-using-distributed-locks">Common Mistakes When Using Distributed Locks</h2>

<p>Like many distributed systems concepts, distributed locks appear deceptively simple: acquire a lock, perform some work, release the lock. In practice, however, there are several subtle mistakes that can introduce bugs that are even harder to diagnose than the problem the lock was intended to solve. Understanding these pitfalls is just as important as understanding distributed locks themselves.</p>

<hr />

<h3 id="assuming-a-lock-lasts-forever">Assuming a Lock Lasts Forever</h3>

<p>One of the most common mistakes is forgetting that distributed locks usually have an expiration time. Suppose a server acquires a lock with a TTL of thirty seconds, and the developer assumes the operation will always finish within that window. Months later, a new feature makes the operation take forty-five seconds. The lock expires while the first server is still working, another server acquires the same lock and begins executing the exact same task, and suddenly, duplicate work appears again.</p>

<p>Choosing an appropriate TTL, and renewing it for long-running tasks when necessary, is essential.</p>

<hr />

<h3 id="forgetting-to-release-the-lock">Forgetting to Release the Lock</h3>

<p>Although expiration protects against permanent deadlocks, applications should still release locks as soon as the protected work finishes. Holding a lock longer than necessary reduces concurrency and delays other servers waiting to perform legitimate work.</p>

<p>A good rule is simple:</p>

<blockquote>
  <p>Hold the lock only for the work that genuinely requires exclusive access.</p>
</blockquote>

<p>Everything else should happen outside the lock whenever possible.</p>

<hr />

<h3 id="protecting-too-much-code">Protecting Too Much Code</h3>

<p>Developers sometimes wrap entire workflows inside a distributed lock. For example:</p>

<pre><code class="language-text">Acquire Lock

↓

Call External Payment API

↓

Generate PDF

↓

Upload File

↓

Send Email

↓

Release Lock
</code></pre>

<p>This means every other server waits while network requests, file generation, and email delivery are taking place. Often, only a small portion of the workflow actually requires exclusive access. A better approach is to keep the critical section as short as possible.</p>

<pre><code class="language-text">Acquire Lock

↓

Update Shared Resource

↓

Release Lock

↓

Generate PDF

↓

Send Email
</code></pre>

<p>The shorter the lock, the better the system scales.</p>

<hr />

<h2 id="distributed-locks-vs-database-locks">Distributed Locks vs Database Locks</h2>

<p>At first glance, distributed locks and database locks appear very similar. Both prevent concurrent operations and both coordinate access to shared resources, but they operate at completely different levels.</p>

<p>A database lock protects <strong>data inside the database</strong>. For example, when two transactions attempt to update the same customer record, the database can lock that row until one transaction completes. Everything happens within the database engine itself.</p>

<p>A distributed lock protects <strong>work performed by application servers</strong>. Instead of preventing two transactions from updating the same row, it prevents two application instances from starting the same business process. Consider generating monthly invoices: before any invoice rows even exist in the database, every server must first decide whether it should begin the job. That decision happens outside the database, and a distributed lock coordinates that decision.</p>

<p>An easy way to remember the difference is:</p>

<blockquote>
  <p><strong>Database locks protect data. Distributed locks protect business operations.</strong></p>
</blockquote>

<p>In many systems, you’ll use both together. A distributed lock ensures only one server begins generating invoices, and database transactions then ensure every invoice is written consistently.</p>

<hr />

<h2 id="distributed-locks-vs-optimistic-concurrency">Distributed Locks vs Optimistic Concurrency</h2>

<p>Another concept frequently confused with distributed locks is optimistic concurrency. Optimistic concurrency assumes conflicts are relatively rare. Instead of preventing multiple users from editing the same record, it detects whether someone else changed the data before saving.</p>

<p>Suppose two employees open the same customer profile, and each begins editing. The system stores a version number alongside the record. When Employee A saves, the version changes from <strong>5</strong> to <strong>6</strong>. When Employee B later attempts to save, the application notices that the version has already changed. Rather than silently overwriting Employee A’s work, it rejects the update and asks Employee B to refresh the page. No locking was required; the conflict was simply detected before committing.</p>

<p>Distributed locks take a different approach. Instead of detecting conflicts afterward, they prevent conflicting work from starting in the first place. Neither technique is universally better: optimistic concurrency works well when conflicts are uncommon, while distributed locks work best when duplicate execution would be expensive or dangerous.</p>

<hr />

<h2 id="best-practices">Best Practices</h2>

<p>As with most distributed systems techniques, simplicity is your friend. If you’re considering introducing distributed locks into your application, the following guidelines will help you avoid many common problems.</p>

<h4 id="keep-critical-sections-small">Keep Critical Sections Small</h4>

<p>Acquire the lock immediately before modifying shared resources, and release it immediately afterward. The less work performed while holding the lock, the better your system scales.</p>

<hr />

<h4 id="always-use-lock-expiration">Always Use Lock Expiration</h4>

<p>Servers crash, containers restart, and networks fail. Never assume your application will always release its lock correctly. Expiration protects the rest of the system from waiting forever.</p>

<hr />

<h4 id="verify-lock-ownership">Verify Lock Ownership</h4>

<p>Before releasing a lock, ensure your application still owns it. Ownership checks prevent one server from accidentally deleting another server’s lock after an expiration or retry.</p>

<hr />

<h4 id="design-for-failure">Design for Failure</h4>

<p>Distributed systems should always assume that something will eventually fail. Ask yourself:</p>

<ul>
  <li>What happens if Redis becomes unavailable?</li>
  <li>What happens if the server crashes?</li>
  <li>What happens if the network partitions?</li>
  <li>What happens if the lock expires unexpectedly?</li>
</ul>

<p>Thinking through failure scenarios early often prevents painful production incidents later.</p>

<hr />

<h4 id="combine-reliability-patterns">Combine Reliability Patterns</h4>

<p>Distributed locks are rarely used in isolation. Production systems often combine multiple reliability techniques. For example:</p>

<ul>
  <li><strong>Idempotency</strong> prevents duplicate requests.</li>
  <li><strong>Transactions</strong> guarantee atomic database updates.</li>
  <li><strong>Isolation Levels</strong> provide predictable views of data.</li>
  <li><strong>Distributed Locks</strong> coordinate multiple application servers.</li>
</ul>

<p>Each technique solves a different problem. Together, they create systems that continue behaving correctly even under heavy load and unexpected failures.</p>

<hr />

<h2 id="bringing-it-all-together">Bringing It All Together</h2>

<p>At this point in the series, we’ve explored several concepts that all contribute to building reliable backend systems. Each one addresses a different question.</p>

<table>
  <thead>
    <tr>
      <th>Concept</th>
      <th>Question It Answers</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>Idempotency</strong></td>
      <td>What if the same request is sent twice?</td>
    </tr>
    <tr>
      <td><strong>Race Conditions</strong></td>
      <td>What if multiple requests modify the same data simultaneously?</td>
    </tr>
    <tr>
      <td><strong>Database Transactions</strong></td>
      <td>What if part of my operation fails?</td>
    </tr>
    <tr>
      <td><strong>Isolation Levels</strong></td>
      <td>What should transactions be allowed to see while others are running?</td>
    </tr>
    <tr>
      <td><strong>Distributed Locks</strong></td>
      <td>How do multiple servers agree who should perform a task?</td>
    </tr>
  </tbody>
</table>

<p>Notice how these concepts complement one another. None replaces the others; reliable systems are built by combining the right tools for the right problems.</p>

<hr />

<h2 id="final-thoughts">Final Thoughts</h2>

<p>As applications grow, the biggest challenges often aren’t writing business logic. They’re coordinating work across multiple users, multiple requests, multiple transactions, and eventually multiple servers.</p>

<p>Distributed locks exist because modern applications are no longer confined to a single machine. They’re deployed across clusters, containers, cloud regions, and worker nodes that all need to cooperate without constantly stepping on each other’s toes.</p>

<p>Like transactions and isolation levels, distributed locks aren’t something you’ll use for every feature. But when you do need them, they can be the difference between a system that behaves predictably and one that quietly creates duplicate invoices, repeated payments, or inconsistent business data.</p>

<p>The next time you design a background job, scheduled task, or critical workflow, ask yourself one simple question:</p>

<blockquote>
  <p><strong>“What happens if two servers try to do this at exactly the same time?”</strong></p>
</blockquote>

<p>If the answer is “something bad,” you’ve probably found a place where a distributed lock belongs.</p>

<hr />

<h2 id="whats-next">What’s Next?</h2>

<p>We’ve now covered:</p>

<ul>
  <li>Contract Testing</li>
  <li>Idempotency</li>
  <li>Race Conditions</li>
  <li>Database Transactions</li>
  <li>Database Concurrency</li>
  <li>Database Isolation Levels</li>
  <li>Distributed Locks</li>
</ul>

<p>So far, every concept has focused on keeping operations consistent <strong>while they’re happening</strong>. But there’s another challenge waiting. Imagine you’ve successfully updated your database inside a transaction and now need to publish an event to Kafka, RabbitMQ, or another message broker. What happens if the database commit succeeds, but publishing the event fails? Or worse, what if the event is published but the transaction rolls back?</p>

<p>This problem has caused countless production incidents in distributed systems. In the next article, we’ll explore <strong>The Outbox Pattern Explained: Publishing Events Without Losing Data</strong>, one of the most widely used patterns for ensuring your database and message broker stay in sync.</p>
]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="Distributed Systems" />
    
    <category term="Concurrency" />
    
  

  
    
    <category term="Distributed Systems" />
    
    <category term="Concurrency" />
    
  

    <summary>Distributed locks are a coordination mechanism that allows multiple independent servers to agree that only one of them may perform a particular operation at a given time. This article explains what distributed locks are, why they are important, and how they work.</summary>

  </entry>

  
  





  



  


  <entry>
    <title>Distributed Locks Explained: Coordinating Work Across Multiple Servers</title>
    <link href="https://billyokeyo.dev/posts/distributed-locks-explained/" rel="alternate" type="text/html" title="Distributed Locks Explained: Coordinating Work Across Multiple Servers" />
    <published>2026-07-13T00:00:00+00:00</published>
  
    <updated>2026-07-13T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/distributed-locks-explained/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/distributed-locks-explained/"><![CDATA[<blockquote>
  <p><em>“Database locks protect rows. Distributed locks protect systems.”</em></p>
</blockquote>

<p>Imagine your application has been wildly successful. What started as a simple web application running on a single server now runs across multiple machines behind a load balancer. Requests are shared between application instances, background workers process jobs independently, and scheduled tasks run on every server.</p>

<p>From the outside, everything looks better than ever: pages load faster, traffic scales effortlessly, and users are happy. Then one morning, your finance department calls. Every customer has received <strong>four monthly invoices</strong>.</p>

<p>Nothing appears wrong with the code. The invoice generation job is scheduled to run once every month, so why did it execute four times? The answer is surprisingly simple: you now have four application servers. At midnight, every server woke up, checked the scheduler, and independently decided that it was responsible for generating invoices. From each server’s perspective, everything was perfectly correct; collectively, however, they created a costly mistake.</p>

<p>Now imagine a different scenario. Your payment gateway sends a webhook confirming a successful payment. The webhook is delivered to one of your load-balanced servers, but a retry occurs because the payment provider doesn’t receive a response quickly enough, so another server processes the same webhook. Both servers begin updating balances, both create accounting entries, and both generate receipts.</p>

<p>You’ve already learned how <strong>idempotency</strong> protects against duplicate requests and how <strong>transactions</strong> ensure database operations succeed together.</p>

<p>But neither of those concepts answers a new question:</p>

<blockquote>
  <p><strong>How do multiple application servers agree that only one of them should perform a particular piece of work?</strong></p>
</blockquote>

<p>That problem is solved by <strong>distributed locks</strong>.</p>

<p>As applications grow beyond a single server, distributed locks become one of the most important coordination mechanisms in modern software engineering.</p>

<hr />

<h2 id="why-database-locks-are-no-longer-enough">Why Database Locks Are No Longer Enough</h2>

<p>Earlier in this series, we explored database transactions and row-level locking.</p>

<p>Suppose two transactions attempt to update the same bank account.</p>

<p>Using a statement such as:</p>

<pre><code class="language-sql">SELECT *
FROM accounts
WHERE id = 1
FOR UPDATE;
</code></pre>

<p>the database ensures only one transaction can modify that row at a time.</p>

<p>This works beautifully because both transactions are coordinating through the same database.</p>

<p>Now consider a different problem.</p>

<p>Suppose you have four application servers running the exact same code, and each server has a scheduler responsible for calculating monthly loan interest. Midnight arrives, and every server starts the same scheduled job. None of them are updating the same database row immediately. Instead, they’re deciding whether to begin an entire business process. The database has nothing to lock yet, and by the time one server begins writing data, the others have already started processing. The result is duplicated work.</p>

<p>Database locks are excellent at protecting individual records, but they are not designed to coordinate entire applications spread across multiple machines. This is the gap distributed locks were created to fill.</p>

<hr />

<h2 id="what-is-a-distributed-lock">What Is a Distributed Lock?</h2>

<p>A distributed lock is a coordination mechanism that allows multiple independent servers to agree that <strong>only one of them</strong> may perform a particular operation at a given time. Instead of protecting a single database row, a distributed lock protects an entire business activity.</p>

<p>Imagine a conference room with a single key. Anyone can use the room, but only the person holding the key may enter, and everyone else must wait until the key is returned. A distributed lock works in much the same way: before performing an operation, a server first attempts to acquire the lock. If the lock is available, the server proceeds; if another server already owns the lock, the operation waits, retries, or exits.</p>

<p>The important point is that <strong>every server asks the same central authority for permission before beginning work.</strong> That authority might be Redis, ZooKeeper, etcd, or another distributed coordination system.</p>

<hr />

<h2 id="a-simple-example">A Simple Example</h2>

<p>Imagine four application servers.</p>

<pre><code class="language-text">        Load Balancer
              │
   ┌──────────┼──────────┐
   │          │          │
Server A   Server B   Server C
   │          │          │
        Server D
</code></pre>

<p>At midnight, each server checks whether it’s time to generate invoices.</p>

<p>Without a distributed lock:</p>

<pre><code class="language-text">Server A → Generate invoices ✅

Server B → Generate invoices ✅

Server C → Generate invoices ✅

Server D → Generate invoices ✅
</code></pre>

<p>Four executions, four invoices, and one very unhappy finance department.</p>

<p>With a distributed lock:</p>

<pre><code class="language-text">Server A → Acquire Lock ✅

Server B → Lock Exists

Server C → Lock Exists

Server D → Lock Exists
</code></pre>

<p>Only Server A proceeds, and everyone else exits. The invoices are generated exactly once.</p>

<hr />

<h2 id="real-world-examples">Real-World Examples</h2>

<p>Distributed locks appear in far more places than most developers realize. Whenever multiple application instances could accidentally perform the same work, a distributed lock becomes a potential solution.</p>

<h3 id="scheduled-jobs">Scheduled Jobs</h3>

<p>Suppose your loan management platform calculates accrued interest every night at midnight. Without coordination, every application server performs the calculation independently, interest may be applied multiple times, and a distributed lock ensures exactly one server performs the calculation.</p>

<hr />

<h3 id="payment-processing">Payment Processing</h3>

<p>Imagine receiving a payment webhook from M-Pesa. Network retries cause multiple servers to receive the same notification, and without coordination, several servers may attempt to update balances simultaneously. A distributed lock allows only one server to process the payment while the others simply exit.</p>

<hr />

<h3 id="inventory-management">Inventory Management</h3>

<p>Only one laptop remains in stock, and two servers receive purchase requests simultaneously. Each attempts to reserve the item. Although transactions protect database consistency, a distributed lock can coordinate reservation workflows across multiple application instances before they even begin modifying inventory.</p>

<hr />

<h3 id="sending-emails">Sending Emails</h3>

<p>Marketing decides to send a promotional email to one million subscribers, and your email scheduler is deployed across five worker nodes. Without coordination, every worker starts sending the campaign and customers receive the same email five times. With a distributed lock, only one worker initiates the campaign while the others remain idle.</p>

<hr />

<h3 id="report-generation">Report Generation</h3>

<p>Generating annual financial reports may take several minutes. Without coordination, multiple servers might begin generating the exact same report simultaneously, wasting CPU time and increasing database load. A distributed lock ensures only one report generation process is active.</p>

<hr />

<h2 id="when-should-you-consider-a-distributed-lock">When Should You Consider a Distributed Lock?</h2>

<p>A useful rule of thumb is to ask yourself a simple question:</p>

<blockquote>
  <p><strong>What would happen if two servers performed this operation at exactly the same time?</strong></p>
</blockquote>

<p>If the answer is:</p>

<ul>
  <li>Duplicate invoices</li>
  <li>Duplicate payments</li>
  <li>Duplicate notifications</li>
  <li>Duplicate accounting entries</li>
  <li>Duplicate interest calculations</li>
</ul>

<p>then the operation is probably a candidate for a distributed lock.</p>

<p>Not every feature needs one. Most HTTP requests don’t, reading data doesn’t, and serving web pages doesn’t. Distributed locks are primarily useful for <strong>shared background work</strong> and <strong>critical business processes</strong> where duplicate execution would produce incorrect results.</p>

<hr />

<h2 id="distributed-locks-are-about-coordination">Distributed Locks Are About Coordination</h2>

<p>One misconception worth addressing early is that distributed locks replace database transactions.</p>

<p>They don’t. Transactions guarantee consistency <strong>inside the database</strong>; distributed locks coordinate <strong>between application servers</strong>. The two solve different problems.</p>

<p>In practice, many enterprise systems use both together. A server first acquires a distributed lock, then begins a database transaction. When the transaction completes successfully, the server releases the distributed lock. The lock ensures only one server performs the work, and the transaction ensures the database remains consistent while that work is being performed. Together, they provide a powerful foundation for building reliable distributed systems.</p>

<hr />

<p>At this point, we’ve answered <strong>why distributed locks exist</strong>.</p>

<p>The next question is equally important:</p>

<p><strong>How do multiple servers actually agree on who owns the lock?</strong></p>

<h2 id="how-distributed-locks-work">How Distributed Locks Work</h2>

<p>At a high level, every distributed lock follows the same basic workflow.</p>

<p>Before performing a critical operation, an application asks a shared coordination service for permission to proceed. If the lock is available, the application acquires it and begins its work; if another server already owns the lock, the application waits, retries later, or simply exits. Once the work has been completed, the lock is released, allowing another server to acquire it.</p>

<p>Although different technologies implement this process differently, the underlying idea remains remarkably simple.</p>

<pre><code class="language-text">Application Server

        │

Request Lock

        │

───────────────
 Lock Service
───────────────

Lock Available?

   │          │

  Yes         No

   │          │

Acquire      Wait / Retry / Exit

   │

Perform Work

   │

Release Lock
</code></pre>

<p>The important detail is that <strong>every application instance talks to the same lock service</strong>. Without a shared source of truth, each server would simply believe it owned the lock.</p>

<hr />

<h2 id="acquiring-a-lock">Acquiring a Lock</h2>

<p>Imagine four servers attempting to generate monthly invoices.</p>

<p>Each server sends a request to Redis asking for a lock called:</p>

<pre><code class="language-text">invoice-generation
</code></pre>

<p>Redis receives the requests almost simultaneously. The first request succeeds, and Redis stores something similar to:</p>

<pre><code class="language-text">invoice-generation

Owner: Server A

Expires: 30 seconds
</code></pre>

<p>When the remaining servers ask for the same lock, Redis responds that the lock already exists. Only Server A continues. Servers B, C, and D either wait, retry after a short delay, or abandon the operation altogether.</p>

<p>The beauty of distributed locks lies in their simplicity: instead of every server making its own decision, they all trust a single coordinator.</p>

<hr />

<h2 id="holding-the-lock">Holding the Lock</h2>

<p>Once a server has successfully acquired the lock, it proceeds with the protected operation.</p>

<p>This might involve:</p>

<ul>
  <li>Generating invoices.</li>
  <li>Processing a payment.</li>
  <li>Calculating loan interest.</li>
  <li>Sending reminder emails.</li>
  <li>Synchronizing inventory.</li>
</ul>

<p>During this period, every other server attempting the same operation sees that the lock is already owned. Rather than performing duplicate work, those servers simply back off. The lock effectively becomes a reservation saying that someone is already doing this work and others should wait.</p>

<hr />

<h2 id="releasing-the-lock">Releasing the Lock</h2>

<p>When the protected work completes successfully, the server releases the lock.</p>

<pre><code class="language-text">Acquire Lock

↓

Process Work

↓

Release Lock
</code></pre>

<p>Once Redis removes the lock, another server is free to acquire it if necessary. Releasing the lock is just as important as acquiring it. A lock that is never released eventually blocks every future attempt to perform that operation.</p>

<hr />

<h2 id="the-problem-with-permanent-locks">The Problem with Permanent Locks</h2>

<p>Now consider something less pleasant.</p>

<p>Server A acquires the invoice-generation lock, but halfway through generating invoices, the server crashes. Perhaps the machine loses power, perhaps Kubernetes terminates the container, or perhaps someone accidentally restarts the application. The important point is that Server A never gets the opportunity to release its lock.</p>

<p>If the lock remained permanent, every future invoice generation attempt would fail because the system would forever believe Server A still owned the lock. This is one of the biggest differences between traditional application locks and distributed locks: distributed systems must always assume that servers can disappear without warning.</p>

<hr />

<h2 id="lock-expiration-ttl">Lock Expiration (TTL)</h2>

<p>To solve this problem, distributed locks almost always include an expiration time, often called a <strong>Time-To-Live (TTL).</strong></p>

<p>Instead of storing only the lock name, the lock service stores something like:</p>

<pre><code class="language-text">Lock:

invoice-generation

Owner:

Server A

Expires:

30 seconds
</code></pre>

<p>If Server A completes successfully, it releases the lock before those thirty seconds expire. If Server A crashes, Redis automatically deletes the lock after the TTL expires, allowing another server to continue the work instead of waiting forever.</p>

<p>Think of it like borrowing a meeting room: rather than reserving it indefinitely, your booking automatically expires after one hour. If you forget to leave, the reservation eventually disappears and someone else can use the room. TTL prevents abandoned locks from permanently blocking the system.</p>

<hr />

<h2 id="choosing-the-right-ttl">Choosing the Right TTL</h2>

<p>Choosing a lock duration isn’t as straightforward as it might seem.</p>

<p>Suppose generating invoices normally takes ten seconds, and a thirty-second TTL provides plenty of room for occasional delays. But what if one month the process unexpectedly takes forty-five seconds? The lock expires after thirty seconds, another server acquires it, and now both servers are generating invoices simultaneously. You’ve accidentally recreated the very problem the lock was supposed to prevent.</p>

<p>On the other hand, choosing an extremely long TTL isn’t ideal either. If a server crashes while holding a lock that expires after thirty minutes, every other server must wait half an hour before continuing. Finding the right TTL therefore requires understanding how long your operation normally takes, while leaving enough room for occasional delays.</p>

<p>Some distributed lock implementations even allow servers to periodically renew the TTL while they’re still actively working. This approach, often called a <strong>heartbeat</strong>, keeps long-running operations alive without requiring excessively long expiration times.</p>

<hr />

<h2 id="what-happens-if-two-servers-ask-at-the-same-time">What Happens If Two Servers Ask at the Same Time?</h2>

<p>One question naturally arises: what happens if two servers request the lock at exactly the same millisecond? The answer depends on the lock service.</p>

<p>Redis, ZooKeeper, etcd, and similar systems perform lock acquisition atomically. That means checking whether the lock exists and creating it happen as a single indivisible operation. There is never a moment when both servers successfully acquire the same lock: one request succeeds and the other fails. This atomicity is exactly what makes distributed locks reliable; without it, two servers could both believe they owned the lock, defeating the entire purpose.</p>

<hr />

<h2 id="lock-ownership-matters">Lock Ownership Matters</h2>

<p>Imagine Server A acquires a lock. Before finishing its work, the lock expires because the TTL was too short, and Server B now acquires the same lock. Moments later, Server A finally finishes and attempts to release it. If the lock service simply deleted the lock without checking ownership, Server A would accidentally remove Server B’s lock, Server C could now acquire it, and suddenly two servers are working simultaneously again.</p>

<p>To prevent this, distributed lock implementations associate every lock with a unique owner identifier. When releasing a lock, the application must prove that it is still the owner; if ownership has already changed, the release request is ignored. This simple verification prevents one server from accidentally deleting another server’s lock.</p>

<hr />

<h2 id="distributed-locks-arent-magic">Distributed Locks Aren’t Magic</h2>

<p>It’s important to understand that distributed locks don’t eliminate failures. Servers can still crash, networks can still become partitioned, and Redis instances can still fail. Distributed locks simply provide a coordinated way for multiple application instances to make decisions despite those realities. They reduce duplicate work, improve consistency, and coordinate critical business operations, but like every distributed systems technique, they must be implemented carefully and combined with other reliability mechanisms such as transactions, retries, idempotency, and monitoring.</p>

<p>In the next section, we’ll explore the most common technologies used to implement distributed locks, including <strong>Redis</strong>, <strong>Redlock</strong>, <strong>ZooKeeper</strong>, <strong>etcd</strong>, and <strong>Consul</strong>, along with the strengths and weaknesses of each approach.</p>

]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="Distributed Systems" />
    
    <category term="Concurrency" />
    
  

  
    
    <category term="Distributed Systems" />
    
    <category term="Concurrency" />
    
    <category term="Database" />
    
  

    <summary>Distributed locks are a coordination mechanism that allows multiple independent servers to agree that only one of them may perform a particular operation at a given time. This article explains what distributed locks are, why they are important, and how they work.</summary>

  </entry>

  
  





  



  


  <entry>
    <title>Database Isolation Levels Explained: Choosing the Right Consistency Guarantees</title>
    <link href="https://billyokeyo.dev/posts/database-isolation-levels-part-2/" rel="alternate" type="text/html" title="Database Isolation Levels Explained: Choosing the Right Consistency Guarantees" />
    <published>2026-07-10T00:00:00+00:00</published>
  
    <updated>2026-07-10T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/database-isolation-levels-part-2/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/database-isolation-levels-part-2/"><![CDATA[<h1 id="understanding-the-four-sql-isolation-levels">Understanding the Four SQL Isolation Levels</h1>

<p>Now that we’ve seen the kinds of problems concurrent transactions can create, the next question is obvious:</p>

<p><strong>How does a database prevent them?</strong></p>

<p>The answer lies in isolation levels.</p>

<p>Rather than enforcing a single set of rules for every application, relational databases allow developers to choose how isolated transactions should be from one another.</p>

<p>This flexibility exists because different applications have different priorities.</p>

<p>A banking application transferring millions of shillings every day values consistency above almost everything else.</p>

<p>A reporting dashboard displaying website traffic may prefer speed over perfect accuracy.</p>

<p>Isolation levels allow the database to balance these competing requirements.</p>

<p>As isolation becomes stronger, transactions observe more consistent data, but the database also has to coordinate more aggressively, often reducing concurrency.</p>

<p>As isolation becomes weaker, transactions execute more freely, improving performance but increasing the likelihood of observing changing data.</p>

<p>The SQL standard defines four isolation levels.</p>

<p>Each one builds upon the guarantees of the previous level.</p>

<hr />

<h2 id="read-uncommitted">Read Uncommitted</h2>

<p>Read Uncommitted is the weakest isolation level defined by the SQL standard.</p>

<p>At this level, transactions are allowed to read changes made by other transactions even if those changes haven’t yet been committed.</p>

<p>Returning to our banking example, imagine Alice begins transferring <strong>KES 20,000</strong> to another account.</p>

<p>The database deducts the money from her balance but hasn’t yet committed the transaction.</p>

<p>Another transaction immediately reads Alice’s account.</p>

<p>Instead of seeing <strong>KES 50,000</strong>, it now sees <strong>KES 30,000</strong>, even though the transfer could still fail and be rolled back.</p>

<p>That second transaction has just performed a dirty read.</p>

<p>The advantage of Read Uncommitted is that transactions almost never wait for one another.</p>

<p>Because the database performs very little coordination, throughput can be extremely high.</p>

<p>The downside is that applications may make decisions using data that never officially existed.</p>

<p>For most business applications, this is unacceptable.</p>

<p>Imagine calculating payroll using salaries that are eventually rolled back or approving a loan based on a balance that disappears moments later.</p>

<p>Fortunately, very few modern relational databases actually encourage Read Uncommitted.</p>

<p>Many databases either discourage it entirely or internally behave more conservatively even when it’s requested.</p>

<p>In practice, you’ll rarely choose this isolation level for production systems.</p>

<hr />

<h2 id="read-committed">Read Committed</h2>

<p>Read Committed is the default isolation level in databases such as PostgreSQL, Oracle, and SQL Server.</p>

<p>Instead of allowing transactions to read uncommitted changes, the database only exposes data that has already been committed.</p>

<p>This immediately eliminates dirty reads.</p>

<p>Returning to Alice’s transfer, suppose another transaction checks her balance while the transfer is still running.</p>

<p>Instead of seeing the temporary balance of <strong>KES 30,000</strong>, it continues seeing the previously committed balance of <strong>KES 50,000</strong> until the transfer completes.</p>

<p>Only after the transaction commits does the new balance become visible.</p>

<p>This makes Read Committed an excellent general-purpose isolation level.</p>

<p>Applications never observe incomplete work, while the database still allows a high degree of concurrency.</p>

<p>However, Read Committed doesn’t solve every problem.</p>

<p>Suppose your transaction reads Alice’s balance at the beginning of a report.</p>

<p>A few seconds later, another transaction deposits <strong>KES 100,000</strong> into the account and commits.</p>

<p>If your report queries the balance again before finishing, you’ll now see a different value.</p>

<p>The same row has changed during your transaction.</p>

<p>Read Committed prevents dirty reads, but it still allows non-repeatable reads and phantom reads.</p>

<p>For many applications, that’s a perfectly acceptable trade-off.</p>

<hr />

<h2 id="read-committed-timeline">Read Committed Timeline</h2>

<pre><code class="language-text">Transaction A                     Transaction B

BEGIN

Read Balance = 50,000

                               BEGIN

                               Deposit 100,000

                               COMMIT

Read Balance = 150,000

COMMIT
</code></pre>

<p>Both values are valid.</p>

<p>The important difference is that Transaction A never sees incomplete or rolled-back data.</p>

<p>It only observes committed changes.</p>

<hr />

<h2 id="repeatable-read">Repeatable Read</h2>

<p>Suppose you’re generating an end-of-day financial report.</p>

<p>Your transaction calculates the total account balance across thousands of customers.</p>

<p>Halfway through generating the report, another transaction updates several account balances.</p>

<p>If your report re-reads those accounts later, the totals may no longer match the values used earlier in the report.</p>

<p>This is exactly the situation Repeatable Read was designed to solve.</p>

<p>At this isolation level, once a transaction reads a row, subsequent reads of that same row always return the same version for the lifetime of the transaction.</p>

<p>Even if another transaction updates the row and commits, your transaction continues working with the original version.</p>

<p>It’s as though your transaction receives its own private snapshot of the database.</p>

<p>This provides a much more consistent view of the data, making it particularly useful for reporting systems and financial calculations.</p>

<p>However, Repeatable Read doesn’t necessarily prevent new rows from appearing that satisfy your query conditions.</p>

<p>Depending on the database implementation, phantom reads may still occur, although databases like PostgreSQL use <strong>Multi-Version Concurrency Control (MVCC)</strong> to eliminate many of these anomalies without locking every row.</p>

<p>This is one of the reasons database behavior differs slightly across vendors.</p>

<p>We’ll return to that shortly.</p>

<hr />

<h2 id="repeatable-read-timeline">Repeatable Read Timeline</h2>

<pre><code class="language-text">Transaction A                     Transaction B

BEGIN

Read Balance = 50,000

                               BEGIN

                               Deposit 100,000

                               COMMIT

Read Balance = 50,000 ✅

COMMIT
</code></pre>

<p>Although the database now contains <strong>KES 150,000</strong>, Transaction A continues seeing <strong>KES 50,000</strong> because it is working from a consistent snapshot.</p>

<hr />

<h2 id="serializable">Serializable</h2>

<p>Serializable is the strongest isolation level defined by the SQL standard.</p>

<p>The easiest way to understand it is to imagine that every transaction runs one after another instead of simultaneously.</p>

<p>Internally, the database may still execute many transactions concurrently, but it guarantees that the final result is identical to some serial execution order.</p>

<p>Returning to our concert ticket example, suppose only one seat remains.</p>

<p>Customer A begins purchasing the ticket.</p>

<p>Customer B attempts to purchase the same seat at exactly the same time.</p>

<p>Under Serializable isolation, the database ensures that only one transaction succeeds.</p>

<p>The other transaction must either wait, retry, or fail.</p>

<p>The database refuses to produce a result that couldn’t happen if the transactions had executed one after another.</p>

<p>This provides the strongest possible consistency guarantees.</p>

<p>It also comes at the highest performance cost.</p>

<p>Serializable transactions often require additional locking, conflict detection, or transaction retries.</p>

<p>For systems processing large volumes of concurrent requests, this can reduce throughput significantly.</p>

<p>Because of this, Serializable is typically reserved for situations where correctness is absolutely critical.</p>

<p>Financial ledgers, securities trading systems, and certain accounting operations are common examples.</p>

<hr />

<h2 id="isolation-levels-at-a-glance">Isolation Levels at a Glance</h2>

<table>
  <thead>
    <tr>
      <th>Isolation Level</th>
      <th>Dirty Reads</th>
      <th>Non-Repeatable Reads</th>
      <th>Phantom Reads</th>
      <th>Performance</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Read Uncommitted</td>
      <td>❌ Possible</td>
      <td>❌ Possible</td>
      <td>❌ Possible</td>
      <td>⭐⭐⭐⭐⭐</td>
    </tr>
    <tr>
      <td>Read Committed</td>
      <td>✅ Prevented</td>
      <td>❌ Possible</td>
      <td>❌ Possible</td>
      <td>⭐⭐⭐⭐</td>
    </tr>
    <tr>
      <td>Repeatable Read</td>
      <td>✅ Prevented</td>
      <td>✅ Prevented</td>
      <td>⚠ Depends on database</td>
      <td>⭐⭐⭐</td>
    </tr>
    <tr>
      <td>Serializable</td>
      <td>✅ Prevented</td>
      <td>✅ Prevented</td>
      <td>✅ Prevented</td>
      <td>⭐⭐</td>
    </tr>
  </tbody>
</table>

<p>The table makes an important pattern clear.</p>

<p>As isolation increases, the number of concurrency anomalies decreases.</p>

<p>At the same time, the amount of coordination required by the database increases.</p>

<p>This is why there is no universally “best” isolation level.</p>

<p>The appropriate choice always depends on the requirements of your application.</p>

<h2 id="database-isolation-levels-in-popular-databases">Database Isolation Levels in Popular Databases</h2>

<p>One detail that often surprises developers is that not every relational database implements isolation levels in exactly the same way.</p>

<p>The SQL standard defines the four isolation levels, but database vendors have some flexibility in how they achieve those guarantees.</p>

<p>For example, PostgreSQL relies heavily on <strong>Multi-Version Concurrency Control (MVCC)</strong>. Instead of locking rows aggressively, PostgreSQL keeps multiple versions of a row and allows transactions to read a consistent snapshot of the data. This approach provides excellent concurrency while maintaining strong consistency.</p>

<p>MySQL’s InnoDB storage engine also supports MVCC but implements certain isolation behaviors differently. In particular, its default <strong>Repeatable Read</strong> isolation level prevents many phantom reads by using a combination of snapshot reads and gap locks.</p>

<p>SQL Server, on the other hand, traditionally relies more heavily on locking, although it also offers snapshot-based isolation levels that can be enabled when appropriate.</p>

<p>As a developer, you don’t need to memorize every implementation detail.</p>

<p>The important lesson is this:</p>

<blockquote>
  <p><strong>Always understand how your specific database implements isolation before assuming its behavior.</strong></p>
</blockquote>

<p>The SQL standard provides the vocabulary, but your database documentation explains the exact behavior.</p>

<hr />

<h2 id="choosing-the-right-isolation-level">Choosing the Right Isolation Level</h2>

<p>After learning about all four isolation levels, it’s natural to ask:</p>

<p><strong>“Which one should I actually use?”</strong></p>

<p>The honest answer is:</p>

<p><strong>It depends on what you’re building.</strong></p>

<p>Suppose you’re developing a dashboard that displays the number of users currently online.</p>

<p>If the number changes while someone refreshes the page, that’s perfectly acceptable.</p>

<p>There’s little value in sacrificing performance just to ensure every count remains identical throughout a transaction.</p>

<p>Read Committed is usually more than sufficient.</p>

<p>Now consider a payroll system.</p>

<p>Calculating employee salaries requires reading thousands of records while ensuring the figures don’t change halfway through the calculation.</p>

<p>If one employee’s salary is updated while payroll is being processed, the final report could contain inconsistent totals.</p>

<p>Repeatable Read becomes a much better fit because it provides a stable snapshot throughout the transaction.</p>

<p>Finally, imagine a securities trading platform or a banking ledger where even a single inconsistency could have significant financial consequences.</p>

<p>Here, correctness is more important than throughput.</p>

<p>Serializable isolation is often the safest choice, even if it means transactions occasionally wait or retry.</p>

<p>The goal isn’t to choose the strongest isolation level.</p>

<p>The goal is to choose the weakest isolation level that still guarantees the correctness your application requires.</p>

<p>Doing so allows the database to maximize concurrency without sacrificing business integrity.</p>

<hr />

<h2 id="isolation-levels-and-performance">Isolation Levels and Performance</h2>

<p>One mistake developers sometimes make is assuming higher isolation is always better.</p>

<p>In reality, every additional guarantee comes at a cost.</p>

<p>Higher isolation levels typically require the database to:</p>

<ul>
  <li>Coordinate more transactions.</li>
  <li>Acquire additional locks or maintain more snapshots.</li>
  <li>Detect conflicts more aggressively.</li>
  <li>Delay or retry conflicting transactions.</li>
</ul>

<p>As concurrency increases, these costs become more noticeable.</p>

<p>A high-traffic e-commerce platform processing thousands of orders every minute cannot afford unnecessary waiting if a lower isolation level already satisfies its business rules.</p>

<p>Likewise, a financial institution cannot sacrifice correctness simply to process a few extra transactions per second.</p>

<p>Finding the right balance is part of designing reliable software.</p>

<hr />

<h2 id="isolation-levels-vs-transactions-vs-race-conditions">Isolation Levels vs Transactions vs Race Conditions</h2>

<p>At this point in the series, we’ve covered three concepts that are closely related but often confused.</p>

<p>Let’s put them side by side.</p>

<h3 id="transactions">Transactions</h3>

<p>Transactions answer the question:</p>

<blockquote>
  <p><strong>What happens if my operation fails halfway through?</strong></p>
</blockquote>

<p>They ensure a group of related database operations either all succeed together or all fail together.</p>

<p>Without transactions, partial updates can leave your data inconsistent.</p>

<hr />

<h3 id="race-conditions">Race Conditions</h3>

<p>Race conditions answer a different question:</p>

<blockquote>
  <p><strong>What happens if two requests modify the same data at the same time?</strong></p>
</blockquote>

<p>These problems arise because multiple users or systems interact with shared data concurrently.</p>

<p>The outcome often depends entirely on timing.</p>

<p>Transactions alone don’t eliminate race conditions.</p>

<p>Additional mechanisms such as locking, optimistic concurrency, or stronger isolation levels are often required.</p>

<hr />

<h3 id="isolation-levels">Isolation Levels</h3>

<p>Isolation levels answer yet another question:</p>

<blockquote>
  <p><strong>While another transaction is running, what am I allowed to see?</strong></p>
</blockquote>

<p>Should your transaction observe unfinished work?</p>

<p>Should it continue seeing the same data even after another transaction commits?</p>

<p>Should it behave as though it’s the only transaction running?</p>

<p>Isolation levels define these rules.</p>

<p>Together, these three concepts form the foundation of reliable database applications.</p>

<p>They complement one another rather than compete.</p>

<p>A payment system, for example, might use:</p>

<ul>
  <li><strong>Idempotency</strong> to prevent duplicate payment requests.</li>
  <li><strong>Transactions</strong> to ensure payment records and account balances remain synchronized.</li>
  <li><strong>Read Committed</strong> or <strong>Serializable</strong> isolation to guarantee consistent reads.</li>
  <li><strong>Locking</strong> to prevent concurrent modifications of the same account.</li>
</ul>

<p>No single technique solves every reliability problem.</p>

<p>Reliable systems combine several techniques, each addressing a different class of failure.</p>

<hr />

<h2 id="practical-advice-for-backend-developers">Practical Advice for Backend Developers</h2>

<p>If you’re just beginning your backend engineering journey, don’t feel pressured to master every isolation level immediately.</p>

<p>Instead, focus on developing the habit of asking the right questions whenever you design a feature.</p>

<p>For example:</p>

<ul>
  <li>Could another user modify this data while I’m reading it?</li>
  <li>If the same query runs twice, should it return the same result?</li>
  <li>What happens if another transaction inserts new rows before mine finishes?</li>
  <li>Is perfect consistency necessary, or is slightly stale data acceptable?</li>
  <li>Would optimistic concurrency or explicit locking be a better solution?</li>
</ul>

<p>Thinking through these questions early in the design process often prevents bugs that are incredibly difficult to diagnose later in production.</p>

<p>Many concurrency issues aren’t caused by writing incorrect code.</p>

<p>They’re caused by making incorrect assumptions about how multiple users interact with the same data simultaneously.</p>

<hr />

<h2 id="final-thoughts">Final Thoughts</h2>

<p>Database isolation levels are often presented as a collection of definitions that developers are expected to memorize.</p>

<p>In reality, they’re much simpler than they first appear.</p>

<p>They’re simply different answers to one question:</p>

<p><strong>How much should one transaction be allowed to observe while another transaction is still working?</strong></p>

<p>Lower isolation levels prioritize concurrency, allowing more users to interact with the database simultaneously.</p>

<p>Higher isolation levels prioritize consistency, ensuring every transaction sees a predictable view of the data.</p>

<p>Neither approach is universally correct.</p>

<p>The right choice depends entirely on the problem you’re solving.</p>

<p>As your applications grow, understanding isolation levels becomes increasingly important because concurrency is no longer the exception—it’s the norm.</p>

<p>Every online store, banking application, inventory system, booking platform, and loan management system eventually reaches a point where multiple transactions compete for the same data.</p>

<p>The developers who understand isolation levels don’t simply build applications that work.</p>

<p>They build applications that continue working correctly under real-world load.</p>

<hr />

<h2 id="whats-next">What’s Next?</h2>

<p>In this series we’ve explored:</p>

<ul>
  <li>Idempotency</li>
  <li>Race Conditions</li>
  <li>Database Transactions</li>
  <li>Database Isolation Levels</li>
</ul>

<p>We’ve learned how to protect our systems from duplicate requests, concurrent updates, partial failures, and inconsistent reads.</p>

<p>But one challenge still remains.</p>

<p>Everything we’ve discussed assumes our application is running on a single database.</p>

<p>What happens when your application is running on <strong>ten servers</strong>, each processing requests simultaneously?</p>

<p>A normal database lock isn’t always enough.</p>

<p>In the next article, we’ll explore <strong>Distributed Locks Explained: Coordinating Work Across Multiple Servers</strong>, where we’ll see how systems like Redis, ZooKeeper, and etcd help ensure that only one application instance performs a critical operation at a time.</p>

]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="Database" />
    
    <category term="Concurrency" />
    
  

  
    
    <category term="Database" />
    
    <category term="Concurrency" />
    
  

    <summary>Database isolation levels determine what one transaction can see while another transaction is still running. This article explains why isolation levels exist, the four SQL standard isolation levels, and how to choose the right one for your application.</summary>

  </entry>

  
  





  



  


  <entry>
    <title>Database Isolation Levels Explained: Why Two Transactions Can See Different Data</title>
    <link href="https://billyokeyo.dev/posts/database-isolation-levels/" rel="alternate" type="text/html" title="Database Isolation Levels Explained: Why Two Transactions Can See Different Data" />
    <published>2026-07-06T00:00:00+00:00</published>
  
    <updated>2026-07-06T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/database-isolation-levels/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/database-isolation-levels/"><![CDATA[<blockquote>
  <p><em>“Transactions guarantee that your work completes correctly. Isolation levels determine what everyone else is allowed to see while that work is happening.”</em></p>
</blockquote>

<hr />

<p>In the previous article, we explored database transactions and learned how they ensure multiple database operations either succeed together or fail together. Transactions protect applications from partial execution, preventing situations where money is deducted from one account without being deposited into another or where inventory is reduced without successfully creating an order.</p>

<p>But transactions solve only part of the problem.</p>

<p>Modern applications rarely have just one user interacting with the database at a time. Thousands of customers may be placing orders, updating records, making payments, or querying reports simultaneously. Each of these actions runs inside its own transaction, and more often than not, several transactions are accessing the same data at exactly the same time.</p>

<p>This raises an important question:</p>

<p><strong>What should one transaction be allowed to see while another transaction is still running?</strong></p>

<p>Imagine opening your banking application to check your account balance.</p>

<p>At the exact same moment, your employer’s payroll system is depositing your monthly salary into the same account.</p>

<p>Should your transaction see the new balance immediately?</p>

<p>Should it continue seeing the old balance until the salary transaction finishes?</p>

<p>Should it wait until the payroll transaction completes before showing you anything at all?</p>

<p>Each answer is technically valid depending on how the database is configured.</p>

<p>Now imagine an online store where only one laptop remains in stock.</p>

<p>Customer A begins placing an order.</p>

<p>Before their transaction finishes, Customer B checks the product page.</p>

<p>Should Customer B still see one laptop available?</p>

<p>Should they see zero?</p>

<p>Should they wait until Customer A’s purchase either succeeds or fails?</p>

<p>Again, the answer depends on the database’s isolation level.</p>

<p>Isolation levels define the rules governing how concurrent transactions interact with one another. They determine whether one transaction can observe another transaction’s work before it has been completed, whether repeated reads always return the same result, and whether new rows appearing during a transaction should be visible immediately.</p>

<p>Although isolation levels are often introduced as an advanced database topic, they’re really about one simple idea:</p>

<blockquote>
  <p><strong>How much of another transaction’s work should your transaction be allowed to see?</strong></p>
</blockquote>

<p>The answer has significant consequences for both correctness and performance.</p>

<p>In this article, we’ll explore why isolation levels exist, the concurrency problems they solve, the four SQL standard isolation levels, and how to choose the right one for your application.</p>

<hr />

<h1 id="why-isolation-exists">Why Isolation Exists</h1>

<p>To understand isolation, imagine you’re reading a book in a library.</p>

<p>Halfway through chapter three, someone walks over, quietly replaces several pages with new ones, and walks away.</p>

<p>You continue reading without realizing anything changed.</p>

<p>The beginning of the chapter describes one story.</p>

<p>The ending describes another.</p>

<p>Nothing makes sense.</p>

<p>Databases can experience a remarkably similar problem.</p>

<p>When multiple transactions execute simultaneously, each transaction may be reading data while another transaction is actively changing it.</p>

<p>Without rules governing these interactions, applications could make decisions based on incomplete information, outdated values, or data that is eventually discarded.</p>

<p>Isolation exists to prevent these situations.</p>

<p>Rather than allowing every transaction unrestricted access to every change happening in the database, the database controls what each transaction can observe and when it can observe it.</p>

<p>Think of it as putting walls between transactions.</p>

<p>Some walls are very thin.</p>

<p>Transactions can see almost everything happening around them.</p>

<p>Other walls are much thicker.</p>

<p>Transactions operate almost as though they’re the only users of the database.</p>

<p>The thicker the wall, the more isolated the transaction becomes.</p>

<hr />

<h1 id="the-trade-off-between-consistency-and-performance">The Trade-Off Between Consistency and Performance</h1>

<p>At first glance, it might seem obvious that every database should simply use the highest possible isolation level.</p>

<p>After all, if stronger isolation produces more consistent data, why wouldn’t every system choose it?</p>

<p>The answer lies in performance.</p>

<p>Imagine a supermarket with only one checkout counter.</p>

<p>Every customer waits patiently in line.</p>

<p>Because only one cashier is serving customers, inventory updates happen one at a time.</p>

<p>Mistakes are rare.</p>

<p>Unfortunately, the queue becomes enormous.</p>

<p>Now imagine opening ten checkout counters.</p>

<p>Customers move much faster.</p>

<p>However, all ten cashiers are now updating the same inventory system simultaneously.</p>

<p>Keeping everything synchronized becomes much more difficult.</p>

<p>Databases face exactly the same challenge.</p>

<p>Higher isolation levels provide stronger guarantees about data consistency, but they often require additional locking, coordination, and waiting.</p>

<p>Lower isolation levels allow more transactions to execute concurrently, increasing throughput and reducing latency, but they also increase the likelihood that transactions observe changing data.</p>

<p>Isolation levels are therefore a balancing act between two competing goals:</p>

<ul>
  <li><strong>Consistency</strong>, ensuring every transaction sees predictable and reliable data.</li>
  <li><strong>Concurrency</strong>, allowing as many users as possible to interact with the system simultaneously.</li>
</ul>

<p>Different applications make different choices.</p>

<p>A banking application processing financial transfers typically prioritizes correctness over raw performance.</p>

<p>An analytics dashboard generating sales reports might tolerate slightly older data if it means thousands of users can run reports simultaneously without slowing the system.</p>

<p>Neither approach is universally correct.</p>

<p>The appropriate isolation level depends entirely on your business requirements.</p>

<hr />

<h1 id="concurrency-anomalies-the-problems-isolation-levels-exist-to-solve">Concurrency Anomalies: The Problems Isolation Levels Exist to Solve</h1>

<p>Isolation levels were not invented simply to make databases more complicated.</p>

<p>They exist because concurrent transactions can produce behaviors that most developers would consider surprising—or even dangerous.</p>

<p>These unexpected behaviors are collectively known as <strong>concurrency anomalies</strong>.</p>

<p>Every isolation level is essentially a trade-off between preventing these anomalies and maintaining good performance.</p>

<p>Before discussing the isolation levels themselves, it’s important to understand the problems they are designed to solve.</p>

<p>The four anomalies you’ll encounter most often are:</p>

<ul>
  <li>Dirty Reads</li>
  <li>Non-Repeatable Reads</li>
  <li>Phantom Reads</li>
  <li>Lost Updates</li>
</ul>

<p>Each represents a different way concurrent transactions can interfere with one another.</p>

<p>Let’s begin with the simplest.</p>

<hr />

<h1 id="dirty-reads">Dirty Reads</h1>

<p>Imagine Alice has <strong>KES 50,000</strong> in her account.</p>

<p>She initiates a transfer of <strong>KES 20,000</strong> to another account.</p>

<p>The banking system begins processing the transaction.</p>

<p>The first step deducts the money from Alice’s balance.</p>

<p>Before the transaction finishes, another process—perhaps an ATM balance inquiry or an online banking session—checks Alice’s account.</p>

<p>At that moment, it sees a balance of <strong>KES 30,000</strong>.</p>

<p>Everything seems perfectly normal.</p>

<p>Then something unexpected happens.</p>

<p>The transfer fails because the destination account no longer exists.</p>

<p>The database rolls back the transaction.</p>

<p>Alice’s balance immediately returns to <strong>KES 50,000</strong>.</p>

<p>The second transaction has now made a decision based on information that never officially existed.</p>

<p>It observed data that was eventually discarded.</p>

<p>This is known as a <strong>Dirty Read</strong>.</p>

<p>A dirty read occurs when one transaction reads data written by another transaction <strong>before that transaction has been committed</strong>.</p>

<p>The easiest way to understand it is to imagine reading someone’s unfinished draft before they’ve decided whether to keep or delete it.</p>

<p>The version you read may never become the final version.</p>

<p>Making business decisions based on that draft could lead to incorrect outcomes.</p>

<p>Fortunately, most modern relational databases prevent dirty reads by default because they are rarely desirable in business applications.</p>

<p>The SQL standard still defines them because they help explain the spectrum of isolation levels.</p>

<hr />

<h1 id="timeline-of-a-dirty-read">Timeline of a Dirty Read</h1>

<pre><code class="language-text">Transaction A                     Transaction B

BEGIN

Balance = 50,000

↓

Update Balance = 30,000

                               Read Balance = 30,000 ❌

↓

Transfer Fails

↓

ROLLBACK

Balance returns to 50,000
</code></pre>

<p>Transaction B has observed a value that disappeared moments later.</p>

<p>From the perspective of the database, that balance never officially existed.</p>

<p>Yet another transaction already acted as though it did.</p>

<p>This is precisely the type of inconsistency isolation levels are designed to prevent.</p>

<hr />
<h1 id="non-repeatable-reads">Non-Repeatable Reads</h1>

<p>Suppose you’re building an online banking application.</p>

<p>A customer opens the app and views their account balance. At that moment, the database reports a balance of <strong>KES 50,000</strong>.</p>

<p>The customer decides to transfer <strong>KES 40,000</strong> to another account, but before confirming the transfer, the application performs one final balance check to ensure sufficient funds are still available.</p>

<p>This seems like a perfectly reasonable workflow.</p>

<p>However, between the first balance check and the second, another transaction deposits <strong>KES 100,000</strong> into the same account.</p>

<p>When the application performs the second query, the balance is no longer <strong>KES 50,000</strong>.</p>

<p>It’s now <strong>KES 150,000</strong>.</p>

<p>Nothing is technically wrong.</p>

<p>The second transaction committed successfully.</p>

<p>The balance genuinely changed.</p>

<p>The surprising part is that <strong>the same transaction read the same row twice and received two different answers</strong>.</p>

<p>This phenomenon is known as a <strong>Non-Repeatable Read</strong>.</p>

<p>Unlike a dirty read, the second transaction isn’t reading uncommitted data. Every value it sees has been permanently committed to the database.</p>

<p>The inconsistency comes from the fact that another transaction modified the row while the first transaction was still running.</p>

<p>Imagine reading yesterday’s newspaper while someone keeps replacing pages with today’s edition.</p>

<p>The information isn’t incorrect.</p>

<p>It’s simply inconsistent because the document changed while you were reading it.</p>

<p>For many applications, this isn’t a problem.</p>

<p>If you’re refreshing a weather dashboard or checking the number of users currently online, it’s perfectly acceptable for values to change between two queries.</p>

<p>However, systems that rely on a stable snapshot of data—such as financial reporting, payroll processing, or end-of-day reconciliation—often require the same query to return the same result throughout the entire transaction.</p>

<hr />

<h1 id="timeline-of-a-non-repeatable-read">Timeline of a Non-Repeatable Read</h1>

<pre><code class="language-text">Transaction A                     Transaction B

BEGIN

Read Balance = 50,000

                               BEGIN

                               Deposit 100,000

                               COMMIT

Read Balance = 150,000 ❌

COMMIT
</code></pre>

<p>Transaction A never modified the balance itself.</p>

<p>It simply asked the same question twice and received two different answers because another committed transaction changed the underlying data in the meantime.</p>

<hr />

<h1 id="real-world-example-updating-a-customer-profile">Real-World Example: Updating a Customer Profile</h1>

<p>Consider an insurance application where a customer service representative opens a customer’s profile.</p>

<p>The representative spends several minutes reviewing the information before approving a policy update.</p>

<p>Meanwhile, another employee updates the customer’s phone number and address.</p>

<p>When the representative finally clicks <strong>Save</strong>, the application may now be working with information that is different from what was originally displayed.</p>

<p>Depending on how the application handles these changes, it could accidentally overwrite newer data or make decisions using outdated information.</p>

<p>This isn’t a database bug.</p>

<p>It’s simply the natural consequence of multiple users interacting with the same record at the same time.</p>

<p>Applications that require users to work with a consistent view of the data often use higher isolation levels or optimistic concurrency controls to detect these situations before committing changes.</p>

<hr />

<h1 id="phantom-reads">Phantom Reads</h1>

<p>Now let’s consider a different scenario.</p>

<p>Instead of reading a single row twice, imagine you’re querying an entire collection of rows.</p>

<p>Suppose you’re generating a report showing all loan applications submitted today.</p>

<p>Your first query returns:</p>

<pre><code class="language-text">Loan Applications Submitted Today

-------------------------------

Loan #101

Loan #102

Loan #103

Total: 3
</code></pre>

<p>While your report is still running, another loan application is submitted and committed to the database.</p>

<p>A few moments later, your transaction performs the exact same query again.</p>

<p>This time the results look different.</p>

<pre><code class="language-text">Loan Applications Submitted Today

-------------------------------

Loan #101

Loan #102

Loan #103

Loan #104

Total: 4
</code></pre>

<p>Notice what changed.</p>

<p>None of the existing rows were modified.</p>

<p>Instead, an entirely <strong>new row appeared</strong>.</p>

<p>This is called a <strong>Phantom Read</strong>.</p>

<p>A phantom read occurs when the same query returns a different set of rows because another transaction inserted, updated, or deleted records that match the query’s search criteria.</p>

<p>Think of it like counting the number of people in a room.</p>

<p>You count 20 people.</p>

<p>While you’re writing the number down, someone walks into the room.</p>

<p>You count again.</p>

<p>Now there are 21 people.</p>

<p>Nothing about the original twenty people changed.</p>

<p>The difference is that a new “phantom” appeared between your two observations.</p>

<hr />

<h1 id="timeline-of-a-phantom-read">Timeline of a Phantom Read</h1>

<pre><code class="language-text">Transaction A                     Transaction B

BEGIN

SELECT *

WHERE loan_date = TODAY

Returns 3 rows

                               BEGIN

                               INSERT Loan #104

                               COMMIT

SELECT *

WHERE loan_date = TODAY

Returns 4 rows ❌

COMMIT
</code></pre>

<p>Unlike a non-repeatable read, where an existing row changes, phantom reads involve the appearance or disappearance of entire rows.</p>

<hr />

<h1 id="why-phantom-reads-matter">Why Phantom Reads Matter</h1>

<p>Imagine you’re calculating today’s total revenue for financial reporting.</p>

<p>Your reporting transaction begins at 5:00 PM and starts aggregating sales.</p>

<p>While it’s still processing, new sales continue being recorded.</p>

<p>Different parts of the report may now be working with different datasets.</p>

<p>The total revenue calculated on page one might not match the detailed transaction list generated on page five because new rows appeared while the report was still executing.</p>

<p>In reporting systems, this can produce confusing and inconsistent results.</p>

<p>Higher isolation levels solve this problem by ensuring the transaction sees a consistent snapshot of the data throughout its lifetime, even if other transactions continue inserting new rows.</p>

<hr />

<h1 id="lost-updates">Lost Updates</h1>

<p>The final concurrency anomaly is perhaps the most dangerous because it silently discards valid work.</p>

<p>Imagine two warehouse employees looking at the same inventory record.</p>

<p>The system currently shows:</p>

<pre><code class="language-text">Laptop Stock = 10
</code></pre>

<p>Employee A sells one laptop.</p>

<p>Employee B also sells one laptop at almost exactly the same time.</p>

<p>Both employees read the current stock before making their update.</p>

<p>Each calculates the new quantity as:</p>

<pre><code class="language-text">10 - 1 = 9
</code></pre>

<p>Employee A saves.</p>

<p>The inventory becomes:</p>

<pre><code class="language-text">9
</code></pre>

<p>A fraction of a second later, Employee B saves.</p>

<p>The inventory is still:</p>

<pre><code class="language-text">9
</code></pre>

<p>One of the updates has effectively disappeared.</p>

<p>The correct inventory should now be <strong>8</strong>, but because both transactions started from the same original value, one update overwrote the other.</p>

<p>This is known as a <strong>Lost Update</strong>.</p>

<p>Unlike the previous anomalies, nothing appears obviously wrong.</p>

<p>No errors occur.</p>

<p>No constraints are violated.</p>

<p>The database happily accepts both updates.</p>

<p>The problem is that one user’s work has unintentionally replaced another’s.</p>

<p>Lost updates are one of the primary reasons databases provide row locking, optimistic concurrency control, and stronger isolation levels.</p>

<p>Without these protections, applications that receive many simultaneous updates—such as inventory systems, banking platforms, or booking applications—can slowly drift away from reality without anyone noticing.</p>

<p>Now that we understand the problems, the next question is obvious: How do databases prevent them? That’s exactly what we’ll cover in Part 2.”</p>

]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="Database" />
    
    <category term="Concurrency" />
    
  

  
    
    <category term="Database" />
    
    <category term="Concurrency" />
    
  

    <summary>Database isolation levels determine what one transaction can see while another transaction is still running. This article explains why isolation levels exist, the four SQL standard isolation levels, and how to choose the right one for your application.</summary>

  </entry>

  
  





  



  


  <entry>
    <title>Database Transactions Explained: Keeping Data Correct When Things Go Wrong</title>
    <link href="https://billyokeyo.dev/posts/database-transactions-explained/" rel="alternate" type="text/html" title="Database Transactions Explained: Keeping Data Correct When Things Go Wrong" />
    <published>2026-07-03T00:00:00+00:00</published>
  
    <updated>2026-07-03T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/database-transactions-explained/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/database-transactions-explained/"><![CDATA[<blockquote>
  <p><em>“Transactions are not just a database feature—they’re one of the fundamental building blocks of reliable software.”</em></p>
</blockquote>

<p>Imagine you’re transferring <strong>KES 10,000</strong> from your savings account to a friend.</p>

<p>From your perspective, it’s a single action. You tap <strong>“Send Money”</strong>, authenticate the transaction, and wait for confirmation. Behind the scenes, however, the banking system performs several independent operations. It verifies that you have sufficient funds, deducts the amount from your account, credits your friend’s account, records the transaction in a ledger, updates account balances, and generates a receipt.</p>

<p>Each of these operations is important, but together they represent a single business action: <strong>a money transfer</strong>.</p>

<p>Now imagine the server crashes immediately after deducting the money from your account but before crediting your friend.</p>

<p>The result is disastrous. Your balance has decreased, your friend never receives the money, and unless additional recovery mechanisms exist, the system is left in an inconsistent state. From a customer’s perspective, the money has simply disappeared.</p>

<p>The same problem appears outside banking.</p>

<p>An e-commerce application might create an order, reduce inventory, process a payment, generate an invoice, and send a confirmation email. If the payment succeeds but the order creation fails, the customer has paid for a product that the system doesn’t believe exists. Likewise, in a loan management system, a repayment may update the outstanding balance, post accounting entries, and generate a receipt. If only some of those updates complete, financial records quickly become unreliable.</p>

<p>These problems aren’t caused by bad algorithms or poor business logic. They’re caused by <strong>partial execution</strong> when only part of a larger operation succeeds.</p>

<p>This is precisely the problem database transactions were designed to solve.</p>

<p>A transaction ensures that multiple database operations behave as a single unit of work. Either every operation succeeds together, or every operation is rolled back as though nothing ever happened. There is no halfway point where your system is left in an inconsistent state.</p>

<p>For backend developers, understanding transactions is just as important as understanding APIs or databases themselves. They are the foundation upon which reliable financial systems, booking platforms, inventory systems, healthcare applications, and countless other business-critical systems are built.</p>

<hr />

<h1 id="what-is-a-database-transaction">What Is a Database Transaction?</h1>

<p>A database transaction is a collection of one or more database operations that the database treats as a single logical operation.</p>

<p>Instead of thinking about individual SQL statements, think about the business process they represent.</p>

<p>Suppose a customer purchases the last laptop in your online store. That single purchase might require your application to:</p>

<ul>
  <li>Create an order.</li>
  <li>Deduct one item from inventory.</li>
  <li>Reserve the shipment.</li>
  <li>Record the payment.</li>
  <li>Create an invoice.</li>
</ul>

<p>Although these are separate SQL statements, they represent one business event. Either all of them should succeed, or none of them should.</p>

<p>That’s exactly what a transaction guarantees.</p>

<p>Without transactions, every statement executes independently. If statement number four fails, the previous three remain committed, leaving your data inconsistent.</p>

<p>With transactions, the database waits until you’re satisfied that every operation has completed successfully. Only then are the changes permanently saved.</p>

<hr />

<h1 id="understanding-transactions-through-a-simple-example">Understanding Transactions Through a Simple Example</h1>

<p>Let’s return to the banking example.</p>

<p>Alice wants to transfer <strong>KES 10,000</strong> to Bob.</p>

<p>A simplified version of the SQL might look like this:</p>

<pre><code class="language-sql">UPDATE accounts
SET balance = balance - 10000
WHERE account_id = 1;

UPDATE accounts
SET balance = balance + 10000
WHERE account_id = 2;
</code></pre>

<p>At first glance, this seems perfectly reasonable.</p>

<p>But imagine the database crashes immediately after the first statement executes.</p>

<p>Alice’s balance has already been reduced.</p>

<p>Bob’s balance has not increased.</p>

<p>The system now contains incorrect financial data.</p>

<p>This is why production systems rarely execute related operations independently.</p>

<p>Instead, they wrap them inside a transaction.</p>

<pre><code class="language-sql">BEGIN;

UPDATE accounts
SET balance = balance - 10000
WHERE account_id = 1;

UPDATE accounts
SET balance = balance + 10000
WHERE account_id = 2;

COMMIT;
</code></pre>

<p>If every statement succeeds, the database executes the <code>COMMIT</code>, making the changes permanent.</p>

<p>If any statement fails before that point, the application issues a <code>ROLLBACK</code>, and the database restores itself to exactly the state it was in before the transaction began.</p>

<p>To the outside world, it appears as though the failed transfer never happened.</p>

<p>This “all-or-nothing” behavior is what makes transactions so valuable.</p>

<hr />

<h1 id="the-lifecycle-of-a-transaction">The Lifecycle of a Transaction</h1>

<p>Every transaction follows a predictable lifecycle.</p>

<pre><code class="language-text">BEGIN
   │
Execute SQL Operations
   │
Everything Successful?
   │
 ┌─ Yes ─────────────┐
 │                   │
COMMIT          Changes Saved
 │
 └─ No ──────────────┐
                     │
                 ROLLBACK
                     │
          Database Restored
</code></pre>

<p>The process begins with <code>BEGIN</code>, which tells the database to temporarily hold all modifications rather than immediately committing them.</p>

<p>The application then performs one or more operations. These could involve inserting records, updating balances, deleting data, or modifying relationships between tables.</p>

<p>If every operation succeeds, the application calls <code>COMMIT</code>. At that point, the database permanently saves all changes.</p>

<p>If anything goes wrong along the way, perhaps a validation error, a database constraint violation, or even an unexpected server failure, the transaction is rolled back, discarding every change made since <code>BEGIN</code>.</p>

<p>The beauty of this model is that the database itself guarantees consistency. Developers don’t need to manually undo every failed operation because the database handles that responsibility.</p>

<hr />

<h1 id="the-four-acid-properties">The Four ACID Properties</h1>

<p>When developers discuss transactions, you’ll almost always hear the term <strong>ACID</strong>.</p>

<p>Despite sounding intimidating, ACID simply describes the guarantees that modern relational databases provide when executing transactions.</p>

<h2 id="atomicity">Atomicity</h2>

<p>Atomicity means that a transaction is indivisible.</p>

<p>Either every operation succeeds, or none of them do.</p>

<p>Returning to our banking example, it makes no sense for money to be deducted from one account without being added to another. The transaction must succeed completely or fail completely.</p>

<p>Think of flipping a light switch.</p>

<p>The light cannot be half on.</p>

<p>Similarly, a transaction cannot be half completed.</p>

<hr />

<h2 id="consistency">Consistency</h2>

<p>Consistency ensures that every transaction leaves the database in a valid state.</p>

<p>Business rules should always remain true.</p>

<p>If your application enforces that inventory can never become negative, then a successful transaction should never violate that rule.</p>

<p>Likewise, if your accounting system requires every journal entry to balance, no committed transaction should ever leave the ledger unbalanced.</p>

<p>Consistency isn’t about preventing bugs in your application logic; it’s about ensuring that completed transactions respect the rules defined by your database and your business.</p>

<hr />

<h2 id="isolation">Isolation</h2>

<p>Isolation becomes important when multiple users interact with the system simultaneously.</p>

<p>Imagine two customers attempting to purchase the last available ticket for a concert.</p>

<p>Without proper isolation, both requests may read the inventory before either updates it. Both believe the ticket is available, and both complete the purchase.</p>

<p>You’ve now sold the same seat twice.</p>

<p>Isolation ensures that concurrent transactions don’t interfere with one another in ways that produce inconsistent results.</p>

<p>In our previous article, we discussed <strong>race conditions</strong> situations where multiple requests compete to modify the same data. Isolation is one of the database mechanisms used to prevent those concurrency problems.</p>

<p>We’ll explore isolation levels in greater depth in the next article because they deserve an entire discussion of their own.</p>

<hr />

<h2 id="durability">Durability</h2>

<p>Durability guarantees that once a transaction has been committed, the changes are permanent.</p>

<p>Even if the server loses power immediately after the commit, the database ensures that committed data survives.</p>

<p>Modern databases achieve this through techniques such as write-ahead logging, transaction logs, and crash recovery.</p>

<p>For developers, the important takeaway is simple: once the database confirms a successful commit, you can trust that the data has been safely stored.</p>

<hr />

<h1 id="transactions-solve-partial-failures-not-every-problem">Transactions Solve Partial Failures: Not Every Problem</h1>

<p>One misconception among newer developers is that transactions magically solve every data consistency problem.</p>

<p>They don’t.</p>

<p>Transactions protect against <strong>partial execution</strong>.</p>

<p>Suppose your application updates three tables and crashes after updating the second one. A transaction ensures that the database rolls everything back, preventing inconsistent data. However, transactions don’t automatically solve concurrency problems.</p>

<p>Imagine two users attempting to withdraw money from the same account simultaneously.
Each transaction independently checks the balance before either completes. If both see the same balance and both proceed, the final result may still be incorrect depending on your isolation level. This isn’t a transaction problem. It’s a concurrency problem.</p>

<p>That’s why understanding race conditions and transactions together is so important. They solve different classes of reliability issues.</p>

<hr />

<h1 id="common-places-youll-use-transactions">Common Places You’ll Use Transactions</h1>

<p>Transactions appear almost everywhere in modern backend systems.</p>

<p>Payment processing is perhaps the most obvious example. Charging a customer’s card, recording the payment, updating invoices, and generating accounting entries should either all succeed or all fail together.</p>

<p>Inventory management systems use transactions to ensure stock counts remain accurate even when multiple customers are purchasing products simultaneously.</p>

<p>Booking platforms rely on transactions to reserve hotel rooms, airline seats, or event tickets without creating conflicting reservations.</p>

<p>Loan management systems use transactions when posting repayments, updating outstanding balances, calculating accrued interest, and recording accounting entries.</p>

<p>Healthcare systems use them to ensure patient records, prescriptions, billing information, and appointment schedules remain synchronized.</p>

<p>Any time a business operation spans multiple database changes, a transaction is usually involved.</p>

<hr />

<h1 id="common-mistakes-developers-make">Common Mistakes Developers Make</h1>

<p>One of the most common mistakes is keeping transactions open for too long.</p>

<p>Imagine starting a transaction, calling a third-party payment API, waiting several seconds for a response, and only then committing the transaction.</p>

<p>During that entire period, database resources may remain locked, reducing performance for other users.</p>

<p>A better approach is to perform external API calls before starting the transaction whenever possible, keeping the transaction focused solely on database operations.</p>

<p>Another common mistake is assuming transactions automatically protect against concurrent updates. As we’ve already seen, concurrency introduces an entirely different set of challenges that require locking strategies or appropriate isolation levels.</p>

<p>Finally, developers sometimes forget that transactions should represent business operations not individual SQL statements. Wrapping every single query in its own transaction rarely provides meaningful benefits.</p>

<hr />

<h1 id="transactions-in-modern-frameworks">Transactions in Modern Frameworks</h1>

<p>Fortunately, most frameworks make transactions straightforward to use.</p>

<p>Laravel offers the <code>DB::transaction()</code> helper.</p>

<p>Django provides <code>transaction.atomic()</code>.</p>

<p>Entity Framework supports <code>BeginTransactionAsync()</code>.</p>

<p>Spring Boot uses the <code>@Transactional</code> annotation.</p>

<p>Although the syntax differs, the underlying principle never changes. The framework simply tells the database when to begin the transaction, when to commit it, and when to roll it back if something goes wrong.</p>

<p>Understanding the concept matters far more than memorizing framework-specific syntax.</p>

<hr />

<h1 id="transactions-idempotency-and-race-conditions">Transactions, Idempotency, and Race Conditions</h1>

<p>If you’ve been following this series, you may have noticed that each concept addresses a different reliability challenge.</p>

<p><strong>Idempotency</strong> protects against duplicate requests by ensuring that repeating the same request doesn’t produce duplicate side effects.</p>

<p><strong>Race conditions</strong> occur when multiple requests compete to modify shared data simultaneously, leading to unpredictable outcomes.</p>

<p><strong>Transactions</strong> ensure that a group of related database operations either all succeed together or all fail together.</p>

<p>Reliable backend systems typically rely on all three.</p>

<p>Imagine a payment API.</p>

<p>Idempotency prevents customers from being charged twice if they retry a request.</p>

<p>Transactions ensure that charging the customer, recording the payment, and updating account balances either all succeed or all fail.</p>

<p>Proper concurrency control ensures that two simultaneous payment requests don’t corrupt shared data.</p>

<p>Each concept complements the others rather than replacing them.</p>

<hr />

<h1 id="final-thoughts">Final Thoughts</h1>

<p>Transactions are one of the reasons relational databases remain so powerful. They provide developers with a reliable mechanism for preserving data integrity even when failures occur.</p>

<p>As systems become larger and more distributed, failures become inevitable. Servers crash, networks fail, APIs time out, and users submit requests simultaneously. Transactions don’t eliminate those realities, but they ensure your database remains consistent when they happen.</p>

<p>Whenever you’re implementing a feature that modifies multiple pieces of related data, pause for a moment and ask yourself:</p>

<blockquote>
  <p><strong>What happens if this operation fails halfway through?</strong></p>
</blockquote>

<p>If the answer is “my system ends up in an inconsistent state,” then you’ve almost certainly found a place where a database transaction belongs.</p>

<p>In the next article, we’ll build on this foundation by exploring <strong>database isolation levels</strong> and why two perfectly valid transactions can still interfere with one another when they run at the same time.</p>
]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="Database" />
    
    <category term="Software Engineering" />
    
  

  
    
    <category term="Database" />
    
    <category term="Software Engineering" />
    
  

    <summary>Database transactions are a fundamental concept in database management systems that ensure data integrity and consistency. This article explains what database transactions are, why they are important, and how they work.</summary>

  </entry>

  
  





  



  


  <entry>
    <title>Race Conditions Explained: The Concurrency Bug Every Backend Developer Should Understand</title>
    <link href="https://billyokeyo.dev/posts/race-conditions-explained/" rel="alternate" type="text/html" title="Race Conditions Explained: The Concurrency Bug Every Backend Developer Should Understand" />
    <published>2026-06-28T00:00:00+00:00</published>
  
    <updated>2026-06-28T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/race-conditions-explained/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/race-conditions-explained/"><![CDATA[<p>Imagine you’re trying to buy the last ticket for your favorite concert.</p>

<p>The website shows:</p>

<blockquote>
  <p><strong>Only 1 ticket remaining.</strong></p>
</blockquote>

<p>At exactly the same moment, someone else clicks <strong>Buy</strong>.</p>

<p>Both of you complete payment.</p>

<p>Both of you receive confirmation emails.</p>

<p>But there was only one ticket.</p>

<p>How did two people successfully purchase the same seat?</p>

<p>Now imagine the same thing happening in a banking application.</p>

<p>Two ATM withdrawals happen at almost the same time.</p>

<p>Both check the balance before either transaction finishes.</p>

<p>Both think there’s enough money.</p>

<p>Both approve the withdrawal.</p>

<p>The account ends up with a negative balance.</p>

<p>Neither application is necessarily “broken.”</p>

<p>Instead, they suffer from one of the most common problems in software engineering:</p>

<p><strong>Race conditions.</strong></p>

<p>Race conditions are among the hardest bugs to reproduce because they don’t happen every time. They may only appear under heavy traffic, high concurrency, or perfect timing. Everything works during testing until your application reaches production.</p>

<p>In this article, we’ll explore what race conditions are, why they happen, how they relate to idempotency, and the techniques developers use to prevent them.</p>

<hr />

<h1 id="what-is-a-race-condition">What Is a Race Condition?</h1>

<p>A race condition occurs when <strong>two or more operations access and modify the same piece of data at the same time, and the final result depends on the order in which they execute.</strong></p>

<p>The important phrase is:</p>

<blockquote>
  <p><strong>The outcome depends on timing.</strong></p>
</blockquote>

<p>That’s what makes race conditions so dangerous.</p>

<p>Sometimes everything works.</p>

<p>Sometimes everything breaks.</p>

<p>The exact same code can produce different results simply because two requests happened a few milliseconds apart.</p>

<hr />

<h1 id="a-simple-analogy">A Simple Analogy</h1>

<p>Imagine two people standing in front of a cookie jar.</p>

<p>The jar contains exactly one cookie.</p>

<p>Both people look inside.</p>

<p>Both see one cookie.</p>

<p>Both reach in.</p>

<p>Both believe they’ll get the cookie.</p>

<p>Reality says otherwise.</p>

<p>Only one cookie exists.</p>

<p>The mistake happened because both people <strong>checked the state before either updated it.</strong></p>

<p>Software behaves exactly the same way.</p>

<hr />

<h1 id="a-real-banking-example">A Real Banking Example</h1>

<p>Suppose an account has:</p>

<pre><code class="language-text">Balance = $100
</code></pre>

<p>Two withdrawal requests arrive simultaneously.</p>

<pre><code>Request A → Withdraw $80

Request B → Withdraw $50
</code></pre>

<p>Without synchronization:</p>

<pre><code>Request A
↓

Read Balance ($100)

------------

Request B

↓

Read Balance ($100)

------------

Request A

Balance = $20

------------

Request B

Balance = $50
</code></pre>

<p>Depending on timing, the final balance might be:</p>

<pre><code>$20

or

$50

or

-$30
</code></pre>

<p>None of these outcomes are guaranteed.</p>

<p>This is a race condition.</p>

<hr />

<h1 id="why-it-works-during-development">Why It Works During Development</h1>

<p>Most developers test applications alone.</p>

<p>One request.</p>

<p>One browser.</p>

<p>One user.</p>

<p>Everything works perfectly.</p>

<p>Production is different.</p>

<p>Imagine:</p>

<ul>
  <li>5,000 users</li>
  <li>Hundreds of requests per second</li>
  <li>Multiple application servers</li>
  <li>Database replication</li>
  <li>Network latency</li>
</ul>

<p>The probability of two requests colliding becomes much higher.</p>

<p>Race conditions often appear only after an application becomes successful.</p>

<p>Ironically, scaling your application can reveal bugs that never existed during development.</p>

<hr />

<h1 id="race-conditions-vs-idempotency">Race Conditions vs Idempotency</h1>

<p>If you’ve read my previous article on idempotency, if not, read it first <a href="https://billyokeyo.dev/posts/idempotency-explained/">here</a>. You might wonder whether they’re the same thing.</p>

<p>They’re related, but they solve different problems.</p>

<h3 id="idempotency-answers">Idempotency answers:</h3>

<blockquote>
  <p>What if the <strong>same request</strong> is sent twice?</p>
</blockquote>

<p>Example:</p>

<pre><code>POST /payments

↓

Retry

↓

POST /payments
</code></pre>

<p>The solution is an <strong>Idempotency-Key</strong>.</p>

<p>The same request produces the same result.</p>

<hr />

<h3 id="race-conditions-answer">Race conditions answer:</h3>

<blockquote>
  <p>What if <strong>different requests</strong> happen at the same time?</p>
</blockquote>

<p>Example:</p>

<pre><code>User A buys last ticket

↓

User B buys last ticket
</code></pre>

<p>These are two legitimate requests from different users.</p>

<p>An idempotency key won’t help because the requests are not duplicates.</p>

<p>Race conditions require synchronization, not deduplication.</p>

<hr />

<h1 id="real-world-examples">Real-World Examples</h1>

<h2 id="airline-seat-booking">Airline Seat Booking</h2>

<p>Only one seat remains.</p>

<p>Two customers purchase it simultaneously.</p>

<p>Without proper locking:</p>

<ul>
  <li>Seat sold twice</li>
  <li>Refund required</li>
  <li>Customer frustration</li>
</ul>

<hr />

<h2 id="e-commerce-inventory">E-Commerce Inventory</h2>

<p>Stock:</p>

<pre><code>Laptop

Quantity = 1
</code></pre>

<p>Two customers purchase simultaneously.</p>

<p>Without protection:</p>

<p>Inventory becomes:</p>

<pre><code>-1
</code></pre>

<p>Now you’ve sold a product you don’t have.</p>

<hr />

<h2 id="loan-approval-systems">Loan Approval Systems</h2>

<p>Imagine two loan officers reviewing the same application.</p>

<p>Officer A:</p>

<p>Approve.</p>

<p>Officer B:</p>

<p>Reject.</p>

<p>If both updates happen simultaneously without coordination, the final loan status depends entirely on timing.</p>

<hr />

<h2 id="coupon-redemption">Coupon Redemption</h2>

<p>Promotion:</p>

<pre><code>First 100 customers only
</code></pre>

<p>If multiple requests update the redemption count simultaneously, you might accidentally issue:</p>

<pre><code>103

105

110

coupons.
</code></pre>

<hr />

<h1 id="how-race-conditions-happen">How Race Conditions Happen</h1>

<p>Most race conditions follow this pattern:</p>

<pre><code>Read

↓

Modify

↓

Write
</code></pre>

<p>The danger lies between <strong>Read</strong> and <strong>Write</strong>.</p>

<p>Example:</p>

<pre><code>Read Balance

↓

Calculate New Balance

↓

Update Balance
</code></pre>

<p>If another request changes the balance between those steps, your calculation becomes outdated.</p>

<p>This is known as a <strong>Lost Update</strong> problem.</p>

<hr />

<h1 id="solution-1-database-transactions">Solution 1: Database Transactions</h1>

<p>Transactions ensure multiple operations succeed or fail together.</p>

<p>Example:</p>

<pre><code class="language-sql">BEGIN;

SELECT balance
FROM accounts
WHERE id = 1;

UPDATE accounts
SET balance = balance - 80
WHERE id = 1;

COMMIT;
</code></pre>

<p>Transactions protect data consistency.</p>

<p>However, they don’t automatically eliminate every race condition.</p>

<p>Isolation levels matter too.</p>

<hr />

<h1 id="solution-2-row-level-locks">Solution 2: Row-Level Locks</h1>

<p>Many relational databases allow locking a row while it’s being updated.</p>

<p>Example:</p>

<pre><code class="language-sql">SELECT *
FROM accounts
WHERE id = 1
FOR UPDATE;
</code></pre>

<p>Now:</p>

<p>Request A locks the row.</p>

<p>Request B must wait.</p>

<p>Only after Request A finishes can Request B continue.</p>

<p>This guarantees consistent updates.</p>

<hr />

<h1 id="solution-3-optimistic-locking">Solution 3: Optimistic Locking</h1>

<p>Instead of preventing conflicts, optimistic locking detects them.</p>

<p>Imagine a version number.</p>

<pre><code>Account

Balance = 100

Version = 5
</code></pre>

<p>Update:</p>

<pre><code>WHERE Version = 5
</code></pre>

<p>If another request updates the row first:</p>

<pre><code>Version = 6
</code></pre>

<p>Your update fails.</p>

<p>The client retries with fresh data.</p>

<p>Optimistic locking works well when collisions are relatively rare.</p>

<hr />

<h1 id="solution-4-distributed-locks">Solution 4: Distributed Locks</h1>

<p>What if your application runs on multiple servers?</p>

<pre><code>Server A

↓

Database

↑

Server B
</code></pre>

<p>A normal in-memory lock won’t work because each server has its own memory.</p>

<p>Instead, developers use distributed locking systems like:</p>

<ul>
  <li>Redis (Redlock)</li>
  <li>ZooKeeper</li>
  <li>etcd</li>
  <li>Consul</li>
</ul>

<p>These coordinate access across multiple application instances.</p>

<hr />

<h1 id="solution-5-atomic-database-operations">Solution 5: Atomic Database Operations</h1>

<p>Sometimes you don’t need to:</p>

<pre><code>Read

↓

Calculate

↓

Write
</code></pre>

<p>Instead, let the database perform the update atomically.</p>

<p>Bad:</p>

<pre><code class="language-sql">SELECT quantity;

quantity--;

UPDATE products;
</code></pre>

<p>Better:</p>

<pre><code class="language-sql">UPDATE products

SET quantity = quantity - 1

WHERE quantity &gt; 0;
</code></pre>

<p>Now the database guarantees consistency.</p>

<hr />

<h1 id="detecting-race-conditions">Detecting Race Conditions</h1>

<p>One reason race conditions are difficult is that they rarely appear during manual testing.</p>

<p>Ways to uncover them include:</p>

<ul>
  <li>Load testing with concurrent users</li>
  <li>Stress testing</li>
  <li>Running parallel integration tests</li>
  <li>Simulating delayed responses</li>
  <li>Chaos engineering</li>
  <li>Monitoring production logs</li>
</ul>

<p>If a bug only appears “sometimes,” concurrency should be one of your first suspects.</p>

<hr />

<h1 id="best-practices">Best Practices</h1>

<p>When designing systems that handle shared data:</p>

<ul>
  <li>Keep transactions short.</li>
  <li>Avoid long-running locks.</li>
  <li>Prefer atomic database operations where possible.</li>
  <li>Use optimistic locking when contention is low.</li>
  <li>Use pessimistic locking for critical resources.</li>
  <li>Test with concurrent requests, not just sequential ones.</li>
  <li>Understand your database’s transaction isolation levels.</li>
</ul>

<p>Most importantly, always ask:</p>

<blockquote>
  <p><strong>“What happens if two users do this at exactly the same time?”</strong></p>
</blockquote>

<hr />

<h1 id="final-thoughts">Final Thoughts</h1>

<p>Race conditions aren’t caused by bad developers, they’re caused by systems becoming concurrent.</p>

<p>As applications grow, users interact simultaneously, background jobs overlap, and services communicate in parallel. Timing becomes unpredictable.</p>

<p>That’s why building reliable software isn’t just about writing correct logic for one request. It’s about ensuring your logic remains correct when hundreds or thousands of requests happen together.</p>

<p>If idempotency protects you from duplicate requests, race condition handling protects you from competing requests.</p>

<p>Together, they form two of the most important building blocks for designing resilient APIs and distributed systems.</p>

<p>The next time you write code that reads, modifies, and writes shared data, pause for a moment and ask:</p>

<blockquote>
  <p><strong>“What happens if someone else does this at the exact same time?”</strong></p>
</blockquote>

<p>If you don’t know the answer, you’ve just found your next engineering problem to solve.</p>
]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="API Design" />
    
    <category term="Software Testing" />
    
  

  
    
    <category term="Race Conditions" />
    
    <category term="API Design" />
    
    <category term="Software Testing" />
    
  

    <summary>Race conditions are among the hardest bugs to reproduce because they don&apos;t happen every time. They may only appear under heavy traffic, high concurrency, or perfect timing. Everything works during testing—until your application reaches production. This article explains what race conditions are, why they happen, how they relate to idempotency, and the techniques developers use to prevent them.</summary>

  </entry>

  
  





  



  


  <entry>
    <title>Idempotency Explained: Building APIs That Survive Retries</title>
    <link href="https://billyokeyo.dev/posts/idempotency-explained/" rel="alternate" type="text/html" title="Idempotency Explained: Building APIs That Survive Retries" />
    <published>2026-06-25T00:00:00+00:00</published>
  
    <updated>2026-06-25T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/idempotency-explained/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/idempotency-explained/"><![CDATA[<p>Imagine you’re purchasing a product online.</p>

<p>You click the <strong>“Pay Now”</strong> button.</p>

<p>Nothing happens.</p>

<p>After a few seconds, you assume the request failed, so you click the button again.</p>

<p>And again.</p>

<p>A few minutes later, you discover you’ve been charged three times.</p>

<p>What happened?</p>

<p>From the user’s perspective, the payment seemed to fail. From the server’s perspective, however, it successfully processed every request it received.</p>

<p>This is one of the most common problems in distributed systems, and it’s exactly why idempotency exists.</p>

<p>Whether you’re building payment systems, booking platforms, inventory management software, or any API that changes data, retries are inevitable. Networks fail, clients time out, mobile connections drop, and users double-click buttons.</p>

<p>A well-designed API should survive these retries without creating duplicate side effects.</p>

<p>In this article, we’ll explore what idempotency is, why it matters, and how to implement it in your own APIs.</p>

<hr />

<h1 id="what-is-idempotency">What Is Idempotency?</h1>

<p>In simple terms, <strong>an idempotent operation can be performed multiple times without changing the final result beyond the first successful execution.</strong></p>

<p>For example:</p>

<pre><code>Turn on the light.
Turn on the light again.
Turn on the light again.
</code></pre>

<p>The light is still <strong>ON</strong>.</p>

<p>Nothing new happened after the first request.</p>

<p>The final state remains the same.</p>

<p>That’s idempotency.</p>

<p>Now compare it with this:</p>

<pre><code>Deposit $100
Deposit $100
Deposit $100
</code></pre>

<p>Your account balance increases by <strong>$300</strong>.</p>

<p>This operation is <strong>not idempotent</strong> because every request changes the system.</p>

<hr />

<h1 id="why-retries-happen">Why Retries Happen</h1>

<p>Many developers assume users only send one request.</p>

<p>Reality is different.</p>

<p>Requests are retried because of:</p>

<ul>
  <li>Slow internet connections</li>
  <li>Gateway timeouts</li>
  <li>Reverse proxies</li>
  <li>Mobile network interruptions</li>
  <li>Browser refreshes</li>
  <li>Double-clicking buttons</li>
  <li>Client retry mechanisms</li>
  <li>Load balancers</li>
  <li>Microservice communication failures</li>
</ul>

<p>Imagine this timeline:</p>

<pre><code>Client -------- POST /payments --------&gt; API

             Payment succeeds

API -------- 200 OK --------X

(Response never reaches client)

Client waits...

Client retries.

POST /payments again.
</code></pre>

<p>The client believes the payment failed.</p>

<p>The server already completed it.</p>

<p>Without idempotency…</p>

<p>The payment happens twice.</p>

<hr />

<h1 id="http-methods-and-idempotency">HTTP Methods and Idempotency</h1>

<p>HTTP itself distinguishes between idempotent and non-idempotent methods.</p>

<h3 id="get">GET</h3>

<pre><code>GET /users/10
</code></pre>

<p>Read the user.</p>

<p>Call it once.</p>

<p>Call it 100 times.</p>

<p>Nothing changes.</p>

<p>Idempotent</p>

<hr />

<h3 id="put">PUT</h3>

<pre><code>PUT /users/10
{
   "name": "Billy"
}
</code></pre>

<p>Replacing the same resource repeatedly produces the same result.</p>

<p>Idempotent</p>

<hr />

<h3 id="delete">DELETE</h3>

<pre><code>DELETE /users/10
</code></pre>

<p>Delete the user.</p>

<p>Deleting an already deleted user doesn’t delete them twice.</p>

<p>The final state is still:</p>

<pre><code>User does not exist.
</code></pre>

<p>Idempotent</p>

<hr />

<h3 id="post">POST</h3>

<pre><code>POST /orders
</code></pre>

<p>Create a new order.</p>

<p>Call it twice.</p>

<p>You now have two orders.</p>

<p>Not idempotent</p>

<p>This is why POST requests often require additional protection.</p>

<hr />

<h1 id="why-payment-apis-use-idempotency-keys">Why Payment APIs Use Idempotency Keys</h1>

<p>Payment providers like Stripe popularized the use of <strong>Idempotency Keys</strong>.</p>

<p>The idea is simple.</p>

<p>The client generates a unique identifier.</p>

<p>Example:</p>

<pre><code>Idempotency-Key:
6ab89d3b-acde-4d71-b20d-483d8d0ef091
</code></pre>

<p>Every retry sends the same key.</p>

<pre><code>POST /payments

Idempotency-Key:
6ab89d3b-acde-4d71-b20d-483d8d0ef091
</code></pre>

<p>When the server receives the request:</p>

<ol>
  <li>Check if this key already exists.</li>
  <li>If not, process the payment.</li>
  <li>Save both the key and the response.</li>
  <li>Return the response.</li>
</ol>

<p>If the same request arrives again with the same key:</p>

<p>Instead of charging the customer again…</p>

<p>Return the previously stored response.</p>

<pre><code>Client

POST /payments
Key: ABC123

↓

Server

Charge customer

↓

Store

ABC123 → Payment #456

↓

Return success

---

Retry

POST /payments
Key: ABC123

↓

Lookup

ABC123 exists

↓

Return Payment #456

No second charge.
</code></pre>

<hr />

<h1 id="implementing-idempotency">Implementing Idempotency</h1>

<p>A common workflow looks like this.</p>

<h2 id="step-1">Step 1</h2>

<p>Receive request.</p>

<pre><code>POST /orders
</code></pre>

<p>Headers</p>

<pre><code>Idempotency-Key:
XYZ987
</code></pre>

<hr />

<h2 id="step-2">Step 2</h2>

<p>Search database.</p>

<pre><code>SELECT *
FROM idempotency_keys
WHERE key = 'XYZ987'
</code></pre>

<p>Found?</p>

<p>Yes.</p>

<p>Return stored response.</p>

<p>Done.</p>

<hr />

<h2 id="step-3">Step 3</h2>

<p>Not found?</p>

<p>Create the resource.</p>

<pre><code>Create Order
</code></pre>

<hr />

<h2 id="step-4">Step 4</h2>

<p>Store:</p>

<pre><code>Key

Response

Status Code

Timestamp
</code></pre>

<p>Now every retry returns the same response.</p>

<hr />

<h1 id="example-in-nodejs-express">Example in Node.js (Express)</h1>

<pre><code class="language-javascript">app.post("/payments", async (req, res) =&gt; {
    const key = req.header("Idempotency-Key");

    const existing = await Idempotency.findOne({ key });

    if (existing) {
        return res.status(existing.status).json(existing.response);
    }

    const payment = await processPayment(req.body);

    await Idempotency.create({
        key,
        status: 201,
        response: payment,
    });

    return res.status(201).json(payment);
});
</code></pre>

<h2 id="python-fastapi">Python (FastAPI)</h2>

<pre><code class="language-python">from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

@app.post("/payments")
async def create_payment(request: Request):
    key = request.headers.get("Idempotency-Key")

    existing = await Idempotency.find_one(key=key)

    if existing:
        return JSONResponse(
            content=existing.response,
            status_code=existing.status,
        )

    body = await request.json()
    payment = await process_payment(body)

    await Idempotency.create(
        key=key,
        status=201,
        response=payment,
    )

    return JSONResponse(content=payment, status_code=201)
</code></pre>

<h2 id="c-aspnet-core">C# (ASP.NET Core)</h2>

<pre><code class="language-csharp">app.MapPost("/payments", async (
    HttpRequest request,
    IdempotencyStore store,
    PaymentService payments) =&gt;
{
    var key = request.Headers["Idempotency-Key"].ToString();

    var existing = await store.FindAsync(key);
    if (existing is not null)
    {
        return Results.Json(existing.Response, statusCode: existing.Status);
    }

    var body = await request.ReadFromJsonAsync&lt;PaymentRequest&gt;();
    var payment = await payments.ProcessAsync(body!);

    await store.CreateAsync(new IdempotencyRecord(key, 201, payment));

    return Results.Json(payment, statusCode: StatusCodes.Status201Created);
});
</code></pre>

<h2 id="go">Go</h2>

<pre><code class="language-go">func createPayment(w http.ResponseWriter, r *http.Request) {
    key := r.Header.Get("Idempotency-Key")

    existing, err := idempotency.FindOne(r.Context(), key)
    if err == nil &amp;&amp; existing != nil {
        w.WriteHeader(existing.Status)
        json.NewEncoder(w).Encode(existing.Response)
        return
    }

    var body PaymentRequest
    if err := json.NewDecoder(r.Body).Decode(&amp;body); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    payment, err := processPayment(r.Context(), body)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }

    if err := idempotency.Create(r.Context(), IdempotencyRecord{
        Key:      key,
        Status:   http.StatusCreated,
        Response: payment,
    }); err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }

    w.WriteHeader(http.StatusCreated)
    json.NewEncoder(w).Encode(payment)
}
</code></pre>

<h2 id="laravel">Laravel</h2>

<pre><code class="language-php">Route::post('/payments', function (Request $request) {
    $key = $request-&gt;header('Idempotency-Key');

    $existing = Idempotency::where('key', $key)-&gt;first();

    if ($existing) {
        return response()-&gt;json($existing-&gt;response, $existing-&gt;status);
    }

    $payment = processPayment($request-&gt;all());

    Idempotency::create([
        'key' =&gt; $key,
        'status' =&gt; 201,
        'response' =&gt; $payment,
    ]);

    return response()-&gt;json($payment, 201);
});
</code></pre>

<p>The logic is surprisingly simple.</p>

<p>The complexity comes from storing and managing the keys correctly.</p>

<hr />

<h1 id="where-should-idempotency-keys-be-stored">Where Should Idempotency Keys Be Stored?</h1>

<p>Options include:</p>

<h2 id="database">Database</h2>

<p>Best for most applications.</p>

<p>Pros:</p>

<ul>
  <li>Persistent</li>
  <li>Reliable</li>
  <li>Easy to query</li>
</ul>

<p>Cons:</p>

<ul>
  <li>Slightly slower</li>
</ul>

<hr />

<h2 id="redis">Redis</h2>

<p>Excellent for high-volume APIs.</p>

<p>Pros:</p>

<ul>
  <li>Extremely fast</li>
  <li>TTL support</li>
  <li>Easy expiration</li>
</ul>

<p>Many APIs automatically expire keys after 24 hours.</p>

<hr />

<h2 id="in-memory">In-Memory</h2>

<p>Useful only during development.</p>

<p>Not recommended for production.</p>

<p>Restarting the server loses everything.</p>

<hr />

<h1 id="common-mistakes">Common Mistakes</h1>

<h2 id="reusing-keys">Reusing Keys</h2>

<p>Every logical operation should have its own unique key.</p>

<p>Bad:</p>

<pre><code>ABC123

used today

used tomorrow
</code></pre>

<p>Good:</p>

<pre><code>New checkout

↓

Generate new UUID
</code></pre>

<hr />

<h2 id="ignoring-request-differences">Ignoring Request Differences</h2>

<p>Suppose the first request is:</p>

<pre><code>$50
</code></pre>

<p>The retry is:</p>

<pre><code>$500
</code></pre>

<p>Same key.</p>

<p>Different body.</p>

<p>The server should reject this request because the key is being reused for a different operation.</p>

<hr />

<h2 id="never-expiring-keys">Never Expiring Keys</h2>

<p>Keeping millions of old keys forever wastes storage.</p>

<p>Most APIs expire them after:</p>

<ul>
  <li>24 hours</li>
  <li>48 hours</li>
  <li>7 days</li>
</ul>

<p>depending on business requirements.</p>

<hr />

<h1 id="real-world-use-cases">Real-World Use Cases</h1>

<p>Idempotency is valuable anywhere duplicate requests could have costly consequences.</p>

<p>Examples include:</p>

<ul>
  <li>Payment processing</li>
  <li>Bank transfers</li>
  <li>Order creation</li>
  <li>Hotel reservations</li>
  <li>Flight bookings</li>
  <li>Ticket purchases</li>
  <li>Subscription billing</li>
  <li>Inventory updates</li>
  <li>Webhook processing</li>
  <li>Email sending</li>
  <li>Message queues</li>
</ul>

<p>If performing the same action twice could create an incorrect outcome, idempotency is worth considering.</p>

<hr />

<h1 id="when-you-dont-need-idempotency">When You Don’t Need Idempotency</h1>

<p>Not every endpoint needs an idempotency key.</p>

<p>For example:</p>

<pre><code>GET /posts
</code></pre>

<p>No state changes.</p>

<p>No duplicates.</p>

<p>No problem.</p>

<p>Likewise, endpoints such as:</p>

<ul>
  <li>Search</li>
  <li>Filtering</li>
  <li>Reading reports</li>
  <li>Viewing profiles</li>
</ul>

<p>are already naturally idempotent.</p>

<p>Reserve idempotency mechanisms for operations where retries could create unintended side effects.</p>

<hr />

<h1 id="final-thoughts">Final Thoughts</h1>

<p>Idempotency isn’t just an implementation detail—it’s a reliability feature.</p>

<p>In distributed systems, retries are normal. Networks are unreliable, users click buttons more than once, and clients retry requests automatically. Instead of hoping those situations never happen, design your APIs to handle them gracefully.</p>

<p>By using idempotency keys, storing responses, validating retries, and choosing the right storage strategy, you can prevent duplicate orders, repeated payments, and other costly errors.</p>

<p>A resilient API isn’t one that never receives duplicate requests.</p>

<p>It’s one that produces the correct outcome even when duplicate requests inevitably arrive.</p>

<p>The next time you design a <code>POST</code> endpoint, ask yourself:</p>

<blockquote>
  <p><strong>“What happens if this request is sent twice?”</strong></p>
</blockquote>

<p>If the answer is “something bad,” it’s probably time to add idempotency.</p>
]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="API Design" />
    
    <category term="Software Testing" />
    
  

  
    
    <category term="Idempotency" />
    
    <category term="API Design" />
    
    <category term="Software Testing" />
    
  

    <summary>Idempotency is a critical concept in API design that ensures that an operation can be performed multiple times without changing the final result beyond the first successful execution. This article explains what idempotency is, why it matters, and how to implement it in your own APIs.</summary>

  </entry>

  
  





  



  


  <entry>
    <title>Lessons Learned from Writing My First 72 Blog Posts</title>
    <link href="https://billyokeyo.dev/posts/lessons-learned-fron-writing/" rel="alternate" type="text/html" title="Lessons Learned from Writing My First 72 Blog Posts" />
    <published>2026-06-17T00:00:00+00:00</published>
  
    <updated>2026-06-17T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/lessons-learned-fron-writing/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/lessons-learned-fron-writing/"><![CDATA[<p>When I published my first blog post, I wasn’t thinking about reaching 72 articles.</p>

<p>I wasn’t thinking about traffic, search engine rankings, personal branding, or becoming a better writer. I simply wanted a place to share my thoughts, document what I was learning, and build something that belonged to me.</p>

<p>Like many developers, I started blogging because I was learning new things every day and wanted to keep track of my progress. At the time, I had no idea how much writing would teach me—not just about technology, but about consistency, communication, patience, and personal growth.</p>

<p>Now, after publishing my first 72 blog posts, I’ve learned lessons that extend far beyond blogging itself. Some lessons came from successes, while others came from mistakes and moments of frustration.</p>

<p>In this article, I want to share the most important lessons I’ve learned from publishing my first 72 blog posts.</p>

<h2 id="1-consistency-beats-perfection">1. Consistency Beats Perfection</h2>

<p>One of the biggest mistakes I made early on was trying to make every article perfect.</p>

<p>I would spend hours tweaking sentences, rewriting paragraphs, and overthinking every detail. Sometimes I delayed publishing because I felt an article wasn’t “good enough.”</p>

<p>Over time, I realized that perfection is the enemy of progress.</p>

<p>The articles that helped me grow weren’t necessarily my best articles. They were simply the articles I published.</p>

<p>Consistency creates momentum.</p>

<p>Publishing one article every week for a year is far more valuable than spending months trying to create a single masterpiece.</p>

<p>The biggest breakthrough came when I stopped chasing perfection and started focusing on showing up consistently.</p>

<h2 id="2-writing-clarifies-thinking">2. Writing Clarifies Thinking</h2>

<p>Many times, I thought I understood a topic until I tried to explain it in writing.</p>

<p>That’s when the gaps in my knowledge became obvious.</p>

<p>Writing forced me to organize my thoughts, simplify complex ideas, and identify areas where my understanding was incomplete.</p>

<p>The process taught me that learning and explaining are not the same thing.</p>

<p>If I couldn’t explain a concept clearly, I probably didn’t understand it as well as I thought.</p>

<p>This lesson made me a better learner and a better developer.</p>

<h2 id="3-nobody-reads-your-first-postsand-thats-okay">3. Nobody Reads Your First Posts—And That’s Okay</h2>

<p>One of the hardest realities for new bloggers is that almost nobody reads your early content.</p>

<p>I remember publishing articles and checking analytics repeatedly, hoping to see visitors.</p>

<p>Most of the time, there were very few.</p>

<p>At first, that felt discouraging.</p>

<p>But eventually I realized something important:</p>

<p>The purpose of your first blog posts isn’t to attract thousands of readers.</p>

<p>The purpose is to learn how to write.</p>

<p>Your first posts are practice.</p>

<p>Every article improves your skills, your confidence, and your ability to communicate.</p>

<p>The audience comes later.</p>

<h2 id="4-the-habit-matters-more-than-motivation">4. The Habit Matters More Than Motivation</h2>

<p>Motivation is unreliable.</p>

<p>Some days you’ll feel inspired.</p>

<p>Other days you’ll have no desire to write.</p>

<p>If blogging depends entirely on motivation, consistency becomes impossible.</p>

<p>One of the most valuable lessons I learned is that habits outperform motivation.</p>

<p>The writers who succeed aren’t necessarily the most talented.</p>

<p>They’re the ones who continue writing even when they don’t feel like it.</p>

<p>Creating a writing habit transformed blogging from an occasional activity into a regular part of my routine.</p>

<h2 id="5-every-post-doesnt-need-to-be-revolutionary">5. Every Post Doesn’t Need to Be Revolutionary</h2>

<p>Early in my blogging journey, I believed every article needed a unique insight or groundbreaking idea.</p>

<p>I was wrong.</p>

<p>Many of my most useful posts covered topics that had already been discussed countless times.</p>

<p>The difference was that I shared my own perspective and experience.</p>

<p>Your value doesn’t come from inventing entirely new ideas.</p>

<p>It comes from explaining ideas through your own lens.</p>

<p>There’s always someone who needs the explanation that only you can provide.</p>

<h2 id="6-writing-builds-confidence">6. Writing Builds Confidence</h2>

<p>Publishing online can feel intimidating.</p>

<p>You’re sharing your thoughts with strangers.</p>

<p>You’re exposing your ideas to criticism.</p>

<p>You’re putting your work in public.</p>

<p>At first, this can be uncomfortable.</p>

<p>But over time, each article builds confidence.</p>

<p>You become more comfortable expressing your opinions.</p>

<p>You stop worrying about being perfect.</p>

<p>You gain confidence in your ability to communicate and contribute valuable ideas.</p>

<p>That confidence eventually extends beyond blogging into other areas of life and work.</p>

<h2 id="7-blogging-is-a-long-term-game">7. Blogging Is a Long-Term Game</h2>

<p>One of the most important lessons I learned is that blogging rewards patience.</p>

<p>Results rarely happen overnight.</p>

<p>Traffic grows slowly.</p>

<p>Authority builds gradually.</p>

<p>Opportunities emerge unexpectedly.</p>

<p>Many people quit because they expect immediate results.</p>

<p>The reality is that blogging is similar to investing.</p>

<p>Small contributions made consistently over time eventually compound into significant outcomes.</p>

<p>The key is staying committed long enough to experience those benefits.</p>

<h2 id="8-publishing-teaches-more-than-consuming">8. Publishing Teaches More Than Consuming</h2>

<p>Before I started blogging, I spent most of my time consuming content.</p>

<p>I watched tutorials.</p>

<p>I read articles.</p>

<p>I followed courses.</p>

<p>While these activities were helpful, publishing taught me far more.</p>

<p>Creating content forces you to think deeply, research thoroughly, and communicate clearly.</p>

<p>It transforms you from a consumer into a creator.</p>

<p>That shift changed the way I learn forever.</p>

<h2 id="9-your-blog-becomes-a-personal-archive">9. Your Blog Becomes a Personal Archive</h2>

<p>One unexpected benefit of blogging is having a permanent record of your journey.</p>

<p>Looking back at my older articles shows how much I’ve grown.</p>

<p>I can see:</p>

<ul>
  <li>How my thinking evolved.</li>
  <li>What I was learning.</li>
  <li>Problems I was solving.</li>
  <li>Mistakes I made.</li>
</ul>

<p>The blog becomes more than a collection of articles.</p>

<p>It becomes a timeline of personal growth.</p>

<h2 id="10-small-efforts-compound-over-time">10. Small Efforts Compound Over Time</h2>

<p>When I published my first article, it felt insignificant.</p>

<p>The same was true for my second, third, and tenth article.</p>

<p>But by the time I reached fifty posts, those small efforts had accumulated into something meaningful.</p>

<p>Fifty articles represent:</p>

<ul>
  <li>Hundreds of hours of learning.</li>
  <li>Hundreds of hours of writing.</li>
  <li>Dozens of lessons learned.</li>
  <li>A growing body of work.</li>
</ul>

<p>This reminded me that success is rarely the result of a single big action.</p>

<p>It’s usually the result of many small actions repeated consistently over time.</p>

<h2 id="11-the-real-reward-isnt-traffic">11. The Real Reward Isn’t Traffic</h2>

<p>When people think about blogging success, they often think about page views, followers, and analytics.</p>

<p>Those metrics matter, but they’re not the greatest reward.</p>

<p>The greatest reward is who you become during the process.</p>

<p>Blogging made me:</p>

<ul>
  <li>A better writer.</li>
  <li>A better learner.</li>
  <li>A better communicator.</li>
  <li>A more disciplined creator.</li>
  <li>A more thoughtful developer.</li>
</ul>

<p>Those benefits are far more valuable than any traffic number.</p>

<h2 id="looking-ahead">Looking Ahead</h2>

<p>Reaching 72 blog posts feels like an important milestone, but it also feels like the beginning.</p>

<p>There’s still so much to learn.</p>

<p>So many topics to explore.</p>

<p>So many experiences to share.</p>

<p>The goal isn’t simply to publish more articles.</p>

<p>The goal is to continue learning, improving, and documenting the journey.</p>

<p>If the first 72 posts taught me anything, it’s that growth comes from consistency, curiosity, and the willingness to keep showing up.</p>

<h2 id="conclusion">Conclusion</h2>

<p>Publishing my first 72 blog posts taught me lessons that extend far beyond writing.</p>

<p>It taught me patience when growth was slow.</p>

<p>It taught me discipline when motivation disappeared.</p>

<p>It taught me confidence when self-doubt appeared.</p>

<p>Most importantly, it taught me that meaningful progress is often the result of small actions repeated consistently over time.</p>

<p>If you’re thinking about starting a blog, my advice is simple:</p>

<p>Start now.</p>

<p>Don’t wait until you’re an expert.</p>

<p>Don’t wait until everything is perfect.</p>

<p>Write your first post.</p>

<p>Then write your second.</p>

<p>Then your third.</p>

<p>One day, you’ll look back and realize those small steps created something much bigger than you ever imagined.</p>

<p>I did an article about <a href="https://blogs.innova.co.ke/importance-of-writing-for-devs/">importance of writing for developers</a> which you can check out.</p>
]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="Writing" />
    
    <category term="Blogging" />
    
    <category term="Career" />
    
  

  
    
    <category term="writing" />
    
    <category term="blogging" />
    
    <category term="career advice" />
    
  

    <summary>Writing articles has made me a better developer. This post breaks down the mindset and process of effective writing, with practical steps and real examples to help you become a better problem solver. I wrote my first blog post in 2023 and have written 72 blog posts since then.</summary>

  </entry>

  
  





  



  


  <entry>
    <title>Debugging Is a Skill Nobody Teaches You</title>
    <link href="https://billyokeyo.dev/posts/debugging-is-a-skill-noone-teaches-you/" rel="alternate" type="text/html" title="Debugging Is a Skill Nobody Teaches You" />
    <published>2026-05-04T00:00:00+00:00</published>
  
    <updated>2026-05-04T00:00:00+00:00</updated>
  
    <id>https://billyokeyo.dev/posts/debugging-is-a-skill-noone-teaches-you/</id>
    <content type="html" xml:base="https://billyokeyo.dev/posts/debugging-is-a-skill-noone-teaches-you/"><![CDATA[<blockquote>
  <p><em>You’ve been staring at the same bug for 2 hours.</em>
You’ve restarted the server. Cleared cache. Added random <code>console.log</code>s.
Somehow… it still doesn’t work.</p>
</blockquote>

<p>At some point, you stop coding and start guessing.</p>

<p><img src="https://media.giphy.com/media/3o7btPCcdNniyf0ArS/giphy.gif" alt="Frustrated Coding" /></p>

<p>And that’s the real problem.</p>

<blockquote>
  <p><strong>The issue isn’t the bug.
It’s that nobody actually teaches debugging as a skill.</strong></p>
</blockquote>

<hr />

<h2 id="the-way-most-developers-debug">The Way Most Developers Debug</h2>

<p>Let’s be honest. Most of us learned debugging like this:</p>

<ul>
  <li>Sprinkle <code>console.log</code> everywhere</li>
  <li>Change random lines and hope something works</li>
  <li>Copy-paste error messages into Google</li>
  <li>Restart everything “just in case”</li>
</ul>

<p><img src="https://media.giphy.com/media/13HgwGsXF0aiGY/giphy.gif" alt="Random Typing" /></p>

<p>It <em>sometimes</em> works.</p>

<p>But it’s slow, frustrating, and unreliable.</p>

<p>It’s not debugging.</p>

<p>It’s <strong>trial and error disguised as progress</strong>.</p>

<hr />

<h2 id="what-debugging-actually-is">What Debugging Actually Is</h2>

<p>Here’s the mindset shift that changes everything:</p>

<blockquote>
  <p><strong>Debugging is not about fixing code.
It’s about finding where your mental model diverges from reality.</strong></p>
</blockquote>

<p>You <em>think</em> the system works one way.</p>

<p>Reality says otherwise.</p>

<p>Your job is to <strong>close that gap</strong>.</p>

<hr />

<h2 id="the-debugging-mindset">The Debugging Mindset</h2>

<p>Before tools, before techniques, this is what matters most.</p>

<h3 id="1-assume-your-assumptions-are-wrong">1. Assume Your Assumptions Are Wrong</h3>

<p>If something doesn’t work, at least one thing you believe is false.</p>

<p>Your job is to find it.</p>

<hr />

<h3 id="2-narrow-the-problem-space">2. Narrow the Problem Space</h3>

<p>Bad debugging:</p>

<blockquote>
  <p>“Something is wrong with the app”</p>
</blockquote>

<p>Good debugging:</p>

<blockquote>
  <p>“The issue happens only when this function runs after login”</p>
</blockquote>

<p><img src="https://media.giphy.com/media/l0IylOPCNkiqOgMyA/giphy.gif" alt="Analyzing Clues" /></p>

<hr />

<h3 id="3-reproduce-before-fixing">3. Reproduce Before Fixing</h3>

<p>If you can’t reliably reproduce the bug, you don’t understand it.</p>

<p>And if you don’t understand it, your fix is luck—not skill.</p>

<hr />

<h3 id="4-one-change-at-a-time">4. One Change at a Time</h3>

<p>If you change 5 things and it works…
which one fixed it?</p>

<p>You don’t know.</p>

<p>That’s how bugs come back later.</p>

<hr />

<h3 id="5-understand-before-you-patch">5. Understand Before You Patch</h3>

<p>Quick fixes feel good.</p>

<p>Understanding the root cause makes you dangerous (in a good way).</p>

<hr />

<h2 id="a-repeatable-debugging-process">A Repeatable Debugging Process</h2>

<p>This is where things become practical.</p>

<hr />

<h3 id="step-1-reproduce-the-bug"><strong>Step 1: Reproduce the Bug</strong></h3>

<p>Make it happen consistently.</p>

<pre><code class="language-bash">Click button → error appears  
Refresh → still happens  
Different browser → still happens
</code></pre>

<p>If it’s inconsistent, your first task is to <strong>find the pattern</strong>.</p>

<hr />

<h3 id="step-2-define-expected-vs-actual"><strong>Step 2: Define Expected vs Actual</strong></h3>

<p>Write it down clearly.</p>

<pre><code class="language-text">Expected: API returns user data  
Actual: API returns empty array
</code></pre>

<p>This step alone eliminates confusion.</p>

<hr />

<h3 id="step-3-isolate-the-problem"><strong>Step 3: Isolate the Problem</strong></h3>

<p>Shrink the scope.</p>

<ul>
  <li>Comment out unrelated code</li>
  <li>Remove layers (UI → API → DB)</li>
  <li>Test pieces independently</li>
</ul>

<p>Think of it like this:</p>

<pre><code>[ UI ] → [ API ] → [ Database ]

Which layer is lying?
</code></pre>

<hr />

<h3 id="step-4-form-a-hypothesis"><strong>Step 4: Form a Hypothesis</strong></h3>

<p>Be explicit:</p>

<blockquote>
  <p>“I think the API is returning empty data because the query filter is wrong.”</p>
</blockquote>

<p>Now you’re not guessing—you’re <strong>testing a theory</strong>.</p>

<hr />

<h3 id="step-5-test-the-hypothesis"><strong>Step 5: Test the Hypothesis</strong></h3>

<p>Use targeted tools:</p>

<ul>
  <li>Logs</li>
  <li>Breakpoints</li>
  <li>Network inspector</li>
</ul>

<p><img src="https://media.giphy.com/media/26ufdipQqU2lhNA4g/giphy.gif" alt="Experimenting" /></p>

<p>Example:</p>

<pre><code class="language-js">console.log("User ID:", userId)
</code></pre>

<p>But intentional—not random.</p>

<hr />

<h3 id="step-6-fix-and-verify"><strong>Step 6: Fix and Verify</strong></h3>

<p>Fix it.</p>

<p>Then confirm:</p>

<ul>
  <li>Does it work in all cases?</li>
  <li>Did you break something else?</li>
</ul>

<p><img src="https://media.giphy.com/media/26gsspfbt1HfVQ9va/giphy.gif" alt="Calm Focus" /></p>

<hr />

<h3 id="step-7-understand-the-root-cause"><strong>Step 7: Understand the Root Cause</strong></h3>

<p>This is where most devs stop too early.</p>

<p>Don’t just fix it—<strong>explain it</strong>:</p>

<blockquote>
  <p>“The bug happened because the state updated asynchronously, and we read it too early.”</p>
</blockquote>

<p>Now you’ve learned something reusable.</p>

<hr />

<h2 id="real-example-the-api-is-broken-but-its-not">Real Example: “The API Is Broken” (But It’s Not)</h2>

<p>Let’s walk through a real scenario.</p>

<hr />

<h3 id="the-bug">The Bug</h3>

<blockquote>
  <p>Frontend shows: <strong>No data available</strong></p>
</blockquote>

<hr />

<h3 id="initial-assumption">Initial Assumption</h3>

<blockquote>
  <p>“The API is broken.”</p>
</blockquote>

<hr />

<h3 id="step-1-check-network-tab">Step 1: Check Network Tab</h3>

<p>You open DevTools → Network:</p>

<p>API returns correct data</p>

<p>So… not the API.</p>

<hr />

<h3 id="step-2-check-state">Step 2: Check State</h3>

<pre><code class="language-js">console.log(data)
</code></pre>

<p>It logs:</p>

<pre><code class="language-js">[]
</code></pre>

<p>Empty array.</p>

<hr />

<h3 id="step-3-trace-the-flow">Step 3: Trace the Flow</h3>

<pre><code class="language-js">useEffect(() =&gt; {
  fetchData()
}, [])
</code></pre>

<p>Inside <code>fetchData</code>:</p>

<pre><code class="language-js">setData(response.data)
console.log(data) // still empty
</code></pre>

<hr />

<h3 id="the-problem">The Problem</h3>

<p>React state updates are <strong>asynchronous</strong>.</p>

<p>You’re logging <strong>before state updates</strong>.</p>

<hr />

<h3 id="the-fix">The Fix</h3>

<pre><code class="language-js">useEffect(() =&gt; {
  fetchData()
}, [])

useEffect(() =&gt; {
  console.log(data)
}, [data])
</code></pre>

<h2><img src="https://media.giphy.com/media/111ebonMs90YLu/giphy.gif" alt="Victory" /></h2>

<h3 id="the-lesson">The Lesson</h3>

<blockquote>
  <p>The bug wasn’t in the API.
It was in your mental model of how state updates work.</p>
</blockquote>

<hr />

<h2 id="tools-that-actually-help">Tools That Actually Help</h2>

<p>Not everything is about tools—but the right ones matter.</p>

<hr />

<h3 id="1-browser-devtools-underrated-powerhouse">1. Browser DevTools (Underrated Powerhouse)</h3>

<ul>
  <li><strong>Network tab</strong> → verify API calls</li>
  <li><strong>Console</strong> → inspect runtime values</li>
  <li><strong>Application tab</strong> → check storage</li>
</ul>

<hr />

<h3 id="2-breakpoints-game-changer">2. Breakpoints (Game Changer)</h3>

<p>Instead of spamming logs:</p>

<p>Pause execution and inspect state <em>live</em></p>

<hr />

<h3 id="3-intentional-logging">3. Intentional Logging</h3>

<p>Bad:</p>

<pre><code class="language-js">console.log("here")
</code></pre>

<p>Good:</p>

<pre><code class="language-js">console.log("User after login:", user)
</code></pre>

<hr />

<h3 id="4-stack-traces">4. Stack Traces</h3>

<p>Read them.</p>

<p>They literally tell you:</p>

<ul>
  <li>Where the error happened</li>
  <li>What triggered it</li>
</ul>

<hr />

<h3 id="5-rubber-duck-debugging">5. Rubber Duck Debugging</h3>

<p>Explain the bug out loud.</p>

<p>Yes, seriously.</p>

<p>You’ll often solve it mid-explanation.</p>

<hr />

<pre><code>Problem → Hypothesis → Test → Learn → Repeat
</code></pre>

<hr />

<h2 id="common-debugging-traps">Common Debugging Traps</h2>

<p>Avoid these and you’ll already be ahead of most devs:</p>

<hr />

<h3 id="fixing-symptoms-instead-of-causes">Fixing Symptoms Instead of Causes</h3>

<p>You silence the error… but the bug is still there.</p>

<hr />

<h3 id="changing-too-many-things-at-once">Changing Too Many Things at Once</h3>

<p>Now you don’t know what worked.</p>

<hr />

<h3 id="ignoring-error-messages">Ignoring Error Messages</h3>

<p>The error is literally telling you what’s wrong.</p>

<p>Read it.</p>

<hr />

<h3 id="assuming-the-bug-is-weird">Assuming the Bug Is “Weird”</h3>

<p>It’s almost never weird.</p>

<p>It’s misunderstood.</p>

<hr />

<h3 id="it-works-on-my-machine">“It Works on My Machine”</h3>

<p>This is not a flex.</p>

<p>It’s a clue.</p>

<hr />

<h2 id="a-better-mental-model">A Better Mental Model</h2>

<pre><code>Expectation ≠ Reality  
        ↓  
Investigate the gap
</code></pre>

<p>That’s debugging.</p>

<hr />

<h2 id="final-thought">Final Thought</h2>

<blockquote>
  <p>The best developers aren’t the ones who write perfect code.
They’re the ones who can <strong>quickly understand why things break</strong>.</p>
</blockquote>

<p>Debugging isn’t a side skill.</p>

<p>It <em>is</em> the job.</p>

]]></content>
    <author>
      <name>Billy Okeyo</name>
    </author>

  
    
    <category term="Programming" />
    
    <category term="Software Development" />
    
    <category term="Career" />
    
  

  
    
    <category term="debugging" />
    
    <category term="software development" />
    
    <category term="programming" />
    
    <category term="career advice" />
    
  

    <summary>Debugging is a critical skill that many developers struggle with. This post breaks down the mindset and process of effective debugging, with practical steps and real examples to help you become a better problem solver.</summary>

  </entry>

</feed>