DEV Community: Bishoy Bishai

Rethinking Redux: Enhancing Your State Management Strategy

Bishoy Bishai — Sat, 04 Jul 2026 11:56:08 +0000

Rethinking Redux: Enhancing Your State Management Strategy

Remember the early days of Redux? The thrill of predictable state, the robust debugging tools, the beautiful unidirectional data flow. It was a revelation! But let's be honest, it often came with a side of boilerplate fatigue. I've been there, staring at a new feature, dreading the creation of yet another action type, action creator, reducer case, and maybe a thunk or two. It was powerful, yes, but often felt like a lot of overhead for even simple state changes.

For many professional developers, this memory sticks. It's why I've seen teams hesitant to adopt Redux, or quick to dismiss it in favor of simpler (sometimes too simple) alternatives. The problem isn't Redux itself; it's that the conversation often gets stuck in the past. We're still talking about Redux like it's 2017, missing out on how dramatically it has evolved.

Here's the thing: Redux, especially with the advent of Redux Toolkit (RTK), isn't just surviving; it's thriving. It's transformed from a potentially cumbersome library into an incredibly ergonomic and powerful tool that drastically enhances our state management strategy. "Rethinking Redux" isn't about abandoning it, but about embracing its modern form and applying it strategically.

Why This Matters: Beyond Boilerplate Reduction

In my experience, modern Redux offers more than just less typing. It brings:

Opinionated Best Practices: RTK bakes in best practices, guiding you towards maintainable and scalable code.
Type Safety (with TypeScript): unparalleled confidence in your state shape and logic.
Performance Optimizations: Tools like Reselect are easier to integrate for memoized selectors.
Developer Experience: Less cognitive load, faster feature development, and more enjoyable coding.

Let's dive into how RTK makes this happen.

The Modern Redux Workflow: A Breath of Fresh Air

At the heart of modern Redux is configureStore and createSlice from Redux Toolkit. These two utilities alone obliterate most of the historical boilerplate.

Let's imagine we're building a simple counter feature.

1. Defining Your Slice with `createSlice`

Instead of separate action types, action creators, and reducers, createSlice bundles them all into one neat package.

// features/counter/counterSlice.ts
import { createSlice, PayloadAction } from '@reduxjs/toolkit';

interface CounterState {
  value: number;
}

const initialState: CounterState = {
  value: 0,
};

export const counterSlice = createSlice({
  name: 'counter',
  initialState,
  reducers: {
    increment: (state) => {
      // Redux Toolkit allows us to write "mutating" logic in reducers;
      // it doesn't actually mutate the state because it uses Immer library,
      // which detects changes to a "draft state" and produces a brand new
      // immutable state based off those changes.
      state.value += 1;
    },
    decrement: (state) => {
      state.value -= 1;
    },
    incrementByAmount: (state, action: PayloadAction<number>) => {
      state.value += action.payload;
    },
  },
});

export const { increment, decrement, incrementByAmount } = counterSlice.actions;

export default counterSlice.reducer;

Look at that! In one file, we've defined our initial state, our actions, and our reducers. The name property automatically generates action types like counter/increment. RTK handles all the immutability magic under the hood using Immer, so you can write seemingly "mutating" logic without worry. This is a huge win for readability and reducing common bugs.

2. Configuring Your Store

Setting up the store is equally streamlined with configureStore.

// app/store.ts
import { configureStore } from '@reduxjs/toolkit';
import counterReducer from '../features/counter/counterSlice';

export const store = configureStore({
  reducer: {
    counter: counterReducer,
  },
});

// Infer the `RootState` and `AppDispatch` types from the store itself
export type RootState = ReturnType<typeof store.getState>;
// Inferred type: {counter: CounterState}
export type AppDispatch = typeof store.dispatch;

configureStore automatically sets up Redux DevTools, redux-thunk (for async logic), and other sensible defaults. It's truly a "batteries included" approach.

3. Using in Your React Components

With React Redux hooks, connecting your components is a breeze.

```typescript jsx
// features/counter/Counter.tsx
import React from 'react';
import { useSelector, useDispatch } from 'react-redux';
import { RootState, AppDispatch } from '../../app/store'; // For type safety
import { increment, decrement, incrementByAmount } from './counterSlice';

function Counter() {
// The 'as any' is a temporary hack if not fully typed yet, but with TS, it's inferred
const count = useSelector((state: RootState) => state.counter.value);
const dispatch = useDispatch(); // Dispatch also typed

return (

Count: {count}

dispatch(increment())}>Increment
dispatch(decrement())}>Decrement
dispatch(incrementByAmount(5))}>Increment by 5

);
}

export default Counter;




See how clean that is? With TypeScript, you get full type inference and safety from your store's root state all the way down to your selectors and dispatched actions. This is invaluable in larger applications.

## Insights from the Trenches: What Most Tutorials Miss

1.  **It's Not All or Nothing:** You don't need to put *all* your state in Redux. In my experience, a common pitfall is over-globalizing. If a piece of state is only relevant to a single component and its children, React's `useState` or `useReducer` (or even the Context API for slightly broader, but still localized, concerns) is often a better, simpler choice. Redux shines for truly global, application-wide, or frequently shared state. Be strategic.
2.  **Selectors Are Your Superpower:** Beyond just getting state, well-crafted selectors (especially memoized ones using `createSelector` from Reselect, which integrates beautifully with RTK) are crucial for performance. They prevent unnecessary re-renders and can derive complex data efficiently. Don't fetch raw state and compute derived values in your components; push that logic into selectors.
3.  **Async Logic with `createAsyncThunk`:** Forget the old `redux-thunk` boilerplate. `createAsyncThunk` handles pending, fulfilled, and rejected states for asynchronous operations automatically, again reducing boilerplate and improving type safety. It's a game-changer for API calls.



    ```typescript
    // Example with createAsyncThunk
    import { createSlice, createAsyncThunk } from '@reduxjs/toolkit';
    import { fetchUserById } from './api'; // Imagine this is your API call

    export const fetchUser = createAsyncThunk(
      'users/fetchById',
      async (userId: number) => {
        const response = await fetchUserById(userId);
        return response.data; // The payload of the fulfilled action
      }
    );

    const usersSlice = createSlice({
      name: 'users',
      initialState: { entities: {}, loading: 'idle' },
      reducers: {
        // standard reducer logic here
      },
      extraReducers: (builder) => {
        builder
          .addCase(fetchUser.pending, (state, action) => {
            state.loading = 'pending';
          })
          .addCase(fetchUser.fulfilled, (state, action) => {
            state.loading = 'idle';
            state.entities[action.payload.id] = action.payload;
          })
          .addCase(fetchUser.rejected, (state, action) => {
            state.loading = 'idle';
            // handle error
          });
      },
    });
    ```


    This pattern ensures consistent handling of async states across your application.

## Common Pitfalls and How to Avoid Them

*   **Not using Redux Toolkit:** Seriously, if you're still writing Redux the old way, you're missing out. RTK is *the* recommended way to use Redux.
*   **Anemic Reducers:** If your reducers are just setting single fields directly from action payloads without any logic, you might be dispatching too many specific actions. Sometimes, a more generic action with a richer payload (or even local component state) is better.
*   **Poorly Structured State:** A well-normalized state shape (similar to a database structure, using IDs for entities) is key for performance and maintainability, especially with many-to-many relationships. `createEntityAdapter` from RTK helps immensely with this.
*   **Forgetting Memoization:** If selectors are recalculating expensive values on every render, you're losing performance. Use `createSelector` for derived data.

## Moving Forward: Redux, Reimagined

My journey with Redux has been long and, at times, challenging. But witnessing its evolution, particularly with Redux Toolkit, has completely reshaped my perspective. It's no longer just a state container; it's a comprehensive state management framework that offers unparalleled power, predictability, and a genuinely delightful developer experience when used correctly.

So, if you or your team have been reluctant to embrace Redux, or if you're struggling with a legacy setup, I urge you to take another look. Dive into Redux Toolkit, appreciate the patterns it enforces, and understand *when* to reach for it. Your state management strategy, and your sanity, will thank you.

---

**✨ Let's keep the conversation going!**

If you found this interesting, I'd love for you to check out more of my work or just drop in to say hello.

✍️ **Read more on my blog:** [bishoy-bishai.github.io](https://bishoy-bishai.github.io/portfolio/blog/)  
☕ **Let's chat on LinkedIn:** [linkedin.com/in/bishoybishai](https://www.linkedin.com/in/bishoybishai/)

---

React Navigation Explained

Bishoy Bishai — Fri, 03 Jul 2026 12:30:00 +0000

Missing

✨ Let's keep the conversation going!

If you found this interesting, I'd love for you to check out more of my work or just drop in to say hello.

✍️ Read more on my blog: bishoy-bishai.github.io

☕ Let's chat on LinkedIn: linkedin.com/in/bishoybishai

Why rour AI agent struggles with full-stack apps

Bishoy Bishai — Thu, 02 Jul 2026 12:31:53 +0000

Why Our AI Agent Still Stumbles on Full-Stack Apps

We've all been there. You're riding high on the AI hype, picturing your agent effortlessly spinning up features, leaving you free for higher-level architectural decisions. You feed it a prompt like, "Build me a simple user profile page with authentication, connected to a database, using Next.js and TypeScript." You hit enter, grab a coffee, and expect magic.

More often than not, what you get back is… well, it's something. It might be syntactically correct, perhaps even impressive in parts. But when you try to integrate it, to make the pieces talk to each other harmoniously, it often feels like trying to connect a square peg to a round hole. The agent struggles, and frankly, so do we trying to fix its output.

The Seams, Not Just the Parts: Why Full-Stack is More Than Sum of Its Halves

In my experience, AI agents, especially Large Language Models, are fantastic at generating code for isolated problems. Need a React component? A SQL query? A utility function? They'll often nail it. But a full-stack application isn't just a collection of frontend, backend, and database parts. It's the intricate, often implicit, contracts between them.

Think about a modern Next.js application. It’s a beautifully complex dance:

Server Components vs. Client Components: This paradigm shift fundamentally changes where state lives, where data is fetched, and how interactivity is handled. An AI might generate a useState hook inside a Server Component, completely missing the architectural intent.
Data Fetching Strategies: getServerSideProps, getStaticProps, route handlers, fetch directly in Server Components – each has specific implications for caching, performance, and where your data lives at runtime. An AI might pick an inefficient or incorrect strategy based on a simplified prompt.
Type Safety Across Boundaries: TypeScript is a lifesaver, but defining types that perfectly mirror your database schema, API responses, and frontend state requires a deep, semantic understanding of your entire data flow. An AI can generate any or generic types, sidestepping the real challenge.
Environment Variables and Deployment: Knowing which variables belong where, how to secure them, and how your build process interacts with your hosting environment is crucial. These aren't just lines of code; they're operational concerns.

A Deeper Dive: Where the AI Agent's Logic Crumbles (with Next.js Examples)

Let's take a common scenario: building an API route in Next.js that interacts with a database, and then consuming that data in a Server Component.

An AI agent might generate something like this for an API route:

// pages/api/users.ts - OLD pages router example, AI might still use this
import type { NextApiRequest, NextApiResponse } from 'next';

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method === 'GET') {
    // In a real app, this would query a database
    const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
    res.status(200).json(users);
  } else {
    res.setHeader('Allow', ['GET']);
    res.status(405).end(`Method ${req.method} Not Allowed`);
  }
}

And then for the frontend, it might try to use it:

// pages/users.tsx - Also pages router
import { useState, useEffect } from 'react';

interface User {
  id: number;
  name: string;
}

function UsersPage() {
  const [users, setUsers] = useState<User[]>([]);

  useEffect(() => {
    fetch('/api/users')
      .then(res => res.json())
      .then(data => setUsers(data));
  }, []);

  return (
    <div>
      <h1>Users</h1>
      <ul>
        {users.map(user => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </div>
  );
}

export default UsersPage;

This looks fine, but it’s using the older Pages Router paradigm. With the App Router, we'd prefer Route Handlers and fetching directly in a Server Component for better performance and maintainability.

A more modern App Router approach the AI should consider:

// app/api/users/route.ts - Route Handler (Next.js App Router)
import { NextResponse } from 'next/server';

export async function GET() {
  // Simulate fetching from a database
  const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
  return NextResponse.json(users);
}

// app/users/page.tsx - Server Component (Next.js App Router)
interface User {
  id: number;
  name: string;
}

async function getUsers(): Promise<User[]> {
  const res = await fetch(`${process.env.NEXT_PUBLIC_BASE_URL}/api/users`, {
    cache: 'no-store' // Or 'force-cache' depending on requirements
  });
  if (!res.ok) {
    // This will activate the closest `error.js` Error Boundary
    throw new Error('Failed to fetch data');
  }
  return res.json();
}

export default async function UsersPage() {
  const users = await getUsers(); // Data fetching directly in Server Component

  return (
    <div>
      <h1>Users</h1>
      <ul>
        {users.map(user => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </div>
  );
}

The AI might get the syntax of the new App Router right if prompted specifically, but understanding when to use async/await directly in a Server Component versus a Client Component with useEffect, or correctly inferring caching strategies, is where it often struggles. It’s the architectural context that's missing.

Insights from the Trenches: What Most Tutorials Miss (and AIs Can't Grasp)

I've found that AI agents excel at pattern matching. They've devoured vast amounts of code and can regurgitate common solutions. But full-stack development is less about common solutions and more about fitting bespoke pieces into a holistic, evolving system.

Implicit Context is King: We, as developers, instinctively understand that a database connection string shouldn't be hardcoded on the frontend, or that certain API endpoints require authentication. These are implicit rules an AI agent often misses without explicit, detailed prompting that verges on writing the code for it anyway.
Architectural Intent: Why did we choose a specific database? Why is this microservice separate? Why are we using server-side rendering here? These decisions are driven by performance, scalability, security, and team expertise – factors an AI agent cannot truly comprehend. It sees syntax; we see a system designed for a purpose.
The "Last Mile" Problem: An AI can get you 80% there on many individual components. But that final 20% – the precise integration, the subtle bug fixes caused by an unexpected edge case in data flow, the performance tuning, the testing – that's where the real complexity (and value) of a human developer lies.

Common Pitfalls and How to Bridge the Gap

Non-Idiomatic Code: AI often generates code that works but isn't "idiomatic" for the framework or language – it might use older patterns, less efficient approaches, or simply not fit existing code conventions. This leads to higher maintenance costs.
Security Vulnerabilities: Without a deep understanding of context, an AI might generate code susceptible to SQL injection, XSS, or expose sensitive data. It prioritizes functionality over robust security, by default.
Performance Anti-Patterns: Incorrect data fetching, over-fetching, or poor caching strategies can kill performance. An AI needs explicit guidance on these often project-specific concerns.
Ignoring Developer Experience (DX): Human developers care deeply about code readability, maintainability, and clear error handling. AI-generated code, while functional, can often be a tangled mess that's hard for another human to pick up.

So, What's the Play?

The goal isn't to replace developers with AI agents, but to augment them. I've found that treating AI agents as hyper-efficient, highly knowledgeable assistants works best.

Define the Architecture: Outline the major components, data flow, and technologies yourself.
Break Down Tasks: Give the AI specific, isolated tasks (e.g., "Write a TypeScript interface for a user profile," "Generate a Next.js App Router API handler for creating a user," "Create a React Client Component for a user form that calls this API").
Provide Context: Feed it snippets of your existing codebase, your tsconfig.json, your package.json, and explicit instructions on desired patterns (e.g., "Use Zod for schema validation," "Integrate with our custom error handling utility").
Review Critically: Always, always review the generated code for correctness, security, performance, and adherence to your project's standards.

Full-stack development, with its myriad layers and implicit knowledge, remains a deeply human endeavor. AI agents are incredible tools to accelerate parts of the process, but the architect, the integrator, the one who truly understands the holistic system, is still very much us. And honestly, that's a good thing. It keeps our jobs exciting and challenging.

✨ Let's keep the conversation going!

If you found this interesting, I'd love for you to check out more of my work or just drop in to say hello.

✍️ Read more on my blog: bishoy-bishai.github.io

☕ Let's chat on LinkedIn: linkedin.com/in/bishoybishai

Debugging React: From Taking a Deep Breath to Finding the Root Cause

Bishoy Bishai — Wed, 01 Jul 2026 14:06:48 +0000

Debugging React: From Taking a Deep Breath to Finding the Root Cause

We've all been there. You've just pushed what you thought was a brilliant new feature, you refresh the page, and... nothing. Or worse, something completely unexpected. That sinking feeling in your stomach, the sudden urge to just console.log everything. Debugging, especially in a dynamic framework like React, can feel like trying to find a needle in a haystac k while blindfolded.

But here's the thing: debugging isn't a dark art. It's a skill, a mindset, and frankly, a huge part of what makes us effective developers. In my experience, the most impactful shift isn't just knowing the tools, but cultivating a systematic, almost zen-like approach. It starts with that deep breath, and ends with a solid understanding of why something broke, not just what broke.

Why Debugging Matters More Than You Think

Sure, fixing bugs is obvious. But effective debugging is about more than just patching a hole. It's about understanding the subtle nuances of your application's architecture, its state management, and how React truly works under the hood. It’s an opportunity to learn, to refine your mental model of the system, and to prevent similar issues down the line. Over the years, I've found that some of my deepest insights into React came from wrestling with the most stubborn bugs.

The Deep Breath: Establishing a Systematic Approach

Before you frantically pepper your codebase with console.log, take that deep breath. Seriously. Close the editor for 30 seconds. This simple act can break the "panic loop" and allow you to approach the problem with a clearer head.

Once you've reset, here’s a flow that's served me well:

Reproduce the Bug: Can you consistently make it happen? If not, you're chasing ghosts. Document the steps.
Localize the Problem: Where is the bug most likely occurring? Is it a UI issue? Data issue? Interaction?
Hypothesize: Based on your knowledge, what do you think is happening? This guides your investigation.
Test Your Hypothesis: Use your tools strategically.
Fix and Verify: Make the change, and then rigorously test to ensure it's truly fixed and hasn't introduced new regressions.

Tools of the Trade: Beyond `console.log`

console.log is the trusty hammer, but sometimes you need a whole toolkit.

1. React DevTools: Your Best Friend

If you're not intimately familiar with React DevTools, stop reading and go explore them. Seriously, it's a game-changer.

Components Tab: See your entire component tree. Inspect props, state, and context for any component at any point in time. This is invaluable for understanding data flow.
- Real-world insight: I once spent an hour trying to figure out why a child component wasn't updating. DevTools showed me that while the parent's state was correct, the prop being passed down was subtly different due to a memoization issue higher up the tree. Boom.
Profiler Tab: Struggling with performance? The Profiler helps you visualize render times, identify unnecessary re-renders, and pinpoint bottlenecks.
Hooks Tab: For functional components, this tab lets you inspect the values of useState, useRef, useMemo, etc., right within the DevTools.

2. Browser DevTools: Network, Console, Sources

Don't forget the browser's native tools.

Network Tab: Is your API call failing? Is the payload what you expect?
Console Tab: More than just console.log output. Watch for uncaught errors, warnings, and deprecation notices that React thoughtfully provides.
Sources Tab: Set breakpoints, step through your code, inspect variables. This is the ultimate tool for deep dives when your hypothesis requires granular inspection.

3. Understanding React's Core Concepts

The most powerful debugging tool is a deep understanding of React itself.

State vs. Props: This seems basic, but so many issues stem from mismanaging what state belongs where, and how props flow. Remember: props are immutable within a component, state is internal and mutable (via setState).

Component Lifecycle: When does a component mount, update, or unmount? When does useEffect run? Why is understanding dependencies crucial?

// Pitfall: Forgetting dependencies, leading to stale closures
useEffect(() => {
  const timer = setInterval(() => {
    // If 'count' is not in dependency array,
    // this 'count' will be the initial value,
    // leading to a stale closure and incorrect updates.
    console.log('Count:', count);
  }, 1000);
  return () => clearInterval(timer);
}, []); // Missing 'count' here!

This useEffect will only see the initial count value if count isn't in the dependency array, creating a common bug where state appears to be "stale."

Reconciliation: When does React decide to re-render? When does it skip? Understanding memoization (React.memo, useMemo, useCallback) can help debug performance issues.

Common Pitfalls and How to Avoid Them

Mutating State Directly: A classic. React's change detection relies on immutability. If you modify an object or array directly, React won't detect the change, and your component won't re-render.

// Bad: Directly mutating state
const [items, setItems] = useState(['apple', 'banana']);
const addItem = (newItem: string) => {
  items.push(newItem); // DANGER! Mutating state directly
  setItems(items); // React won't see a "new" array reference
};

// Good: Creating a new array/object reference
const addItemSafe = (newItem: string) => {
  setItems(prevItems => [...prevItems, newItem]); // Correct: new array
};

Incorrect useEffect Dependencies: As shown above, forgetting dependencies or including too many (causing unnecessary re-runs) is a frequent source of bugs. Use eslint-plugin-react-hooks – it catches this automatically!
Over-reliance on console.log: It's useful, but without a hypothesis, it becomes spam. You end up staring at a wall of text, missing the actual insights. Use it to test a specific theory.
Ignoring Warnings: React and your browser are trying to help you! Don't dismiss those yellow warnings in the console; they often point directly to potential bugs or performance issues.
Not Isolating the Problem: If a bug appears in a large, complex component, try to extract the problematic logic or UI into a simpler, isolated component. This helps you narrow down the scope.

Embracing the Debugging Journey

Debugging is an integral part of development. It’s where you truly become a master of your craft. When you next face a baffling React bug, remember to take that deep breath. Approach it with curiosity, not frustration. Arm yourself with the right tools, a systematic approach, and a solid understanding of React's fundamentals. You'll not only fix the immediate issue but also emerge with a deeper, richer understanding of your application and React itself. Happy debugging!

If you found this helpful, I’d love to hear your favorite debugging tips or your most memorable "aha!" moment in the comments!

✨ Let's keep the conversation going!

If you found this interesting, I'd love for you to check out more of my work or just drop in to say hello.

✍️ Read more on my blog: bishoy-bishai.github.io

☕ Let's chat on LinkedIn: linkedin.com/in/bishoybishai

The bug took two days to find. The fix was one line. But we are solving the wrong problem

Bishoy Bishai — Sat, 20 Jun 2026 12:18:08 +0000

Let me tell you about a bug that took me two full days to find at a company I worked at.

A user on an internal support panel would click between two tickets quickly, ticket A, then ticket B, before ticket A finished loading. Most of the time, this worked fine. Occasionally, ticket B's page would render ticket A's data. Not crash. Not error. Just silently wrong. The kind of bug that makes a support agent send the wrong information to the wrong customer and nobody notices until someone complains.

I traced it for two days. It was a classic race condition: clicking ticket A fired a useEffect that called the API. Clicking ticket B before A resolved firing another `useEffect "for ticket B. If A's network request happened to resolve after B's because of network jitter, server load, or anything A's response would land last and overwrite B's data in state.

The fix was a few lines: an AbortController, a cleanup function, and a check for whether the effect was still "current." I'd written this exact pattern probably thirty times across my career by that point at nearly every company I'd worked for. Every single React codebase I'd touched needed this same defensive code, written by hand, in every single component that fetched data.

That was the moment I stopped being stubborn about React Query.

I'd avoided it for years. Partly because useEffect felt like "real React" and a data library felt like a crutch. Partly because I didn't understand what problem it was actually solving, I thought it was about reducing boilerplate, which felt like a nice-to-have, not a need-to-have. I was wrong on both counts, and the two-day bug is what finally made that clear.

The Category Error That Costs Everyone Time

Here's the mistake I made for years, and the mistake I see in almost every React codebase I review: treating server state as if it were client state.

Client state is data your application fully owns. A modal's open/closed status. The current step in a wizard. A dark mode preference. This state is synchronous, exclusive to your app, and there's exactly one source of truth: your component or your store.

Server state is fundamentally different. It's

Remote — it lives on a server you don't fully control
Shared — other users, other tabs, other devices might change it
Asynchronous by nature you're always looking at a snapshot, never the live truth
Potentially stale the instant you receive it — between the response leaving the server and rendering in your UI, the underlying data could have already changed

useState, useReducer, Redux, Zustand every general-purpose state tool was designed with client state's assumptions in mind: synchronous, single source of truth, fully owned by your application. When you use these tools for server state, you're fighting their fundamental assumptions, and that fight shows up as bugs.

The race condition I described isn't a `useEffect "bug" specifically. It's a category error: I used a tool built for synchronous, owned state to manage asynchronous, borrowed state. The tool doesn't know that a stale response can arrive after a fresh one. It doesn't know that the data might already be cached from another component. It doesn't know that "loading" needs to mean something different on first load versus on a background refetch. Because none of those concerns exist for client states, they only exist for server states.

React Query isn't a data-fetching convenience. It's a state management library built specifically for the category of state that useStatewas never designed to handle.

What the Two-Day Bug Actually Required to Fix Manually

Let me show you the honest, complete fix for the race condition, not the simplified version, the real one, because seeing the full defensive code is what makes the case for a dedicated tool.

// The "fixed" version, by hand, with useEffect
// This is what every data-fetching component needs to be correct.
// I've written approximately this exact code dozens of times.

function TicketDetail({ ticketId }: { ticketId: string }) {
  const [ticket, setTicket] = useState<Ticket | null>(null);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    // AbortController: cancel the in-flight request if ticketId changes
    // or the component unmounts before this resolves
    const controller = new AbortController();

    const fetchTicket = async () => {
      setIsLoading(true);
      setError(null);

      try {
        const response = await fetch(`/api/tickets/${ticketId}`, {
          signal: controller.signal,
        });

        if (!response.ok) throw new Error('Failed to fetch ticket');

        const data: Ticket = await response.json();
        setTicket(data);
      } catch (err) {
        // AbortError means we cancelled this on purpose — not a real error
        if (err instanceof Error && err.name === 'AbortError') return;
        setError(err instanceof Error ? err.message : 'Unknown error');
      } finally {
        setIsLoading(false);
      }
    };

    fetchTicket();

    return () => controller.abort();
  }, [ticketId]);

  // This component has NO caching. Click back to a ticket you already
  // viewed? Full refetch, full loading spinner, every time.

  // This component has NO background refresh. If the ticket status
  // changes on the server while this is open, you'll never know
  // unless you reload the page.

  // This component has NO deduplication. If TWO components on the
  // page both need this ticket's data, you fetch it TWICE.

  // This component has NO retry logic. One network blip and the
  // user sees an error, with no automatic recovery.

  if (isLoading) return <Skeleton />;
  if (error) return <ErrorMessage message={error} />;
  if (!ticket) return null;

  return <TicketView ticket={ticket} />;
}

The AbortController fix solves the race condition. It does not solve caching. It does not solve background refresh. It does not solve deduplication across components. It does not solve retries. Each of those is its own multi-day investment to build correctly, and most teams never build them; they just live with stale data, duplicate requests, and unhandled network blips because building the infrastructure by hand for every feature is too expensive to justify.

This is the actual cost of treating server state as client state: not just the bugs you catch, but the entire category of correctness you never even attempt because it's too expensive to build manually.

The Same Component, Correctly, with React Query

// First, set up the QueryClient once at the app root
// queryClient.ts
import { QueryClient } from '@tanstack/react-query';

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // Data is considered fresh for 30 seconds after fetching.
      // During this window, re-mounting the component or refocusing
      // the tab will NOT trigger a refetch — the cached data is trusted.
      staleTime: 30 * 1000,
      // Retry failed requests twice before giving up.
      // Network blips self-heal without the user noticing.
      retry: 2,
    },
  },
});

// services/tickets.ts
// The fetcher function — pure, framework-agnostic, easily testable

interface Ticket {
  id: string;
  subject: string;
  status: 'open' | 'pending' | 'closed';
  customerEmail: string;
  messages: Message[];
}

export async function fetchTicket(ticketId: string): Promise<Ticket> {
  const response = await fetch(`/api/tickets/${ticketId}`);
  if (!response.ok) {
    throw new Error(`Failed to fetch ticket: ${response.status}`);
  }
  return response.json();
}

// TicketDetail.tsx — the component, now genuinely simple

import { useQuery } from '@tanstack/react-query';
import { fetchTicket } from '../services/tickets';

function TicketDetail({ ticketId }: { ticketId: string }) {
  // The query key ['ticket', ticketId] is the cache identity.
  // Switch from ticket A to ticket B and back to A within 30 seconds?
  // Instant render from cache. No spinner. No refetch.
  const { data: ticket, isLoading, isError, error } = useQuery({
    queryKey: ['ticket', ticketId],
    queryFn: () => fetchTicket(ticketId),
  });

  // Race conditions: SOLVED. React Query tracks which query key is
  // "current" and discards responses for stale keys automatically.
  // Click A, then B fast — React Query knows B is the current request
  // and ignores a late-arriving response for A.

  // Caching: SOLVED. Revisit a ticket within staleTime — instant.

  // Deduplication: SOLVED. Ten components on the page asking for the
  // same ticketId? ONE network request. All ten get the same data.

  // Retries: SOLVED. Configured once, globally, applies everywhere.

  if (isLoading) return <Skeleton />;
  if (isError) return <ErrorMessage message={error.message} />;
  if (!ticket) return null;

  return <TicketView ticket={ticket} />;
}

The component went from forty-plus lines of defensive plumbing to roughly ten lines of actual logic. But the real win isn't line count it's that four entire categories of bugs (race conditions, redundant fetches, stale-without-knowing, and unhandled transient failures) are now handled by infrastructure that's been battle-tested by thousands of production applications, instead of infrastructure I wrote myself at 11 PM under deadline pressure.

The Mental Model That Actually Matters: Stale-While-Revalidate

Here's the part most tutorials explain too quickly. Understanding this pattern is what separates "I added React Query" from "I understand why my app feels fast."

What happens when a component mounts and requests data
that's already in the cache:

Timeline:
0ms    Component mounts, calls useQuery(['ticket', '123'])
0ms    React Query checks cache: data EXISTS for this key
0ms    Returns cached data IMMEDIATELY — UI renders with content,
       no loading spinner, no flash, no delay
0ms    Is the cached data "stale" (older than staleTime)?
       If YES → React Query ALSO fires a background fetch
1ms    UI is fully rendered and interactive with cached data
300ms  Background fetch resolves
300ms  If the data CHANGED → re-render with fresh data
       If the data is THE SAME → no re-render, nothing visible happens

This is the entire insight: the user never waits for a network request if there's any cached data available, even stale data. They see something immediately. If that something turns out to be outdated, it silently corrects itself a moment later usually before they'd notice anyway.

Compare this to the naive useEffect pattern, where every mount means a blank state, loading spinner, wait for network, then render. Stale-while-revalidate eliminates the wait in the common case (revisiting something you've already seen) and only pays the network cost once, in the background, invisibly.

// The staleTime vs gcTime distinction — the one configuration
// decision that determines your caching behavior

useQuery({
  queryKey: ['ticket', ticketId],
  queryFn: () => fetchTicket(ticketId),

  // staleTime: how long the data is considered "fresh"
  // During this window: cached data is served with ZERO background refetch
  // After this window: cached data is still served instantly,
  //   but a background refetch is triggered
  staleTime: 30 * 1000, // 30 seconds

  // gcTime (formerly cacheTime): how long UNUSED data stays in memory
  // after the last component using it unmounts
  // If you navigate away and come back within this window,
  // the cache is still there — instant render, even though stale
  gcTime: 5 * 60 * 1000, // 5 minutes (this is actually the default)
});

The mistake almost everyone makes: setting staleTime: 0 (the default) for data that genuinely doesn't change often, causing unnecessary background refetches every time a component remounts. For a list of countries, a list of categories, anything that changes rarely — set staleTime to minutes or hours. For live, frequently-changing data — keep it low or zero. This single number is your most impactful performance lever, and most developers never touch it.

Mutations and the Cache Invalidation That Actually Works

Fetching is half the story. The other half: changing data and making sure your UI reflects the change everywhere it's displayed.

// services/tickets.ts

export async function updateTicketStatus(
  ticketId: string,
  status: Ticket['status']
): Promise<Ticket> {
  const response = await fetch(`/api/tickets/${ticketId}`, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ status }),
  });
  if (!response.ok) throw new Error('Failed to update ticket');
  return response.json();
}

// TicketActions.tsx

import { useMutation, useQueryClient } from '@tanstack/react-query';
import { updateTicketStatus } from '../services/tickets';

function TicketActions({ ticket }: { ticket: Ticket }) {
  const queryClient = useQueryClient();

  const mutation = useMutation({
    mutationFn: (status: Ticket['status']) =>
      updateTicketStatus(ticket.id, status),

    onSuccess: (updatedTicket) => {
      // Option A: invalidate — tell React Query "this data might be stale,
      // refetch it in the background." Simple, always correct, slight delay.
      queryClient.invalidateQueries({ queryKey: ['ticket', ticket.id] });

      // Also invalidate any list views showing this ticket
      // (e.g., a ticket list filtered by status) — they need to know too
      queryClient.invalidateQueries({ queryKey: ['tickets'] });
    },
  });

  return (
    <div>
      <button
        onClick={() => mutation.mutate('closed')}
        disabled={mutation.isPending}
      >
        {mutation.isPending ? 'Closing...' : 'Close Ticket'}
      </button>
      {mutation.isError && (
        <p className="text-red-500">{mutation.error.message}</p>
      )}
    </div>
  );
}

Option B Optimistic Updates: when invalidation feels too slow

For interactions where instant feedback matters, like a button, a status toggle, or anything, the user expects to feel immediate invalidation, which introduces a visible delay: click, wait for the mutation, wait for the refetch, then see the update. Optimistic updates skip the wait.

function TicketStatusToggle({ ticket }: { ticket: Ticket }) {
  const queryClient = useQueryClient();

  const mutation = useMutation({
    mutationFn: (status: Ticket['status']) =>
      updateTicketStatus(ticket.id, status),

    // onMutate runs BEFORE the mutation fires — this is where
    // we update the cache optimistically
    onMutate: async (newStatus) => {
      // Cancel any in-flight refetches for this query so they
      // don't overwrite our optimistic update with stale data
      await queryClient.cancelQueries({ queryKey: ['ticket', ticket.id] });

      // Snapshot the current value — we need this to roll back on failure
      const previousTicket = queryClient.getQueryData<Ticket>(['ticket', ticket.id]);

      // Optimistically update the cache directly
      queryClient.setQueryData<Ticket>(['ticket', ticket.id], (old) =>
        old ? { ...old, status: newStatus } : old
      );

      // Return the snapshot — this becomes available in onError as `context`
      return { previousTicket };
    },

    // If the mutation fails, roll back using the snapshot
    onError: (err, newStatus, context) => {
      if (context?.previousTicket) {
        queryClient.setQueryData(['ticket', ticket.id], context.previousTicket);
      }
    },

    // Whether it succeeds or fails, refetch to ensure we're in sync
    // with the server's actual state
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['ticket', ticket.id] });
    },
  });

  return (
    <select
      value={ticket.status}
      onChange={(e) => mutation.mutate(e.target.value as Ticket['status'])}
    >
      <option value="open">Open</option>
      <option value="pending">Pending</option>
      <option value="closed">Closed</option>
    </select>
  );
}

The user sees the dropdown change instantly. If the server rejects it with a permission error, validation failure, or network issue the dropdown silently reverts, and the cache eventually matches reality regardless of outcome.

Query Keys: The Decision That Determines Everything Else

I want to spend real time here because query keys are the single most consequential decision in any React Query implementation, and the documentation undersells how much thought they deserve.

The mental model: a query key is not a label. It's a dependency array for your data exactly like a `useEffect "dependency array," except React Query uses it to determine cache identity, not just when to refetch.

`typescript
// 🚩 The mistake: inconsistent or incomplete keys

// Component A
useQuery({ queryKey: ['tickets'], queryFn: () => fetchTickets() });

// Component B — fetching FILTERED tickets, but using the SAME key
useQuery({
queryKey: ['tickets'], // ❌ Same key, different actual data!
queryFn: () => fetchTickets({ status: 'open' }),
});

// Result: these two queries fight over the same cache slot.
// Whichever rendered LAST overwrites the cache for BOTH components.
// Component A might suddenly show only open tickets. Silent, confusing bug.
`

`typescript
// ✅ Correct: the key includes every variable that changes what's fetched

function useTickets(filters: { status?: string; assignee?: string }) {
return useQuery({
// The filters object is PART of the cache identity.
// Different filters → different cache entry → no collision.
queryKey: ['tickets', filters],
queryFn: () => fetchTickets(filters),
});
}

// Usage:
useTickets({ status: 'open' }); // Cache key: ['tickets', { status: 'open' }]
useTickets({ status: 'closed' }); // Cache key: ['tickets', { status: 'closed' }]
useTickets({ assignee: 'me' }); // Cache key: ['tickets', { assignee: 'me' }]
// All three cache independently. No collisions. No stale overwrite bugs.
`

The rule: every variable you use in queryFn to decide what to fetch must appear in the queryKey. If it's not in the key, React Query doesn't know it needs to treat that as a different cache entry, and you get exactly the silent data-swap bug I described at the start of this article, except now it's React Query causing it because you configured it wrong, not because you forgot an AbortController.

The Uncomfortable Truth About Adopting React Query

Here's what the "just add React Query, it's magic" articles don't say:

React Query doesn't remove the need to think about your data. It removes the need to write the same defensive plumbing by hand every time, badly.

The race condition bug I described doesn't disappear because you installed a library. It disappears because the library has already solved that exact problem, correctly, in a way that's been tested across thousands of production applications. But you still need to think about stale time. You still need to design your query keys correctly. You still need to decide between invalidation and optimistic updates for each interaction. The thinking moved from "How do I prevent race conditions?" to "What's the right caching strategy for this specific data?" which is a better question to be answering, but it's still a question that requires judgment.

Teams that adopt React Query and configure everything with defaults, never touching staleTime, never thinking about query key structure, get a worse outcome than teams that understood the defensive `useEffect "pattern" and wrote it carefully by hand. The library amplifies good judgment. It doesn't replace it.

✨ Let's keep the conversation going!

If you found this interesting, I'd love for you to check out more of my work or just drop in to say hello.

✍️ Read more on my blog: bishoy-bishai.github.io

☕ Let's chat on LinkedIn: linkedin.com/in/bishoybishai

📘 Curious about AI?: You can also check out my book: Surrounded by AI

Next.js 15 Error Handling: error.tsx, Server Actions, and Sentry (2026)

Bishoy Bishai — Thu, 18 Jun 2026 13:51:58 +0000

Navigating the Storm: Next.js 15 Error Handling, Server Actions, and Sentry in 2026

I've been building web applications for a while now, and one truth remains constant: errors happen. They always do. I still recall the panicked call from a client, "The entire checkout page is blank!" My stomach dropped. Turns out, a seemingly innocuous API call in a deeply nested component had failed, and without proper error boundaries, the whole thing just silently imploded. We were logging some errors, sure, but understanding the context and gracefully recovering the UI? That was a scramble.

This experience taught me a profound lesson: error handling isn't just about preventing crashes; it's about delivering a resilient, understandable user experience and giving your team the tools to diagnose issues quickly. And as we push deeper into the capabilities of frameworks like Next.js 15, especially with its powerful Server Actions and the declarative error.tsx boundaries, our approach to error handling needs to evolve. We're building full-stack applications with an unprecedented level of integration between client and server, meaning errors can originate anywhere and propagate in fascinating, sometimes frustrating, ways.

The Declarative Embrace: `error.tsx` in Next.js 15

Gone are the days where you'd manually sprinkle try/catch blocks around every potential client-side failure point just to show a fallback UI. Next.js 15's error.tsx is a game-changer, embracing a declarative pattern akin to React's Error Boundaries but deeply integrated into the App Router.

Here's the thing: error.tsx acts as an error boundary for a segment of your application. If an error is thrown within that segment (or any of its children), error.tsx catches it, prevents the crash, and allows you to display a fallback UI, keeping the rest of your application functional. This means instead of your entire page going blank, perhaps just a single widget or a specific data display fails gracefully.

// app/dashboard/error.tsx
'use client'; // Error boundaries must be client components

import { useEffect } from 'react';

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    // Optionally log the error to an error reporting service
    // In my experience, this is critical for server-side errors that bubble up
    console.error(error);
  }, [error]);

  return (
    <div className="flex flex-col items-center justify-center p-8 bg-red-100 border border-red-400 rounded-lg">
      <h2 className="text-xl font-semibold text-red-800">Something went wrong!</h2>
      <p className="mt-2 text-red-700">We're sorry, but there was an issue loading this section.</p>
      <button
        className="mt-4 px-4 py-2 bg-red-600 text-white rounded hover:bg-red-700 transition-colors"
        onClick={
          // Attempt to recover by trying to re-render the segment
          () => reset()
        }
      >
        Try again
      </button>
      <p className="mt-2 text-sm text-red-500">Error digest: {error.digest || 'N/A'}</p>
    </div>
  );
}

Notice the 'use client' directive. If your error.tsx needs interactivity (like that "Try again" button), it must be a client component. What I've found incredibly powerful is how this system prevents cascading failures. If your error.tsx is at app/dashboard/error.tsx, an error in app/dashboard/settings/page.tsx will be caught by that boundary, not taking down the entire dashboard layout.

Taming the Backend Beast: Errors in Server Actions

Server Actions are incredible for unifying client-side interactions with server-side logic, but they introduce a new dimension to error handling. When an error occurs within a Server Action, it doesn't automatically trigger the nearest error.tsx on the client. Why? Because the Server Action executes on the server, and its result (or error) is returned to the client-side code that invoked it.

This means you absolutely must wrap your Server Action logic in try/catch blocks if you want to handle specific error conditions gracefully or return user-friendly messages.

// app/dashboard/actions.ts
'use server';

import { revalidatePath } from 'next/cache';

export async function createProduct(formData: FormData) {
  try {
    const name = formData.get('name') as string;
    const price = parseFloat(formData.get('price') as string);

    if (!name || isNaN(price) || price <= 0) {
      throw new Error('Invalid product data provided.');
    }

    // Simulate a database operation that might fail
    const result = await fetch('https://api.example.com/products', {
      method: 'POST',
      body: JSON.stringify({ name, price }),
      headers: { 'Content-Type': 'application/json' },
    });

    if (!result.ok) {
      // Here, we catch API errors and re-throw a more controlled error
      const errorData = await result.json();
      throw new Error(errorData.message || 'Failed to create product.');
    }

    revalidatePath('/dashboard/products');
    return { success: true, message: `Product "${name}" created!` };
  } catch (error: any) {
    // Log the error for server-side debugging BEFORE returning to client
    console.error('Server Action Error: ', error);
    // Return a structured error object to the client
    return { success: false, message: error.message || 'An unexpected error occurred.' };
  }
}

On the client side, you then handle this returned error:

// app/dashboard/page.tsx
'use client';

import { useState } from 'react';
import { createProduct } from './actions';

export default function DashboardPage() {
  const [statusMessage, setStatusMessage] = useState<string | null>(null);
  const [isSubmitting, setIsSubmitting] = useState(false);

  const handleSubmit = async (event: React.FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    setIsSubmitting(true);
    setStatusMessage(null);

    const formData = new FormData(event.currentTarget);
    const result = await createProduct(formData); // Call the server action

    if (result.success) {
      setStatusMessage(`Success: ${result.message}`);
    } else {
      setStatusMessage(`Error: ${result.message}`);
    }
    setIsSubmitting(false);
  };

  return (
    <div className="p-8">
      <h1 className="text-2xl font-bold mb-4">Create New Product</h1>
      <form onSubmit={handleSubmit} className="space-y-4">
        <div>
          <label htmlFor="name" className="block text-sm font-medium text-gray-700">Product Name</label>
          <input type="text" id="name" name="name" className="mt-1 block w-full border border-gray-300 rounded-md shadow-sm p-2" required />
        </div>
        <div>
          <label htmlFor="price" className="block text-sm font-medium text-gray-700">Price</label>
          <input type="number" id="price" name="price" step="0.01" className="mt-1 block w-full border border-gray-300 rounded-md shadow-sm p-2" required />
        </div>
        <button type="submit" disabled={isSubmitting} className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 disabled:opacity-50">
          {isSubmitting ? 'Creating...' : 'Create Product'}
        </button>
      </form>
      {statusMessage && (
        <p className={`mt-4 ${statusMessage.startsWith('Error') ? 'text-red-600' : 'text-green-600'}`}>
          {statusMessage}
        </p>
      )}
      {/* This component could also throw an error from other logic, which error.tsx would catch */}
      {/* Example: <ProductList /> which might fail to fetch initial data */}
    </div>
  );
}

The critical insight here is that error.tsx only catches errors that occur during the render cycle or data fetching within its boundary. Errors from Server Actions that are properly try/catch-ed and return a structured result object will be handled imperatively by your client component. However, if a Server Action throws an uncaught error on the server and that error then causes a rendering issue (e.g., corrupt data invalidates a React component's expectations), then error.tsx might catch the subsequent client-side rendering error. It's a nuanced distinction, but vital for robust design.

The Watchful Eye: Sentry for Comprehensive Observability

error.tsx provides a beautiful user experience. Your try/catch in Server Actions gives you granular control. But neither tells you what truly happened across your entire application, in production, when you're not actively debugging. This is where Sentry (or a similar error monitoring tool) becomes indispensable.

In my experience, if you're not capturing errors consistently across both your client and server, you're flying blind. Next.js 15, with its client/server component architecture, requires a dual-pronged Sentry setup:

Client-side Sentry: Captures errors that bubble up from your client components, typically caught by error.tsx (which then logs it) or unhandled errors in your interactive client-side logic.
Server-side Sentry: Critical for capturing errors within your Server Components, Server Actions, API routes, and any other Node.js logic. These are errors that often happen before a browser even sees anything.

The setup usually involves initializing Sentry in sentry.client.config.ts and sentry.server.config.ts, ensuring you have the correct DSNs and environment variables. Then, within your error.tsx component, you'd use Sentry.captureException(error) in the useEffect hook. For Server Actions, you'd integrate Sentry.captureException(error) directly within your catch block before returning the error to the client.

// app/sentry.server.config.ts (simplified example)
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  // ... other configs
});

// app/dashboard/actions.ts (updated for Sentry)
'use server';

import { revalidatePath } from 'next/cache';
import * as Sentry from "@sentry/nextjs"; // Import Sentry

export async function createProduct(formData: FormData) {
  try {
    // ... existing logic ...
  } catch (error: any) {
    console.error('Server Action Error: ', error);
    Sentry.captureException(error); // Capture this server-side error
    return { success: false, message: error.message || 'An unexpected error occurred.' };
  }
}

This holistic approach gives you stack traces, user context, breadcrumbs, and release monitoring, helping you move from "what happened?" to "what caused it, who was affected, and how do we fix it?"

Pitfalls to Avoid (Lessons Learned the Hard Way)

Forgetting use client in error.tsx: If your error.tsx needs state, event handlers, or effects, it must be a client component. I've wasted precious minutes debugging hydration errors because of this oversight.
Not logging server-side errors: An error caught by error.tsx on the client might have originated on the server. If you don't log it on the server (e.g., in your Server Action's catch block or a global server-side error handler), you'll miss crucial context. Sentry helps bridge this gap.
Over-catching vs. letting error.tsx handle it: Distinguish between operational errors (like "invalid input") that you handle gracefully within your logic, and unexpected programming errors (like a TypeError from missing data) that error.tsx should catch. Don't try/catch everything; let the boundaries do their job for true exceptions.
Incomplete Sentry setup: Ensure both client-side and server-side Sentry configurations are correct. It's easy to miss one, leading to blind spots. Test your error logging in development and staging environments.
Testing error boundaries: Actively test your error.tsx components. Intentionally throw errors in different parts of your app to ensure the correct boundary catches them and displays the expected fallback.

Wrapping It Up: Building Resilient Next.js Apps

Next.js 15, with its advanced error handling mechanisms and the power of Server Actions, empowers us to build incredibly dynamic and efficient applications. But with great power comes the need for robust error strategies.

By thoughtfully employing error.tsx for graceful UI degradation, strategically using try/catch within your Server Actions for granular control, and integrating a comprehensive observability platform like Sentry, you’re not just catching errors; you're building a resilient, maintainable, and ultimately more user-friendly application. Embrace these tools, and you’ll find yourself spending less time reacting to production fires and more time innovating.

✨ Let's keep the conversation going!

If you found this interesting, I'd love for you to check out more of my work or just drop in to say hello.

✍️ Read more on my blog: bishoy-bishai.github.io

☕ Let's chat on LinkedIn: linkedin.com/in/bishoybishai

The Two Hooks That Separate Junior from Senior React Developers

Bishoy Bishai — Tue, 02 Jun 2026 11:35:32 +0000

It's not about knowing the API. It's about knowing when your component needs to think differently.

There's a specific moment in a code review that tells me everything I need to know about where a developer is in their React code.

I ask: "Why did you use useState here instead of useReducer?"

The junior answer: "Because it's simpler."

The senior answer: "Because the state changes don't depend on each other, so there's no state machine here. If they did, I'd use useReducer."

Both answers reference the same two hooks. But the senior answer reveals something the junior answer doesn't: a mental model for when the problem changes shape. The junior knows the API. The senior knows the diagnosis.

The two hooks that most consistently reveal the gap between junior and senior thinking are useReducer and useRef.

Not because they're the hardest hooks. Because they're the ones that require you to think about your problem differently before you write any code.

`useState`

Here's the thing about useState: it's so easy that it becomes the answer to every question.

Component needs something? useState. Need two things? Two useState calls. Need five things? Five useState calls.

And it works. Until it doesn't.

The moment it stops working isn't dramatic. It's subtle. It looks like this:

// The component that's starting to tell you something

function CheckoutFlow() {
  const [step, setStep] = useState<1 | 2 | 3>(1);
  const [items, setItems] = useState<CartItem[]>([]);
  const [discount, setDiscount] = useState<string>('');
  const [isValidatingDiscount, setIsValidatingDiscount] = useState(false);
  const [discountError, setDiscountError] = useState<string | null>(null);
  const [discountAmount, setDiscountAmount] = useState(0);
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [orderError, setOrderError] = useState<string | null>(null);
  const [orderId, setOrderId] = useState<string | null>(null);

  // Now every handler touches multiple pieces of state.
  // The coordination logic is implicit — it lives in your head, not in the code.
  const handleApplyDiscount = async () => {
    setIsValidatingDiscount(true);
    setDiscountError(null);
    try {
      const result = await validateDiscount(discount);
      setDiscountAmount(result.amount);
      setIsValidatingDiscount(false);
    } catch (err) {
      setDiscountError('Invalid discount code');
      setDiscountAmount(0);
      setIsValidatingDiscount(false);
    }
  };

  // And this is just ONE handler.
  // There are five more like it.
}

Nine useState calls. Every handler coordinates multiple setters. The state transitions are implicit scattered across event handlers, useEffect dependencies, and callback chains.

This isn't a useState problem. It's a diagnosis problem. The component is managing a state machine — a set of explicit states with explicit transitions between them — but using a tool designed for independent values.

That's the gap useReducerfills.

`useReducer` — When Your State Has a Narrative

I'd like to start with this question: Can I describe the states my component can be in as named states with named transitions?

If yes — you have a state machine. useReducer is how you make that machine explicit.

Let me show you the checkout flow refactored. Not because useReducer makes the code shorter — it doesn't, necessarily. Because it makes the state machine readable.

// The shape of possible states — explicit, named, complete
type CheckoutStatus =
  | 'browsing'           // User is reviewing their cart
  | 'validating_discount' // Discount code is being validated
  | 'discount_applied'   // Discount was valid and applied
  | 'submitting'         // Order is being placed
  | 'success'            // Order placed successfully
  | 'error';             // Something went wrong

interface CheckoutState {
  status: CheckoutStatus;
  step: 1 | 2 | 3;
  items: CartItem[];
  discountCode: string;
  discountAmount: number;
  orderId: string | null;
  error: string | null;
}

// Actions — named events that happen in the world
type CheckoutAction =
  | { type: 'DISCOUNT_CODE_CHANGED'; payload: string }
  | { type: 'DISCOUNT_VALIDATION_STARTED' }
  | { type: 'DISCOUNT_VALIDATED'; payload: { amount: number } }
  | { type: 'DISCOUNT_REJECTED'; payload: string }
  | { type: 'NEXT_STEP' }
  | { type: 'PREV_STEP' }
  | { type: 'ORDER_SUBMISSION_STARTED' }
  | { type: 'ORDER_PLACED'; payload: { orderId: string } }
  | { type: 'ORDER_FAILED'; payload: string }
  | { type: 'RESET' };

const initialCheckoutState: CheckoutState = {
  status: 'browsing',
  step: 1,
  items: [],
  discountCode: '',
  discountAmount: 0,
  orderId: null,
  error: null,
};

function checkoutReducer(state: CheckoutState, action: CheckoutAction): CheckoutState {
  switch (action.type) {
    case 'DISCOUNT_CODE_CHANGED':
      // Can only change discount code when not currently validating
      // This is an implicit rule that used to live in the handler —
      // now it lives in the reducer, where it's explicit and testable
      if (state.status === 'validating_discount') return state;
      return {
        ...state,
        discountCode: action.payload,
        // Clear any previous discount when the code changes
        discountAmount: 0,
        error: null,
        status: 'browsing',
      };

    case 'DISCOUNT_VALIDATION_STARTED':
      return {
        ...state,
        status: 'validating_discount',
        error: null,
      };

    case 'DISCOUNT_VALIDATED':
      return {
        ...state,
        status: 'discount_applied',
        discountAmount: action.payload.amount,
        error: null,
      };

    case 'DISCOUNT_REJECTED':
      return {
        ...state,
        status: 'browsing',
        discountAmount: 0,
        error: action.payload,
      };

    case 'NEXT_STEP':
      // Can only advance if not in a blocking state
      if (state.status === 'validating_discount' || state.status === 'submitting') {
        return state;
      }
      return {
        ...state,
        step: Math.min(3, state.step + 1) as 1 | 2 | 3,
        error: null,
      };

    case 'PREV_STEP':
      return {
        ...state,
        step: Math.max(1, state.step - 1) as 1 | 2 | 3,
        error: null,
      };

    case 'ORDER_SUBMISSION_STARTED':
      return { ...state, status: 'submitting', error: null };

    case 'ORDER_PLACED':
      return {
        ...state,
        status: 'success',
        orderId: action.payload.orderId,
        error: null,
      };

    case 'ORDER_FAILED':
      return {
        ...state,
        status: 'error',
        error: action.payload,
      };

    case 'RESET':
      return initialCheckoutState;

    default:
      return state;
  }
}

Now the component:

function CheckoutFlow() {
  const [state, dispatch] = useReducer(checkoutReducer, initialCheckoutState);

  const handleApplyDiscount = async () => {
    if (!state.discountCode.trim()) return;

    dispatch({ type: 'DISCOUNT_VALIDATION_STARTED' });

    try {
      const result = await validateDiscount(state.discountCode);
      dispatch({ type: 'DISCOUNT_VALIDATED', payload: { amount: result.amount } });
    } catch {
      dispatch({ type: 'DISCOUNT_REJECTED', payload: 'Invalid discount code' });
    }
  };

  const handleSubmitOrder = async () => {
    dispatch({ type: 'ORDER_SUBMISSION_STARTED' });

    try {
      const { orderId } = await placeOrder({
        items: state.items,
        discountCode: state.discountCode,
      });
      dispatch({ type: 'ORDER_PLACED', payload: { orderId } });
    } catch (err) {
      dispatch({
        type: 'ORDER_FAILED',
        payload: err instanceof Error ? err.message : 'Order failed',
      });
    }
  };

  // Each handler is now clean: one action, no coordination
  // The coordination logic lives in the reducer

  if (state.status === 'success') {
    return <OrderConfirmation orderId={state.orderId!} />;
  }

  return (
    <div>
      <StepIndicator current={state.step} />

      {state.step === 1 && (
        <CartReview
          items={state.items}
          onNext={() => dispatch({ type: 'NEXT_STEP' })}
        />
      )}

      {state.step === 2 && (
        <DiscountStep
          discountCode={state.discountCode}
          discountAmount={state.discountAmount}
          isValidating={state.status === 'validating_discount'}
          isApplied={state.status === 'discount_applied'}
          error={state.error}
          onCodeChange={(code) =>
            dispatch({ type: 'DISCOUNT_CODE_CHANGED', payload: code })
          }
          onApply={handleApplyDiscount}
          onNext={() => dispatch({ type: 'NEXT_STEP' })}
          onBack={() => dispatch({ type: 'PREV_STEP' })}
        />
      )}

      {state.step === 3 && (
        <OrderReview
          state={state}
          isSubmitting={state.status === 'submitting'}
          error={state.error}
          onSubmit={handleSubmitOrder}
          onBack={() => dispatch({ type: 'PREV_STEP' })}
        />
      )}
    </div>
  );
}

The component is clean. Every handler dispatches one action. The coordination logic lives in the reducer — where it's explicit, named, and testable without mounting anything.

This is the thing juniors miss. The reducer is a pure function. No React. No DOM. No mocks.

// checkout.reducer.test.ts
// Pure function tests — fast, simple, comprehensive

describe('checkoutReducer', () => {
  describe('DISCOUNT_CODE_CHANGED', () => {
    it('updates the discount code', () => {
      const state = checkoutReducer(initialCheckoutState, {
        type: 'DISCOUNT_CODE_CHANGED',
        payload: 'SAVE20',
      });
      expect(state.discountCode).toBe('SAVE20');
    });

    it('clears previous discount amount when code changes', () => {
      const stateWithDiscount: CheckoutState = {
        ...initialCheckoutState,
        discountAmount: 20,
        status: 'discount_applied',
      };

      const state = checkoutReducer(stateWithDiscount, {
        type: 'DISCOUNT_CODE_CHANGED',
        payload: 'NEWSAVE',
      });

      // The discount amount is cleared when the code changes
      expect(state.discountAmount).toBe(0);
      expect(state.status).toBe('browsing');
    });

    it('ignores changes while validation is in progress', () => {
      const validatingState: CheckoutState = {
        ...initialCheckoutState,
        status: 'validating_discount',
        discountCode: 'SAVE20',
      };

      const state = checkoutReducer(validatingState, {
        type: 'DISCOUNT_CODE_CHANGED',
        payload: 'DIFFERENTCODE',
      });

      // Should not change — we're validating
      expect(state.discountCode).toBe('SAVE20');
    });
  });

  describe('NEXT_STEP', () => {
    it('advances the step', () => {
      const state = checkoutReducer(initialCheckoutState, { type: 'NEXT_STEP' });
      expect(state.step).toBe(2);
    });

    it('does not advance while submitting', () => {
      const submittingState: CheckoutState = {
        ...initialCheckoutState,
        step: 2,
        status: 'submitting',
      };

      const state = checkoutReducer(submittingState, { type: 'NEXT_STEP' });
      expect(state.step).toBe(2); // Did not advance
    });

    it('does not go beyond step 3', () => {
      const lastStepState: CheckoutState = {
        ...initialCheckoutState,
        step: 3,
      };

      const state = checkoutReducer(lastStepState, { type: 'NEXT_STEP' });
      expect(state.step).toBe(3); // Stayed at 3
    });
  });
});

When a junior says "this component is hard to test" — it usually means the logic is inside the component, entangled with the rendering. When a senior says "I made this testable" — it usually means the logic is in a pure function like a reducer, separated from the rendering entirely.

That's the real value of useReducer. Not less code. Testable logic.

`useRef` — The Three Different Problems It Solves

Here's the confusion with useRef: it solves three distinct problems, and they look like they have nothing to do with each other. Developers who only know one use case are regularly confused by the other two.

The diagnostic question: Which of these three problems do I have?

I need to access a DOM element directly
I need to store a value that persists across renders but should NOT trigger a re-render
I need a stable reference to a value that changes over time, accessible inside a callback

Three different problems. One hook. Let me show each one clearly.

Problem 1: DOM Access

// The most common use — direct DOM interaction
// You need this when React's declarative model can't express
// what you need to do (focus, play/pause, measure, animate)

function SearchInput({ onSearch }: { onSearch: (query: string) => void }) {
  const inputRef = useRef<HTMLInputElement>(null);
  const [query, setQuery] = useState('');

  // Focus the input when the component mounts
  useEffect(() => {
    // inputRef.current is null on the first render
    // By the time this effect runs, the DOM is ready and current is set
    inputRef.current?.focus();
  }, []);

  // Also focus when user presses Cmd/Ctrl + K anywhere on the page
  useEffect(() => {
    const handleKeyDown = (e: KeyboardEvent) => {
      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
        e.preventDefault();
        inputRef.current?.focus();
        inputRef.current?.select(); // Select existing text
      }
    };

    document.addEventListener('keydown', handleKeyDown);
    return () => document.removeEventListener('keydown', handleKeyDown);
  }, []);

  return (
    <input
      ref={inputRef}
      type="search"
      value={query}
      onChange={e => setQuery(e.target.value)}
      onKeyDown={e => {
        if (e.key === 'Enter') onSearch(query);
      }}
      placeholder="Search... (⌘K)"
    />
  );
}

Problem 2: Mutable Value Without Re-render

// Values that React doesn't need to know about
// Storing them in state would cause unnecessary re-renders
// Storing them in a regular variable would reset on every render

function useStopwatch() {
  const [displayTime, setDisplayTime] = useState(0);
  const [isRunning, setIsRunning] = useState(false);

  // The interval ID needs to persist across renders
  // But changing it shouldn't trigger a re-render — it's not UI state
  // A regular variable would reset to null on every render
  // useState would trigger a re-render every time we set it
  // useRef is the correct tool
  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);

  // The start time also shouldn't trigger re-renders
  const startTimeRef = useRef<number>(0);
  const elapsedRef = useRef<number>(0);

  const start = () => {
    if (isRunning) return;

    startTimeRef.current = Date.now() - elapsedRef.current;
    intervalRef.current = setInterval(() => {
      setDisplayTime(Date.now() - startTimeRef.current);
    }, 10);

    setIsRunning(true);
  };

  const pause = () => {
    if (!isRunning) return;

    clearInterval(intervalRef.current!);
    elapsedRef.current = Date.now() - startTimeRef.current;
    setIsRunning(false);
  };

  const reset = () => {
    clearInterval(intervalRef.current!);
    intervalRef.current = null;
    elapsedRef.current = 0;
    startTimeRef.current = 0;
    setDisplayTime(0);
    setIsRunning(false);
  };

  // Cleanup on unmount
  useEffect(() => {
    return () => {
      if (intervalRef.current) clearInterval(intervalRef.current);
    };
  }, []);

  return { displayTime, isRunning, start, pause, reset };
}

Problem 3: Stable Reference to a Changing Value

This is the one that trips up even experienced developers. It's the stale closure problem and useRef is one of the solutions.

// The problem: a callback captures a stale value from the closure

function useDebounce<T extends (...args: unknown[]) => void>(
  callback: T,
  delay: number
): T {
  // 🚩 Naive implementation — has a stale closure bug
  // Every time callback changes (e.g., because it captures state),
  // the debounced function is recreated — defeating the purpose of debouncing
  const debouncedFn = useCallback(
    debounce(callback, delay),
    [callback, delay] // callback changing recreates the debounced function
  );

  return debouncedFn as T;
}

// ✅ Correct implementation using useRef
function useDebounce<T extends (...args: unknown[]) => void>(
  callback: T,
  delay: number
): T {
  // Store the latest callback in a ref
  // The ref is always up to date — no stale closures
  const callbackRef = useRef(callback);

  // Keep the ref current whenever callback changes
  // This runs after every render where callback changed
  useEffect(() => {
    callbackRef.current = callback;
  }, [callback]);

  // The debounced function is created ONCE (empty dep array)
  // It always calls the latest callback via the ref
  // So the debounce timer is stable AND the callback is always current
  const debouncedFn = useCallback(
    debounce((...args: Parameters<T>) => {
      callbackRef.current(...args);
    }, delay),
    [delay] // Only recreate if delay changes
  );

  return debouncedFn as T;
}

// Another stale closure example: event listener with state

function useKeyboardShortcut(
  key: string,
  onTrigger: () => void
) {
  // onTrigger might capture state from the component.
  // If we add it to the useEffect dependency array,
  // the event listener is removed and re-added on every render — inefficient.
  // If we don't add it, we have a stale closure.

  // useRef solves this: the listener is added once,
  // but always calls the latest version of onTrigger
  const onTriggerRef = useRef(onTrigger);

  useEffect(() => {
    onTriggerRef.current = onTrigger;
  }, [onTrigger]);

  useEffect(() => {
    const handleKeyDown = (e: KeyboardEvent) => {
      if (e.key === key) {
        onTriggerRef.current(); // Always calls the latest version
      }
    };

    document.addEventListener('keydown', handleKeyDown);
    return () => document.removeEventListener('keydown', handleKeyDown);
  }, [key]); // Only re-subscribe if the key changes
}

The Pattern That Combines Both

Here's something I haven't seen documented anywhere but use regularly in production: combining useReducer and useRef in a custom hook to handle async operations cleanly.

The problem: when an async operation completes, the component might have unmounted or the state might have changed. The reducer handles state transitions. The ref handles the "am I still mounted?" check.

// useAsyncReducer.ts
// A pattern for reducers that need to handle async operations
// without race conditions or updates on unmounted components

interface AsyncState<T> {
  data: T | null;
  status: 'idle' | 'loading' | 'success' | 'error';
  error: string | null;
}

type AsyncAction<T> =
  | { type: 'FETCH_STARTED' }
  | { type: 'FETCH_SUCCESS'; payload: T }
  | { type: 'FETCH_ERROR'; payload: string }
  | { type: 'RESET' };

function asyncReducer<T>(
  state: AsyncState<T>,
  action: AsyncAction<T>
): AsyncState<T> {
  switch (action.type) {
    case 'FETCH_STARTED':
      return { ...state, status: 'loading', error: null };
    case 'FETCH_SUCCESS':
      return { status: 'success', data: action.payload, error: null };
    case 'FETCH_ERROR':
      return { ...state, status: 'error', error: action.payload };
    case 'RESET':
      return { data: null, status: 'idle', error: null };
    default:
      return state;
  }
}

function useAsyncData<T>(
  fetchFn: () => Promise<T>,
  deps: React.DependencyList
) {
  const [state, dispatch] = useReducer(asyncReducer<T>, {
    data: null,
    status: 'idle',
    error: null,
  });

  // Track whether the component is still mounted
  // If it unmounts before the fetch completes, don't dispatch
  // (dispatching to an unmounted component causes a React warning
  // and can cause memory leaks)
  const isMountedRef = useRef(true);

  useEffect(() => {
    isMountedRef.current = true;

    return () => {
      // Set to false when the component unmounts
      isMountedRef.current = false;
    };
  }, []);

  useEffect(() => {
    dispatch({ type: 'FETCH_STARTED' });

    fetchFn()
      .then(data => {
        // Only dispatch if still mounted
        if (isMountedRef.current) {
          dispatch({ type: 'FETCH_SUCCESS', payload: data });
        }
      })
      .catch(err => {
        if (isMountedRef.current) {
          dispatch({
            type: 'FETCH_ERROR',
            payload: err instanceof Error ? err.message : 'Unknown error',
          });
        }
      });

    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, deps);

  const reset = () => dispatch({ type: 'RESET' });

  return { ...state, reset };
}

// Usage: clean, safe, handles unmount correctly
function UserProfile({ userId }: { userId: string }) {
  const { data: user, status, error } = useAsyncData(
    () => fetchUser(userId),
    [userId]
  );

  if (status === 'loading') return <Skeleton />;
  if (status === 'error') return <ErrorMessage message={error!} />;
  if (!user) return null;

  return <ProfileCard user={user} />;
}

The useReducer handles the state machine. The useRef handles the imperative concern (is the component still alive?). Together, they make a pattern that is both declarative and safe.

Here's what I want to say that most "advanced hooks" articles skip:

The reason junior developers don't reach for useReducer isn't ignorance. It's confidence.

Writing useState feels safe. The feedback loop is fast. It works. Refactoring to useReducer requires committing to a mental model — state machines, explicit transitions, action names — before you're sure the component will need it.

The senior developer's advantage isn't technical knowledge. It's the willingness to invest in structure before the complexity demands it, because they've seen what happens when you don't. They've debugged the ten-useState component at 11 PM before a launch. They've spent two hours tracing which handler set which flag. They know the cost.

And `useRef "the reason juniors misuse it is simpler: they don't know which of the three problems they have." They reach for it because they've seen it used, not because they've diagnosed their specific situation.

The upgrade isn't learning more syntax. It's learning to ask, "What problem do I actually have?" before picking a tool.

✨ Let's keep the conversation going!

If you found this interesting, I'd love for you to check out more of my work or just drop in to say hello.

✍️ Read more on my blog: bishoy-bishai.github.io

☕ Let's chat on LinkedIn: linkedin.com/in/bishoybishai

📘 Curious about AI?: You can also check out my book: Surrounded by AI

React Hooks in 2026: Not Just What They Do — When to Reach for Each One

Bishoy Bishai — Mon, 11 May 2026 12:32:06 +0000

Every hook is a solution to a specific problem. The senior developer's skill isn't knowing the API — it's knowing the problem.

Let me tell you the moment I knew I'd finally understood React Hooks.

It was 2019; I was building the first mobile app from scratch. No templates. No prior codebase. A blank React Native project and a deadline that didn't care about my learning curve.

I had a form with six steps. Each step had its own state. State from step two affected validation in step five. The user could jump backwards. Progress had to persist. Errors had to be per-field, not per-form.

My first instinct was to reach for useState. Six calls, one per step, plus more for errors, plus more for the current step index. By the time I had a working draft, I had thirteen useState calls that couldn't talk to each other without me writing the coordination logic manually.

I stared at it for a long time. Then I deleted all of it and wrote one useReducer.

Everything became cleaner. The state transitions were explicit. The debugging was straightforward. The tests were obvious. The next developer who opened that file — including future me, three months later — could understand the form's state machine in five minutes.

That's when I understood the real question. Not "What does useReducer do?" — I knew that from the docs. The real question was: "how do I know I need useReducer instead of useState?" And that question doesn't live in any documentation.

Before We Start: The One Question That Changes Everything

Before reaching for any hook, ask: "What changes, and what needs to respond to that change?"

This sounds simple. It isn't. Most over-engineered React components exist because someone added a hook first and figured out the problem second. The hook then created its own complexity, which required another hook, which created more complexity.

The question forces you to define the problem before you pick the tool. A few minutes spent answering it correctly saves hours of debugging the wrong abstraction.

Let me show you what I mean as we go through each hook.

`useState` — The Entry Point and Its Limits

What changes: A single, independent piece of data within one component.

"If this value changes, does anything else in this component need to know about it or react to it?"

If the answer is "no" — useState is correct. If the answer is "yes, something else changes too" — you might be building a state machine that needs useReducer.

// useState is correct here:
// The count changes. Nothing else in the component needs to respond to that change.
// It's truly independent.

function LikeButton({ postId }: { postId: string }) {
  const [isLiked, setIsLiked] = useState(false);
  const [likeCount, setLikeCount] = useState(0);

  const handleLike = async () => {
    // Functional update form — non-negotiable when new state depends on previous
    // Without this, rapid clicks create stale closure bugs:
    // you click twice fast, both callbacks read isLiked = false,
    // both set it to true — the second click doesn't unlike
    setIsLiked(prev => !prev);
    setLikeCount(prev => prev + (isLiked ? -1 : 1));
    await toggleLike(postId);
  };

  return (
    <button onClick={handleLike}>
      {isLiked ? '❤️' : '🤍'} {likeCount}
    </button>
  );
}

Where useState starts to struggle:

// 🚩 The smell: multiple useState calls that always change together
// If you find yourself writing this, you're managing a state machine manually

function MultiStepForm() {
  const [step, setStep] = useState(1);
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [errors, setErrors] = useState<Record<string, string>>({});
  const [formData, setFormData] = useState<FormData>({});
  const [isValid, setIsValid] = useState(false);

  // Now every handler needs to coordinate all five of these.
  // Welcome to the coordination tax.
  const handleNext = () => {
    // Validate current step
    const newErrors = validateStep(step, formData);
    setErrors(newErrors);
    setIsValid(Object.keys(newErrors).length === 0);
    if (Object.keys(newErrors).length === 0) {
      setStep(prev => prev + 1);
    }
  };
  // This is already fragile and we haven't written the submit handler yet.
}

When you see multiple pieces of state that always change together, or when one state change conditionally triggers another — that's useReducer territory.

`useReducer` — State Machines, Not Just Complex State

What changes: Multiple related pieces of state with explicit transitions between them.

"Can I describe this component's state as a set of named states with named transitions between them?"

If yes — useReducer. The reducer IS the state machine definition.

// Six steps of state. Now it's one reducer.
// Every possible state transition is named and explicit.

type FormStep = 1 | 2 | 3 | 4 | 5 | 6;

interface FormState {
  currentStep: FormStep;
  data: Partial<FormData>;
  errors: Record<string, string>;
  isSubmitting: boolean;
  isComplete: boolean;
}

type FormAction =
  | { type: 'NEXT_STEP'; payload: { stepData: Partial<FormData>; errors: Record<string, string> } }
  | { type: 'PREV_STEP' }
  | { type: 'UPDATE_FIELD'; payload: { field: string; value: unknown } }
  | { type: 'SUBMIT_START' }
  | { type: 'SUBMIT_SUCCESS' }
  | { type: 'SUBMIT_ERROR'; payload: string };

const initialFormState: FormState = {
  currentStep: 1,
  data: {},
  errors: {},
  isSubmitting: false,
  isComplete: false,
};

function formReducer(state: FormState, action: FormAction): FormState {
  switch (action.type) {
    case 'NEXT_STEP': {
      // State transition is explicit: you can only go to next step if no errors
      const hasErrors = Object.keys(action.payload.errors).length > 0;
      if (hasErrors) {
        return { ...state, errors: action.payload.errors };
      }
      return {
        ...state,
        currentStep: Math.min(6, state.currentStep + 1) as FormStep,
        data: { ...state.data, ...action.payload.stepData },
        errors: {},
      };
    }

    case 'PREV_STEP':
      return {
        ...state,
        currentStep: Math.max(1, state.currentStep - 1) as FormStep,
        errors: {}, // Clear errors when going back — intentional UX decision
      };

    case 'UPDATE_FIELD':
      return {
        ...state,
        data: { ...state.data, [action.payload.field]: action.payload.value },
        // Clear the error for this field as the user types — live validation
        errors: { ...state.errors, [action.payload.field]: '' },
      };

    case 'SUBMIT_START':
      return { ...state, isSubmitting: true, errors: {} };

    case 'SUBMIT_SUCCESS':
      return { ...state, isSubmitting: false, isComplete: true };

    case 'SUBMIT_ERROR':
      return {
        ...state,
        isSubmitting: false,
        // Show a general error at the current step
        errors: { form: action.payload },
      };

    default:
      return state;
  }
}

// The component is now clean.
// All the coordination logic is in the reducer — testable in isolation.
function MultiStepForm() {
  const [state, dispatch] = useReducer(formReducer, initialFormState);

  const handleNext = () => {
    const stepData = getCurrentStepData(state.currentStep, state.data);
    const errors = validateStep(state.currentStep, stepData);
    dispatch({ type: 'NEXT_STEP', payload: { stepData, errors } });
  };

  return (
    <div>
      <StepIndicator current={state.currentStep} total={6} />
      <StepContent
        step={state.currentStep}
        data={state.data}
        errors={state.errors}
        onFieldChange={(field, value) =>
          dispatch({ type: 'UPDATE_FIELD', payload: { field, value } })
        }
      />
      <FormNavigation
        onNext={handleNext}
        onBack={() => dispatch({ type: 'PREV_STEP' })}
        isSubmitting={state.isSubmitting}
        currentStep={state.currentStep}
        totalSteps={6}
      />
    </div>
  );
}

The test that tells you if your reducer is well-designed: Can you test every state transition without mounting a component? If yes — you've separated your logic from your UI correctly. The reducer is pure. The component is dumb.

// Test the reducer in isolation — no React, no render, no DOM
describe('formReducer', () => {
  it('does not advance to next step when errors exist', () => {
    const state = formReducer(initialFormState, {
      type: 'NEXT_STEP',
      payload: {
        stepData: {},
        errors: { name: 'Name is required' },
      },
    });

    expect(state.currentStep).toBe(1); // Stayed on step 1
    expect(state.errors.name).toBe('Name is required');
  });

  it('clears errors when going back', () => {
    const stateWithErrors: FormState = {
      ...initialFormState,
      currentStep: 2,
      errors: { email: 'Invalid email' },
    };

    const state = formReducer(stateWithErrors, { type: 'PREV_STEP' });
    expect(state.errors).toEqual({});
    expect(state.currentStep).toBe(1);
  });
});

`useEffect` — The Most Misused Hook in React

What changes: Something outside React's rendering model needs to synchronize with your component's state.

"Am I synchronizing with something external — DOM, API, timer, subscription, browser API? Or am I just computing a value?"

If you're computing a value — don't use useEffect. Compute it inline or use useMemo. useEffect is for synchronization, not computation.

// 🚩 The most common useEffect mistake: using it for derived state
function UserGreeting({ user }: { user: User }) {
  const [greeting, setGreeting] = useState('');

  // Wrong: This is not synchronization. It's computation.
  // Every render: compute greeting → trigger re-render → compute greeting again
  // That's a render cycle for zero reason.
  useEffect(() => {
    setGreeting(`Hello, ${user.name.split(' ')[0]}!`);
  }, [user.name]);

  return <h1>{greeting}</h1>;
}

// ✅ Correct: Compute inline. No useEffect needed.
function UserGreeting({ user }: { user: User }) {
  const greeting = `Hello, ${user.name.split(' ')[0]}!`;
  return <h1>{greeting}</h1>;
}

// ✅ useEffect is correct here: synchronizing with an external system (browser API)
function useDocumentTitle(title: string) {
  useEffect(() => {
    const previousTitle = document.title;
    document.title = title;

    // Cleanup: restore the previous title when component unmounts
    // or when title changes. This is the cleanup function doing real work.
    return () => {
      document.title = previousTitle;
    };
  }, [title]);
}

// ✅ useEffect is correct here: subscribing to an external event
function useOnlineStatus() {
  const [isOnline, setIsOnline] = useState(navigator.onLine);

  useEffect(() => {
    const handleOnline = () => setIsOnline(true);
    const handleOffline = () => setIsOnline(false);

    window.addEventListener('online', handleOnline);
    window.addEventListener('offline', handleOffline);

    // Cleanup: remove listeners when component unmounts.
    // Without this, the handlers remain attached to the window
    // even after the component is gone — a memory leak.
    return () => {
      window.removeEventListener('online', handleOnline);
      window.removeEventListener('offline', handleOffline);
    };
  }, []); // Empty array: subscribe once on mount, unsubscribe on unmount

  return isOnline;
}

The AbortController pattern — the one most tutorials skip:

// Data fetching in useEffect — the complete, production-safe version
function useUserData(userId: string) {
  const [user, setUser] = useState<User | null>(null);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    // AbortController lets us cancel the request if:
    // 1. The component unmounts before the request completes
    // 2. userId changes before the first request completes
    // Without this, a fast userId change causes a race condition:
    // request for user A resolves AFTER request for user B,
    // and you render user A's data for user B's profile.
    const controller = new AbortController();

    const fetchUser = async () => {
      setIsLoading(true);
      setError(null);

      try {
        const response = await fetch(`/api/users/${userId}`, {
          signal: controller.signal, // Link this request to the AbortController
        });

        if (!response.ok) throw new Error('Failed to fetch');

        const data: User = await response.json();
        setUser(data);
      } catch (err) {
        // AbortError is expected and not a real error — the component
        // unmounted or userId changed. Don't show an error for this.
        if (err instanceof Error && err.name === 'AbortError') return;
        setError(err instanceof Error ? err.message : 'Unknown error');
      } finally {
        setIsLoading(false);
      }
    };

    fetchUser();

    // Cleanup: abort the in-flight request
    return () => controller.abort();
  }, [userId]);

  return { user, isLoading, error };
}

`useContext` — Sharing State Without Prop Drilling

The diagnostic question: "Is this value needed by components that are far apart in the tree AND changes infrequently?"

Both conditions matter. useContext is efficient for infrequently changing values. For highly dynamic state that changes on every keystroke, it causes performance issues — every consumer re-renders when the context value changes.

// ✅ Good useContext usage: theme changes rarely, needed everywhere
// ThemeContext.tsx

type Theme = 'light' | 'dark';

interface ThemeContextValue {
  theme: Theme;
  toggleTheme: () => void;
}

const ThemeContext = createContext<ThemeContextValue | null>(null);

export function ThemeProvider({ children }: { children: ReactNode }) {
  const [theme, setTheme] = useState<Theme>(() => {
    // Initialize from localStorage — the inline script handles first paint
    try {
      return (localStorage.getItem('theme') as Theme) ?? 'light';
    } catch {
      return 'light';
    }
  });

  const toggleTheme = useCallback(() => {
    setTheme(prev => {
      const next = prev === 'light' ? 'dark' : 'light';
      try { localStorage.setItem('theme', next); } catch {}
      document.documentElement.setAttribute('data-theme', next);
      return next;
    });
  }, []);

  // Memoize the context value to prevent unnecessary re-renders of all consumers
  // when the ThemeProvider's parent re-renders but theme hasn't changed
  const value = useMemo(() => ({ theme, toggleTheme }), [theme, toggleTheme]);

  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
}

// Always wrap useContext in a custom hook — two reasons:
// 1. Throws a clear error if used outside the provider (beats a cryptic undefined error)
// 2. Hides the Context implementation — consumers don't need to import ThemeContext
export function useTheme() {
  const context = useContext(ThemeContext);
  if (!context) throw new Error('useTheme must be used within ThemeProvider');
  return context;
}

// 🚩 useContext performance trap: high-frequency updates in context
// This causes EVERY consumer to re-render on every keystroke

const SearchContext = createContext<{ query: string; setQuery: (q: string) => void } | null>(null);

function SearchProvider({ children }: { children: ReactNode }) {
  const [query, setQuery] = useState('');
  // Every time query changes (every keystroke), ALL consumers re-render.
  // If there are 20 components consuming SearchContext, that's 20 re-renders per keystroke.
  return (
    <SearchContext.Provider value={{ query, setQuery }}>
      {children}
    </SearchContext.Provider>
  );
}

// ✅ Better: keep high-frequency state local, pass callbacks up deliberately
// Or use a state management library (Zustand) that supports selective subscriptions

`useCallback` and `useMemo` — Performance Tools, Not Default Habits

I've seen codebases where every function was wrapped in useCallback "for performance." The profiler showed zero improvement in re-render counts. What it showed was slightly longer render times — from the dependency array comparisons on every render.

"Is this function passed as a prop to a component wrapped in React.memo? Or used as a dependency in a useEffect?"

If neither — useCallback adds overhead with no benefit.

"Is this computation genuinely expensive (sorting thousands of items, complex math), AND does it run on every render?"

If the computation is cheap (string concatenation, simple filtering of small arrays) — useMemo adds overhead with no benefit.

// 🚩 useCallback that helps nothing
function ParentComponent() {
  const [count, setCount] = useState(0);

  // This function is memoized — but Child is not wrapped in React.memo.
  // React.memo is what makes stable references matter.
  // Without it, Child re-renders whenever Parent re-renders regardless.
  // You're paying the memoization cost for zero benefit.
  const handleClick = useCallback(() => {
    console.log('clicked', count);
  }, [count]);

  return <Child onClick={handleClick} />; // Child is NOT React.memo
}

// ✅ useCallback that earns its place
const Child = React.memo(({ onClick }: { onClick: () => void }) => {
  // React.memo: only re-render if props change reference.
  // Now the stable reference from useCallback actually prevents re-renders.
  console.log('Child rendered');
  return <button onClick={onClick}>Click</button>;
});

function ParentComponent() {
  const [count, setCount] = useState(0);
  const [unrelated, setUnrelated] = useState(0);

  // useCallback is justified here:
  // - Child is wrapped in React.memo
  // - stable reference → Child doesn't re-render when `unrelated` changes
  const handleClick = useCallback(() => {
    console.log('clicked', count);
  }, [count]);

  return (
    <div>
      <button onClick={() => setUnrelated(u => u + 1)}>
        Change unrelated ({unrelated})
      </button>
      <Child onClick={handleClick} />
      {/* Child does NOT re-render when unrelated changes */}
    </div>
  );
}

// useMemo: the right use case
function ProductList({ products, filters }: { products: Product[]; filters: Filters }) {
  // Filtering 10,000 products on every render is expensive.
  // useMemo ensures this only runs when products or filters actually change.
  const filteredProducts = useMemo(() => {
    return products
      .filter(p => !filters.category || p.category === filters.category)
      .filter(p => p.price >= filters.minPrice && p.price <= filters.maxPrice)
      .sort((a, b) => {
        if (filters.sortBy === 'price') return a.price - b.price;
        return a.name.localeCompare(b.name);
      });
  }, [products, filters]); // Only recalculate when these change

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

The rule: profile first. Optimize second. React DevTools Profiler shows you which components re-render and how expensive they are. Every optimization decision should be backed by a profile, not a feeling.

`useRef` — Escaping React Without Losing Your Mind

What changes: Something that needs to persist between renders but should NOT trigger a re-render when it changes.

"Do I need to access a DOM element directly, OR do I need to store a mutable value that shouldn't cause re-renders?"

// Use case 1: DOM access
function VideoPlayer({ src }: { src: string }) {
  const videoRef = useRef<HTMLVideoElement>(null);

  const handlePlay = () => {
    // Direct DOM access — can't be done with state
    videoRef.current?.play();
  };

  const handlePause = () => {
    videoRef.current?.pause();
  };

  return (
    <div>
      <video ref={videoRef} src={src} />
      <button onClick={handlePlay}>Play</button>
      <button onClick={handlePause}>Pause</button>
    </div>
  );
}

// Use case 2: Storing a mutable value without re-render
function useInterval(callback: () => void, delay: number) {
  const savedCallback = useRef(callback);

  // Keep the ref up to date without causing re-renders
  useEffect(() => {
    savedCallback.current = callback;
  }, [callback]);

  useEffect(() => {
    const id = setInterval(() => savedCallback.current(), delay);
    // Cleanup: clear the interval when the component unmounts or delay changes
    return () => clearInterval(id);
  }, [delay]);
}

// Use case 3: Tracking previous values
function usePreview<T>(value: T): T | undefined {
  const ref = useRef<T>();

  useEffect(() => {
    ref.current = value; // Store current value after render
  });

  return ref.current; // Return the value from the PREVIOUS render
}

`useTransition` — Making the UI Lie (In the Best Way)

What changes: A state update that's expensive to compute, AND the user needs the input to remain responsive.

"Is there a fast interaction (typing, clicking) that triggers a slow render? And is it okay to show the old UI briefly while the new one computes?"

This is where the mental model matters. useTransition doesn't make the computation faster. It makes React deprioritize it — keeping the input responsive while the heavy update runs in the background. The UI briefly shows "stale" data, which is usually fine.

// Without useTransition: typing in the search input feels laggy
// because every keystroke triggers an expensive filter of 50,000 items
// and the browser hangs until it's done.

// With useTransition: typing is instant. The results update a moment later.
// The user sees smooth input. The results follow. That's the right UX.

function ProductSearch({ products }: { products: Product[] }) {
  const [inputValue, setInputValue] = useState('');
  const [searchQuery, setSearchQuery] = useState('');
  const [isPending, startTransition] = useTransition();

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    // This update is instant — input stays responsive
    setInputValue(e.target.value);

    // This update is a transition — React can deprioritize it
    // if there are more urgent updates (like the next keystroke)
    startTransition(() => {
      setSearchQuery(e.target.value);
    });
  };

  // This expensive computation only runs when searchQuery changes
  // (which is deferred), not when inputValue changes (which is instant)
  const results = useMemo(() => {
    if (!searchQuery) return products;
    return products.filter(p =>
      p.name.toLowerCase().includes(searchQuery.toLowerCase()) ||
      p.description.toLowerCase().includes(searchQuery.toLowerCase())
    );
  }, [products, searchQuery]);

  return (
    <div>
      <input
        value={inputValue}
        onChange={handleChange}
        placeholder="Search products..."
      />
      {/* isPending = the deferred update is still computing */}
      {/* Don't use a full loading spinner here — it's jarring for fast transitions */}
      {/* A subtle opacity change communicates "updating" without disrupting the user */}
      <div style={{ opacity: isPending ? 0.6 : 1, transition: 'opacity 0.1s' }}>
        <p>{results.length} results</p>
        {results.map(product => (
          <ProductCard key={product.id} product={product} />
        ))}
      </div>
    </div>
  );
}

The difference between useTransition and useDeferredValue:

Both solve the "fast input, slow render" problem. The difference is where you apply the optimization:

useTransition — you control when the expensive state update happens. Use when you own the state update.
useDeferredValue — you defer a value you received (from props or state). Use when you don't control the update.

// useDeferredValue: when you receive a value from outside and can't control when it changes
function SearchResults({ query }: { query: string }) {
  // query comes from a parent — we don't control when it changes.
  // useDeferredValue gives us a version of query that React will
  // deprioritize updating, keeping the parent's UI responsive.
  const deferredQuery = useDeferredValue(query);

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

  // isStale = the deferred value hasn't caught up to the real value yet
  const isStale = query !== deferredQuery;

  return (
    <div style={{ opacity: isStale ? 0.7 : 1 }}>
      {results.map(r => <SearchResult key={r.id} result={r} />)}
    </div>
  );
}

`useOptimistic` — Telling the User "Done" Before It Is

What changes: The UI should reflect a user action immediately — before the server confirms it.

"If the server call takes 1 second, should the user wait for the UI to update, or should the UI update immediately and roll back if it fails?"

Almost always the answer is "update immediately." Waiting for server confirmation before showing feedback is a UX pattern from 2010. Modern users expect instant feedback.

// A like button that feels instant — because it is

interface Post {
  id: string;
  content: string;
  likeCount: number;
  isLikedByUser: boolean;
}

async function toggleLikeApi(postId: string, currentlyLiked: boolean): Promise<void> {
  const response = await fetch(`/api/posts/${postId}/like`, {
    method: currentlyLiked ? 'DELETE' : 'POST',
  });
  if (!response.ok) throw new Error('Failed to toggle like');
}

function LikeButton({ post }: { post: Post }) {
  const [actualPost, setActualPost] = useState(post);

  // useOptimistic takes:
  // 1. The actual state (what the server knows)
  // 2. A function to compute the optimistic state (what we show immediately)
  const [optimisticPost, setOptimisticLike] = useOptimistic(
    actualPost,
    (currentPost, isLiking: boolean) => ({
      ...currentPost,
      isLikedByUser: isLiking,
      likeCount: currentPost.likeCount + (isLiking ? 1 : -1),
    })
  );

  const handleLike = async () => {
    const isCurrentlyLiked = optimisticPost.isLikedByUser;

    // Step 1: Show the result immediately in the UI
    setOptimisticLike(!isCurrentlyLiked);

    try {
      // Step 2: Tell the server
      await toggleLikeApi(post.id, isCurrentlyLiked);

      // Step 3: Update the actual state to match
      setActualPost(prev => ({
        ...prev,
        isLikedByUser: !isCurrentlyLiked,
        likeCount: prev.likeCount + (isCurrentlyLiked ? -1 : 1),
      }));
    } catch {
      // Step 4 (on failure): useOptimistic automatically reverts to actualPost
      // The UI snaps back to the actual state. User sees a brief flash of the revert.
      // Show a toast notification explaining the failure.
      console.error('Like failed — UI reverted automatically');
    }
  };

  return (
    <button
      onClick={handleLike}
      aria-label={optimisticPost.isLikedByUser ? 'Unlike post' : 'Like post'}
    >
      {optimisticPost.isLikedByUser ? '❤️' : '🤍'} {optimisticPost.likeCount}
    </button>
  );
}

The mental model for useOptimistic: think of it as a temporary overlay on your real state. You apply the overlay immediately. The real state catches up when the server responds. If the server fails, the overlay is removed and you're back to real state. The "magic" is that you never have to write the revert logic — it's built in.

Custom Hooks — The Real Power Move

Everything above becomes dramatically more powerful when you extract it into custom hooks. A custom hook is just a function that uses hooks — but it's the architectural tool that makes React logic reusable, testable, and composable.

// usePostActions.ts
// Encapsulates all the logic for interacting with a post.
// The component that uses this doesn't know about API calls,
// optimistic state, error handling, or state management.
// It just calls functions and reads state.

interface UsePostActionsReturn {
  post: Post;
  handleLike: () => Promise<void>;
  handleBookmark: () => Promise<void>;
  isLiking: boolean;
  isBookmarking: boolean;
}

export function usePostActions(initialPost: Post): UsePostActionsReturn {
  const [actualPost, setActualPost] = useState(initialPost);
  const [isLiking, setIsLiking] = useState(false);
  const [isBookmarking, setIsBookmarking] = useState(false);

  const [optimisticPost, applyOptimistic] = useOptimistic(
    actualPost,
    (post, action: { type: 'like' | 'bookmark'; value: boolean }) => {
      if (action.type === 'like') {
        return {
          ...post,
          isLikedByUser: action.value,
          likeCount: post.likeCount + (action.value ? 1 : -1),
        };
      }
      return { ...post, isBookmarkedByUser: action.value };
    }
  );

  const handleLike = async () => {
    const newValue = !optimisticPost.isLikedByUser;
    setIsLiking(true);
    applyOptimistic({ type: 'like', value: newValue });
    try {
      await toggleLikeApi(initialPost.id, !newValue);
      setActualPost(prev => ({
        ...prev,
        isLikedByUser: newValue,
        likeCount: prev.likeCount + (newValue ? 1 : -1),
      }));
    } catch {
      // Optimistic state reverts automatically
    } finally {
      setIsLiking(false);
    }
  };

  const handleBookmark = async () => {
    const newValue = !optimisticPost.isBookmarkedByUser;
    setIsBookmarking(true);
    applyOptimistic({ type: 'bookmark', value: newValue });
    try {
      await toggleBookmarkApi(initialPost.id, !newValue);
      setActualPost(prev => ({ ...prev, isBookmarkedByUser: newValue }));
    } catch {
      // Optimistic state reverts automatically
    } finally {
      setIsBookmarking(false);
    }
  };

  return {
    post: optimisticPost,
    handleLike,
    handleBookmark,
    isLiking,
    isBookmarking,
  };
}

// The component is now trivially simple.
// All complexity is in the hook — testable without mounting a component.
function PostCard({ post }: { post: Post }) {
  const { post: postState, handleLike, handleBookmark } = usePostActions(post);

  return (
    <article>
      <p>{postState.content}</p>
      <button onClick={handleLike}>
        {postState.isLikedByUser ? '❤️' : '🤍'} {postState.likeCount}
      </button>
      <button onClick={handleBookmark}>
        {postState.isBookmarkedByUser ? '🔖' : '📄'}
      </button>
    </article>
  );
}

Here's the thing nobody says at the end of a hooks guide:

Most React performance problems I've seen in production are not solved by hooks. They're solved by moving state closer to where it's used.

The single most impactful architectural change in most React codebases isn't "add useCallback here" or "wrap this in useMemo."This state is being managed three levels up when it's only used one level down move it."

A state that lives too high in the tree re-renders too many components. Before reaching for useCallback "to prevent re-renders," ask, "Why does this parent re-render when this child's data changes?" The answer is usually "because the state is in the wrong place."

State colocation—keeping state as close as possible to where it's used—is the optimization that costs nothing and delivers the most. It's not a hook. It's a thinking habit.

Master the hooks. But don't forget the thinking habit.

Always remember > "The best code is no code at all." > — Jeff Atwood > > Why this stays with me: Every hook you add is code. The best React components are the ones that reach for the simplest hook that solves the problem — and stop there.

The Unfinished Chapter

Here's what I'm still working through:

The line between "use useOptimistic" and "use a proper state management solution with optimistic update support" is blurry to me in practice. For a simple case, a like button and a single field update useOptimistic is clean and sufficient. For complex cases, a multi-field form that updates a nested data structure with partial success handling, I've found myself reinventing things that libraries like Zustand or React Query handle better.

My current heuristic: if the optimistic update involves more than one data entity, or if failure recovery is complex, reach for a library. If it's a single action with a clear success/failure boundary, useOptimistic is enough.

But I've been wrong about this heuristic at least twice. Where do you draw the line?

I built the multi-step form six years ago. The useReducerrefactor was the moment hooks stopped being a feature I used and started being a way I thought.

That's what I want for you. Not memorization of the API. A change in how you think about problems before you write the first line. The diagnostic questions in this article are the questions I ask now automatically — not because I'm smart, but because I've shipped enough broken components to have learned which question to ask first.

Use the hook that fits the problem. Use the simplest hook that fits the problem. And know when not to use a hook at all.

Simple? Yes. Takes years to feel natural. Welcome to the craft.

✨ Let's keep the conversation going!

If you found this interesting, I'd love for you to check out more of my work or just drop in to say hello.

✍️ Read more on my blog: bishoy-bishai.github.io

☕ Let's chat on LinkedIn: linkedin.com/in/bishoybishai

📘 Curious about AI?: You can also check out my book. Surrounded by AI

Next.js App Router Complete Guide: From Basics to Advanced Patterns

Bishoy Bishai — Mon, 04 May 2026 12:13:54 +0000

Navigating the Future: A Complete Guide to Next.js App Router for Professional Teams

Remember the days of wrestling with complex data fetching, managing API calls on the client, and constantly optimizing bundle sizes? We've all been there. It's a familiar challenge for any team building ambitious web applications. When Next.js introduced the App Router, I've heard everything from "this is a game-changer" to "just another thing to learn." But in my experience, especially working with larger engineering teams, it's undeniably the path forward for building truly performant, scalable, and maintainable React applications.

Here's the thing about the App Router: it’s not just a tweak; it’s a paradigm shift. It brings React Server Components (RSC) to the forefront, pushing us towards a more server-centric mental model that deeply impacts how we structure, fetch data, and ultimately deliver user experiences. If you've been on the fence, or felt overwhelmed, consider this your practical, real-world guide from someone who's shipped complex features with it.

The Core Shift: Server vs. Client Components – It’s Not Just an Optimization, It’s an Architecture

The most fundamental concept to grasp is the clear delineation between Server Components and Client Components. This isn't just about rendering speed; it's about responsibilities.

Server Components (Default): These are rendered on the server, have direct access to backend resources (databases, file system), zero bundle size, and never re-render in the browser. They're perfect for fetching data, complex business logic, or static content. Think of them as your backend for UI, running just before the HTML is streamed to the user.

Client Components ('use client'): These are rendered on the client, allow for interactivity (hooks like useState, useEffect, event listeners), and send their JavaScript to the browser. They are your interactive UI elements.

My Key Insight: Don't think of 'use client' as an opt-in for interactivity; think of it as an opt-out from server-side superpowers. Your default should always be a Server Component. Only mark a component as a Client Component if it absolutely needs browser APIs, state, or interactivity. This small mental flip will save you from shipping unnecessary JavaScript.

// app/page.tsx (Server Component by default)
import { fetchProducts } from '../lib/data'; // Server-side data fetching

export default async function HomePage() {
  const products = await fetchProducts(); // Direct database query or API call

  return (
    <div>
      <h1>Welcome to our store!</h1>
      <ProductList products={products} /> {/* This can be a Server Component too */}
      <AddToCartButton productId="123" /> {/* This *needs* to be a Client Component */}
    </div>
  );
}

// components/AddToCartButton.tsx (Client Component)
'use client';

import { useState } from 'react';

export default function AddToCartButton({ productId }: { productId: string }) {
  const [quantity, setQuantity] = useState(1);

  const handleClick = () => {
    // Logic to add to cart, maybe a client-side API call
    console.log(`Adding ${quantity} of product ${productId} to cart`);
  };

  return (
    <div>
      <input
        type="number"
        value={quantity}
        onChange={(e) => setQuantity(Number(e.target.value))}
        min="1"
      />
      <button onClick={handleClick}>Add to Cart</button>
    </div>
  );
}

Data Fetching: A New Horizon of Performance

This is where the App Router truly shines. With Server Components, data fetching moves to where it belongs: the server.

async/await in Server Components: You can now directly await promises in your components. No more useEffect for initial data loads! This means less boilerplate, clearer data flow, and no waterfall requests between client and server.
Automatic Caching and De-duping: Next.js automatically caches fetch requests and de-duplicates them across components, even parallel requests. This is a massive performance win you get out of the box.
Streaming UI: Imagine sending parts of your HTML as soon as they're ready, rather than waiting for all data to load. With loading.tsx and React's Suspense boundaries, you can achieve this effortlessly, improving perceived performance significantly.

Lesson Learned: Initially, I saw teams reach for client-side data fetching libraries like SWR or React Query out of habit. While these still have their place for client-side mutations or real-time updates, for initial server-rendered data, embrace the async/await pattern. It simplifies your stack dramatically.

// app/dashboard/page.tsx
import { Suspense } from 'react';
import UserProfile from './UserProfile';
import RecentOrders from './RecentOrders';
import { SkeletonCard } from '@/components/ui/skeleton-card'; // Example loading state

export default async function DashboardPage() {
  return (
    <main>
      <h1>Your Dashboard</h1>
      <Suspense fallback={<SkeletonCard title="Loading Profile..." />}>
        <UserProfile /> {/* Fetches user data on server */}
      </Suspense>
      <Suspense fallback={<SkeletonCard title="Loading Orders..." />}>
        <RecentOrders /> {/* Fetches order data on server */}
      </Suspense>
    </main>
  );
}

Routing and Layouts: Nested and Powerful

The file-system based routing of the App Router is incredibly intuitive, promoting discoverable, maintainable code.

layout.tsx: Defines shared UI for a segment and its children.
page.tsx: The unique UI of a route segment.
loading.tsx: Provides an immediate loading state for a segment, shown while its children load.
error.tsx: Catches errors in a route segment and renders a fallback UI.
template.tsx: Similar to layout.tsx but creates a new instance for each navigation, useful for specific transition animations.

Pitfall to Avoid: Over-nesting layouts without clear purpose. While powerful, too many nested layouts can make it harder to reason about the overall structure. Plan your UI hierarchy carefully, identifying truly shared components versus those that simply happen to be present on multiple pages.

Advanced Patterns & Pitfalls

Passing Props from Server to Client Components: You can pass serializable props from a Server Component to a Client Component. This is your primary mechanism for hydrating client-side interactivity with server-fetched data. Just be mindful of what you pass – functions, dates, or complex objects that aren't JSON-serializable won't work without specific serialization.

use server for Server Actions: This is a huge one for building truly full-stack apps. use server lets you define server-side functions that can be directly called from Client Components without explicitly creating an API route. It's like RPC (Remote Procedure Call) for your React components. I've found this pattern to drastically reduce boilerplate for form submissions and mutations.

// app/actions.ts
'use server';

import { revalidatePath } from 'next/cache';

export async function createPost(formData: FormData) {
  const title = formData.get('title');
  const content = formData.get('content');
  // ... save to database
  console.log('Post created:', { title, content });
  revalidatePath('/blog'); // Revalidate the blog page cache
}

```typescript
// components/PostForm.tsx
'use client';

import { createPost } from '@/app/actions';

export default function PostForm() {
  return (
    <form action={createPost}>
      <input type="text" name="title" placeholder="Title" required />
      <textarea name="content" placeholder="Content" required />
      <button type="submit">Create Post</button>
    </form>
  );
}
```

Hydration Errors: This often happens when the server-rendered HTML doesn't match what the client-side JavaScript tries to render. A common culprit is client-side code that relies on browser APIs (like window or localStorage) during the initial render. Always wrap such code in useEffect or ensure the component is a Client Component and any non-matching content is conditionally rendered after hydration.

Wrapping Up: Embrace the New Mindset

The Next.js App Router, powered by React Server Components, is a powerful leap forward. It redefines the mental model for building React applications, pushing more logic to the server, and in doing so, significantly enhances performance, reduces client-side JavaScript, and simplifies data fetching.

It will require a shift in how your team thinks about component responsibilities. Start small, experiment, and constantly ask yourself: "Does this component really need client-side interactivity?" If not, keep it a Server Component. Embrace the async/await data fetching, leverage Suspense for streaming, and explore Server Actions for powerful RPC-like mutations. The learning curve is real, but the benefits – a faster, more robust, and easier-to-maintain application – are immense. Your users (and your future self) will thank you.

✨ Let's keep the conversation going!

If you found this interesting, I'd love for you to check out more of my work or just drop in to say hello.

✍️ Read more on my blog: bishoy-bishai.github.io

☕ Let's chat on LinkedIn: linkedin.com/in/bishoybishai

How React Works (Part 2)? Why React Had to Build Its Own Execution Engine

Bishoy Bishai — Sat, 02 May 2026 11:30:51 +0000

Decoding React's Engine: Why It Built Its Own Scheduler

Ever built a React app that, despite all your best efforts, just felt a little… janky? Maybe a complex animation stutters, or a rapid state update feels less than immediate. We've all been there. It’s frustrating when you know you’re using a "fast" framework, yet the user experience isn't quite buttery smooth. The truth is, sometimes the bottleneck isn't your code logic, but a fundamental challenge React faces when interacting with the browser itself.

In my experience, many developers understand React's component model, props, state, and hooks. That’s "Part 1" of how React works. But understanding why React had to build its own sophisticated execution engine – the Fiber reconciler – and how it orchestrates updates, is "Part 2." It's where the real magic, and the deepest insights into performance, lie.

The Browser's Dilemma: Why React Needed Its Own Path

Here's the thing: browsers were not initially designed for the highly dynamic, component-driven UIs we build today. Their DOM (Document Object Model) API, while functional, is inherently slow and blocking. Every time you manipulate the DOM directly – adding an element, changing a style, updating text – the browser might have to perform costly operations like recalculating layouts (reflows) and redrawing pixels (repaints). Do too much of this in quick succession, and your JavaScript execution thread gets tied up, blocking user input, freezing animations, and leading to that dreaded "jank."

Imagine you have a complex dashboard with many widgets updating simultaneously. If each widget tried to update the DOM independently and immediately, the browser would be overwhelmed, constantly reflowing and repainting. The UI would flicker and become unresponsive. This is the core problem React set out to solve: how to manage these updates efficiently and non-blockingly.

Enter the Virtual DOM: A Necessary Abstraction

React's initial answer was the Virtual DOM (VDOM). Instead of directly manipulating the browser's DOM, React builds a lightweight, in-memory JavaScript representation of your UI. When state changes, React builds a new VDOM tree and compares it to the previous one. This process, known as diffing or reconciliation, identifies the minimal set of changes required to update the actual browser DOM.

The genius here is that diffing the VDOM is incredibly fast because it's just plain JavaScript objects. Only after it figures out exactly what needs to change does it apply those changes in a single, optimized batch to the real DOM. This dramatically reduces costly browser operations.

But simply knowing what to change isn’t enough. The when and how those changes are applied is equally crucial, especially for complex applications. This is where React's custom execution engine truly shines.

The Heart of the Engine: React Fiber

The reconciliation algorithm itself underwent a massive re-architecture in React 16, moving from the "Stack" reconciler to Fiber. Fiber is the literal re-implementation of React's core algorithm. It’s an "execution engine" because it takes control of how and when your component updates are processed.

Think of React's update process in two main phases:

Render Phase (Reconciliation):
- React starts traversing your component tree, creating a new Fiber tree (a fancy internal representation of your UI).
- It calls your render methods (or functional component bodies) to figure out what should be on the screen.
- Crucially, this phase is interruptible. React can pause this work, yield control back to the browser (so it can process user input or perform animations), and then pick up where it left off. This cooperative scheduling is the superpower of Fiber.
- During this phase, side effects like DOM mutations should not happen, as the work might be aborted or re-done.
Commit Phase:
- Once the Render Phase completes and all changes are calculated, React moves to the Commit Phase.
- This phase is uninterruptible. React takes the calculated changes and applies them to the actual browser DOM.
- This is when effects like those in useEffect and useLayoutEffect are run, allowing you to interact with the real DOM.

Why Interruptible Work Matters

Imagine a user types rapidly into an input field while a large data fetch completes and triggers a massive UI update. With the old Stack reconciler, React would have to process the entire UI update before the browser could respond to the user's keystrokes. This leads to a noticeable delay.

With Fiber, React can process a chunk of the UI update, then check if there's any higher-priority work (like a user typing). If so, it pauses the UI update, lets the browser handle the input, and then resumes the UI update when the browser is idle again. This ensures that user interactions feel immediate and the UI remains responsive, even during heavy processing.

// A simple component to illustrate the concept
import React, { useState, useTransition } from 'react';

function BigList() {
  const [items, setItems] = useState(Array.from({ length: 10000 }, (_, i) => `Item ${i}`));
  const [filter, setFilter] = useState('');
  const [isPending, startTransition] = useTransition();

  const filteredItems = items.filter(item => item.includes(filter));

  const handleFilterChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    // This part of the state update is "urgent" (for the input value)
    setFilter(event.target.value);

    // This part of the state update can be deferred (for filtering a large list)
    // React can pause this work if higher priority tasks (like more typing) come in.
    startTransition(() => {
      // Potentially expensive calculation here if it were inside the handler directly
      // With useTransition, React can prioritize rendering the input value first.
    });
  };

  return (
    <div>
      <input type="text" value={filter} onChange={handleFilterChange} placeholder="Filter items..." />
      {isPending && <span>Loading filtered items...</span>}
      <ul>
        {filteredItems.map(item => (
          <li key={item}>{item}</li>
        ))}
      </ul>
    </div>
  );
}

export default BigList;

In this example, useTransition explicitly tells React that the update to filteredItems can be deferred. React's Fiber engine will intelligently schedule this work, prioritizing immediate UI feedback (like updating the input field) over the potentially expensive list filtering, ensuring a smoother user experience.

The "Why": React Had to Build Its Own Execution Engine

So, why not just use existing browser APIs? The answer is granular control and fine-tuned scheduling. While browsers offer APIs like requestIdleCallback, they don't provide the level of control React needs to build its internal "Fiber tree," manage priorities, and flawlessly coordinate updates across a complex component hierarchy.

React built its own scheduler because:

JavaScript is single-threaded: It can only do one thing at a time. To prevent long-running tasks from blocking the UI, React needed a way to break up work and yield control back to the browser.
Browser APIs are too high-level: They don't expose the primitives needed for React's specific reconciliation and scheduling needs (e.g., pausing a component's render mid-way).
Cross-platform consistency: React aims to work consistently across web, mobile (React Native), and even VR. A custom engine allows for this unified approach.

Pitfalls and Practical Takeaways

Understanding Fiber and the two phases isn't just theoretical. It has real implications:

useEffect vs. useLayoutEffect: useEffect runs after the Commit Phase (after the browser has painted), making it non-blocking. useLayoutEffect runs synchronously after DOM mutations but before the browser paints, which is critical for measuring DOM elements or performing calculations that need to affect layout immediately. Misusing the latter can reintroduce jank.
Unnecessary Re-renders: While Fiber is efficient, calling setState too often with identical data still triggers the Render Phase, causing React to do unnecessary diffing. Tools like React.memo, useMemo, and useCallback are your allies here to help React skip work.
Keys in Lists: Forgetting key props on list items isn't just a warning; it directly impacts the diffing algorithm. Without stable keys, React can't efficiently identify moved, added, or removed items, leading to less optimal DOM updates and potential state bugs.
Batching: React often batches multiple setState calls that happen within the same event loop tick into a single update. This is an optimization powered by its scheduler, preventing multiple redundant re-renders.

Wrapping Up

React's custom execution engine, powered by Fiber, is a marvel of engineering. It's React’s way of saying, "The browser's default tools aren't quite enough for the rich UIs we want to build, so we're building our own highly optimized orchestrator." It ensures that even when your application is doing heavy lifting, the user experience remains responsive and delightful. By understanding this foundation, you gain a deeper appreciation for React’s magic and, more importantly, the knowledge to build truly high-performance, resilient applications.

✨ Let's keep the conversation going!

If you found this interesting, I'd love for you to check out more of my work or just drop in to say hello.

✍️ Read more on my blog: bishoy-bishai.github.io

☕ Let's chat on LinkedIn: linkedin.com/in/bishoybishai

I Let GitHub Copilot Define My React Standards for Six Months. Here's the Damage It Did.

Bishoy Bishai — Fri, 01 May 2026 11:43:30 +0000

AI doesn't invent bad code. It invents averageness — confidently, quickly, and at scale.

There's a specific kind of technical debt that doesn't show up in your linter.

It's not a bug. It's not a performance issue. It's not something your CI pipeline catches. It's the kind of debt where six months into a project, two developers open components that do the same thing — and neither can understand the other's approach. Both are "correct." Both would pass code review. But they feel like they were written by people who never spoke to each other.

In 2022, during the early months of the Passbase design system work, I watched this happen in real time. We had Copilot. We loved Copilot. We used Copilot for everything. And slowly, invisibly, Copilot became the de facto architect of our component patterns — not because we decided that, but because we never decided anything else.

A button component in one feature used interface for props. Another used type. One used React.FC<Props>. Another used the function signature directly. One had a Button/ folder with an index file. Another was just ButtonComponent.tsx sitting flat in components. All of them passed TypeScript. All of them worked. None of them felt like they belonged to the same codebase.

Copilot didn't cause this. We did. By treating every AI suggestion as a decision rather than an input, we outsourced our architectural thinking to a model trained on the average of the internet. And the internet's average is not your team's standard.

What you'll be able to DO after reading this:

Understand the specific psychological trap that makes AI tools drift toward architectural chaos
Build a React standard document that Copilot actually reinforces instead of undermines
Know which decisions must be made by humans and which ones AI can safely handle
Walk away with a folder structure, naming convention, and component pattern system you can ship to your team tomorrow

This is Pillar 2 content — for the senior developer who's been on the team long enough to see the drift, and wants to fix it before it becomes a rewrite.

The Psychological Trap Nobody Names

I want to spend time on the mechanism before the solution, because if you don't understand why this happens, you'll implement standards and watch them erode anyway.

Here's the trap: a suggestion that arrives pre-formed is harder to reject than a blank page.

When you open a new file and need to decide how to structure a component, you have a moment of creative friction. You think about the codebase. You think about the pattern used in the last three components you touched. You make a decision that's connected to context.

When Copilot opens that same file and immediately suggests a complete component structure, that friction disappears. The suggestion looks reasonable. It compiles. You accept it and move on.

What just happened? You didn't make a decision. You approved a default. And defaults, repeated across a team of five developers over six months, become the de facto standard — not because anyone chose it, but because nobody rejected it.

Picasso said: "Computers are useless. They can only give you answers."

He was being provocative, but the insight is precise. Copilot is extraordinarily good at answers. It will give you A valid component structure. A valid prop pattern. A valid hook. But "valid" is not "right for your context." Only you know your context. Only your team has the history of decisions that make one pattern better than another for your specific product.

The moment you stop asking "what should our standard be?" and start asking "what did Copilot suggest?" — you've given the architect's chair to a model that has never seen your codebase, never attended your design reviews, and never had to maintain the code it generated.

At Passbase, when I finally named this pattern to the team, the reaction was immediate recognition. Everyone had felt the drift. Nobody had named what was causing it.

What "Averageness at Scale" Looks Like

Let me show you the actual damage before I show you the fix.

This is what organic Copilot-driven drift looks like after six months on a real team:

src/components/
├── Button.tsx                    ← Developer A, month 1
├── ButtonComponent.tsx           ← Developer B, month 2 (same thing, different name)
├── PrimaryButton/
│   └── PrimaryButton.tsx         ← Developer C, month 3 (folder style)
├── ui/
│   └── button.tsx                ← Developer D, month 4 (shadcn influence)
└── IconButton.tsx                ← Developer A again, month 5 (forgot the folder pattern)

Five developers. Five buttons. Zero decisions. All of them "correct."

Now multiply this across forms, modals, inputs, cards, hooks, services, and API layers. You don't have a codebase. You have a collection of individually reasonable files that happen to be in the same repository.

The cost isn't the inconsistency itself — developers can read inconsistent code. The cost is the cognitive overhead of uncertainty. Every developer who opens a new file asks: "How should I do this?" And without a standard, the answer is always: "I'll see what Copilot suggests." Which perpetuates the problem.

This is Sultan Ibrahim in the cage. Not locked in by force — locked in by comfort. Why struggle with the decision when the suggestion is right there?

The Standard Document: What It Contains and Why

The solution isn't to turn off Copilot. It's to give Copilot something to accelerate.

A standard document is a decision record — the output of the architectural conversations your team should be having explicitly, written down so they don't have to be re-litigated every time someone opens a new file.

Here's ours. Not as a template to copy — as a worked example to understand.

1. Folder Structure — The First Decision That Shapes Everything

Your folder structure is an architectural statement. It says: "This is how we think about our application." Get this wrong and every subsequent decision builds on a shaky foundation.

src/
├── app/                    # App shell — routing, global layout, providers
│   ├── layout.tsx          # Root layout
│   ├── router.tsx          # Route definitions
│   └── providers.tsx       # Context providers stacked here, not scattered
│
├── components/             # Shared UI primitives — NO business logic here
│   ├── Button/
│   │   ├── Button.tsx      # The component
│   │   ├── Button.test.tsx # Tests live next to what they test
│   │   └── index.ts        # Re-export for clean imports
│   ├── Input/
│   ├── Modal/
│   └── index.ts            # Barrel export for all shared components
│
├── features/               # Domain features — business logic lives here
│   ├── Auth/
│   │   ├── components/     # Components only used inside Auth
│   │   ├── hooks/          # Hooks only used inside Auth
│   │   ├── services/       # API calls only used inside Auth
│   │   ├── types.ts        # Types only used inside Auth
│   │   └── AuthPage.tsx    # The page component
│   ├── UserProfile/
│   └── Dashboard/
│
├── hooks/                  # Reusable hooks — NO feature-specific logic
├── services/               # API layer — all fetch calls go through here
├── types/                  # Global TypeScript types
├── utils/                  # Pure helper functions
└── main.tsx

The decision this encodes: business logic belongs in features/, not in components/. A button doesn't know about authentication. An auth form doesn't belong in components/. This boundary is the single most important architectural decision in the document — because it determines where every future file goes.

Why Copilot violates this without guidance: Copilot looks at the nearest files for context. If you're in features/Auth/ and ask for a button, it might generate a button component right there — not because it's wrong, but because it doesn't know your folder structure convention. Without the standard, the developer accepts it. With the standard, the developer knows to reach for components/Button/ instead.

2. Naming Conventions — The Decisions That Eliminate a Thousand Arguments

// ✅ Our conventions — written down once, never debated again

// Components: PascalCase, noun-based
// ✅ UserProfileCard.tsx
// ✅ AuthenticationForm.tsx
// ❌ userProfileCard.tsx
// ❌ UserProfileCardComponent.tsx  ← "Component" suffix is redundant
// ❌ UPCard.tsx  ← Abbreviations are hidden knowledge

// Props interfaces: ComponentNameProps
// ✅ interface ButtonProps {}
// ✅ interface UserProfileCardProps {}
// ❌ interface IButtonProps {}  ← I-prefix is hungarian notation, we don't use it
// ❌ interface Props {}  ← Too generic, hard to search

// Custom hooks: always useNoun or useNounVerb
// ✅ useAuth
// ✅ useUserProfile
// ✅ useProductFilter
// ❌ useFetchUser  ← The "fetch" is an implementation detail, not the hook's identity

// Event handlers: always handleEventName
// ✅ handleSubmit, handleClick, handleFilterChange
// ❌ onSubmit (that's for the prop name, not the handler variable)
// ❌ submitForm, clickButton (verbs without "handle" prefix)

Why this matters more than it looks: naming conventions are how your team searches the codebase. If half your props are onX and half are handleX, your grep results are always incomplete. If some components have I prefix and some don't, TypeScript autocomplete is inconsistent. These are tiny individual decisions that compound into daily friction.

3. Component Architecture — The Three Patterns We Use and When

This is the hardest part to standardize, because it requires actual architectural judgment. Here's ours:

Pattern A: Simple Presentational Component

Use when: the component receives data and renders it. No fetching. No complex state. No side effects.

// components/UserAvatar/UserAvatar.tsx
// This component has one reason to change: the avatar's visual design.
// It doesn't know where the user came from or how their data is structured globally.

interface UserAvatarProps {
  name: string;
  imageUrl?: string;
  size?: 'sm' | 'md' | 'lg';
}

// We use function declaration over React.FC — team decision.
// Reason: React.FC has implicit children prop in older React versions,
// and the function declaration makes the return type clearer.
export function UserAvatar({ name, imageUrl, size = 'md' }: UserAvatarProps) {
  const initials = name
    .split(' ')
    .map(part => part[0])
    .join('')
    .toUpperCase()
    .slice(0, 2);

  const sizeClasses = {
    sm: 'w-8 h-8 text-xs',
    md: 'w-10 h-10 text-sm',
    lg: 'w-14 h-14 text-base',
  };

  if (imageUrl) {
    return (
      <img
        src={imageUrl}
        alt={`${name}'s avatar`}
        className={`rounded-full object-cover ${sizeClasses[size]}`}
      />
    );
  }

  return (
    <div
      className={`rounded-full bg-blue-500 text-white flex items-center justify-center font-medium ${sizeClasses[size]}`}
      aria-label={`${name}'s avatar`}
    >
      {initials}
    </div>
  );
}

Pattern B: Container Component with Custom Hook

Use when: the component needs data fetching or complex state logic.

// features/UserProfile/hooks/useUserProfile.ts
// The hook owns the data logic. The component owns the rendering.
// If the API changes, you touch the hook. If the design changes, you touch the component.
// They have separate reasons to change — separate files.

import { useState, useEffect } from 'react';

interface User {
  id: string;
  name: string;
  email: string;
  avatarUrl?: string;
  bio: string;
}

interface UseUserProfileReturn {
  user: User | null;
  isLoading: boolean;
  error: string | null;
  refetch: () => void;
}

export function useUserProfile(userId: string): UseUserProfileReturn {
  const [user, setUser] = useState<User | null>(null);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  const fetchUser = async () => {
    setIsLoading(true);
    setError(null);
    try {
      const response = await fetch(`/api/users/${userId}`);
      if (!response.ok) throw new Error('Failed to fetch user');
      const data: User = await response.json();
      setUser(data);
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Unknown error');
    } finally {
      setIsLoading(false);
    }
  };

  useEffect(() => {
    fetchUser();
  }, [userId]);

  return { user, isLoading, error, refetch: fetchUser };
}

// features/UserProfile/components/UserProfileCard.tsx
// This component is dumb on purpose. It renders what it receives.
// The complexity lives in the hook — this stays readable.

import { useUserProfile } from '../hooks/useUserProfile';
import { UserAvatar } from '../../../components/UserAvatar';

interface UserProfileCardProps {
  userId: string;
}

export function UserProfileCard({ userId }: UserProfileCardProps) {
  const { user, isLoading, error } = useUserProfile(userId);

  if (isLoading) return <UserProfileCardSkeleton />;
  if (error) return <ErrorMessage message={error} />;
  if (!user) return null;

  return (
    <div className="rounded-lg border border-gray-200 p-6">
      <div className="flex items-center gap-4">
        <UserAvatar name={user.name} imageUrl={user.avatarUrl} size="lg" />
        <div>
          <h2 className="text-lg font-semibold">{user.name}</h2>
          <p className="text-gray-500 text-sm">{user.email}</p>
        </div>
      </div>
      {user.bio && <p className="mt-4 text-gray-700">{user.bio}</p>}
    </div>
  );
}

Pattern C: Compound Components

Use when: the component has multiple configurable sub-parts with shared state.

// components/Tabs/Tabs.tsx
// The compound pattern gives consumers flexibility without prop explosion.
// Compare:

// ❌ Prop explosion — rigid, hard to extend, impossible to compose
<Tabs
  activeTab={currentTab}
  onTabChange={handleChange}
  tabTitles={['Overview', 'Details', 'Settings']}
  tabContents={[<Overview />, <Details />, <Settings />]}
  tabIcons={[overviewIcon, detailsIcon, settingsIcon]}
  tabDisabled={[false, false, true]}
/>

// ✅ Compound — flexible, composable, clear ownership
<Tabs value={currentTab} onChange={handleChange}>
  <Tabs.List>
    <Tabs.Trigger value="overview">Overview</Tabs.Trigger>
    <Tabs.Trigger value="details">Details</Tabs.Trigger>
    <Tabs.Trigger value="settings" disabled>Settings</Tabs.Trigger>
  </Tabs.List>
  <Tabs.Content value="overview"><Overview /></Tabs.Content>
  <Tabs.Content value="details"><Details /></Tabs.Content>
  <Tabs.Content value="settings"><Settings /></Tabs.Content>
</Tabs>

// The implementation — compound components use Context to share state
// without prop drilling between the sub-components

import { createContext, useContext, useState, ReactNode } from 'react';

interface TabsContextValue {
  activeTab: string;
  onChange: (value: string) => void;
}

const TabsContext = createContext<TabsContextValue | null>(null);

function useTabsContext() {
  const context = useContext(TabsContext);
  if (!context) {
    throw new Error('Tabs compound components must be used within <Tabs>');
  }
  return context;
}

interface TabsProps {
  value: string;
  onChange: (value: string) => void;
  children: ReactNode;
}

// The root component — owns the context
export function Tabs({ value, onChange, children }: TabsProps) {
  return (
    <TabsContext.Provider value={{ activeTab: value, onChange }}>
      <div className="tabs-root">{children}</div>
    </TabsContext.Provider>
  );
}

// Sub-components — consume the context
Tabs.List = function TabsList({ children }: { children: ReactNode }) {
  return <div role="tablist" className="flex border-b">{children}</div>;
};

Tabs.Trigger = function TabsTrigger({
  value,
  disabled = false,
  children,
}: {
  value: string;
  disabled?: boolean;
  children: ReactNode;
}) {
  const { activeTab, onChange } = useTabsContext();
  const isActive = activeTab === value;

  return (
    <button
      role="tab"
      aria-selected={isActive}
      disabled={disabled}
      onClick={() => !disabled && onChange(value)}
      className={`px-4 py-2 text-sm font-medium border-b-2 transition-colors
        ${isActive ? 'border-blue-500 text-blue-600' : 'border-transparent text-gray-500'}
        ${disabled ? 'opacity-40 cursor-not-allowed' : 'hover:text-gray-700'}`}
    >
      {children}
    </button>
  );
};

Tabs.Content = function TabsContent({
  value,
  children,
}: {
  value: string;
  children: ReactNode;
}) {
  const { activeTab } = useTabsContext();
  if (activeTab !== value) return null;
  return <div role="tabpanel" className="py-4">{children}</div>;
};

4. State Management Decision Tree

This is the decision that Copilot gets wrong most often — because the right answer depends on context that Copilot doesn't have.

When you need state, ask in this order:

1. Can this be derived from existing state or props?
   YES → Don't add state. Compute it inline.
   NO  → Continue.

2. Is this state used by only ONE component?
   YES → useState (or useReducer if the logic is complex)
   NO  → Continue.

3. Is this state used by a small, bounded component tree?
   YES → useContext within that feature
   NO  → Continue.

4. Is this state genuinely global (user session, theme, cart)?
   YES → Zustand store
   NO  → Go back to step 2. You probably answered wrong.

// ✅ The decision tree in practice:

// Step 1 — derived state: don't store it
function UserGreeting({ user }: { user: User }) {
  // Don't useState for displayName — it's derived from user.name
  const displayName = user.name.split(' ')[0]; // Compute inline
  return <h1>Hello, {displayName}</h1>;
}

// Step 2 — single component: useState
function SearchInput() {
  const [query, setQuery] = useState('');
  return <input value={query} onChange={e => setQuery(e.target.value)} />;
}

// Step 2 — complex single-component logic: useReducer
type FilterAction =
  | { type: 'SET_CATEGORY'; payload: string }
  | { type: 'SET_PRICE_RANGE'; payload: [number, number] }
  | { type: 'RESET' };

interface FilterState {
  category: string;
  priceRange: [number, number];
}

function filterReducer(state: FilterState, action: FilterAction): FilterState {
  switch (action.type) {
    case 'SET_CATEGORY':
      return { ...state, category: action.payload };
    case 'SET_PRICE_RANGE':
      return { ...state, priceRange: action.payload };
    case 'RESET':
      return { category: '', priceRange: [0, 1000] };
  }
}

// Step 3 — feature-scoped shared state: useContext
// See the compound Tabs example above — TabsContext is step 3.

// Step 4 — global state: Zustand
// (Lives in src/store/ — not shown here to keep focus)

Making Copilot Enforce Your Standard

Here's the part that changes everything: once you have a written standard, Copilot becomes significantly better — because you've given it context.

Method 1: .github/copilot-instructions.md

GitHub Copilot reads this file and uses it to inform suggestions across your repository.

# Copilot Instructions — YourProject React Standard

## Component Structure
- Use function declarations, not React.FC
- Props interface named ComponentNameProps
- Export named, not default
- Each component in its own folder with index.ts re-export

## File Location Rules
- Shared UI with no business logic → src/components/
- Feature-specific components → src/features/FeatureName/components/
- Never create components directly in src/components/ that import from src/features/

## State Management
- Derived state: compute inline, never useState
- Single-component state: useState or useReducer
- Feature-scoped shared state: useContext within the feature
- Global state: Zustand in src/store/

## Naming
- Components: PascalCase noun (UserProfileCard not UserProfileCardComponent)
- Event handlers: handleEventName (handleSubmit not onSubmit or submitForm)
- Custom hooks: useNoun or useNounVerb (useAuth not useFetchAuth)
- Props interfaces: ComponentNameProps (no I prefix)

## TypeScript
- Always type props explicitly — no implicit any
- Prefer interface for props, type for unions and utility types
- Avoid type assertions (as X) unless absolutely necessary

Method 2: Annotated Example Files

Create a _examples/ folder in your repository with heavily commented reference implementations. Copilot learns from nearby files — give it the right nearby files.

// src/_examples/ExampleFeatureComponent.tsx
// THIS IS A REFERENCE EXAMPLE — not production code.
// Copilot uses this as a pattern reference for new components.

// STANDARD: function declaration, not React.FC
// STANDARD: props interface named ComponentNameProps
// STANDARD: named export, not default

interface ExampleFeatureComponentProps {
  // STANDARD: required props first, optional props last
  userId: string;
  // STANDARD: optional props have explicit defaults in the signature
  variant?: 'compact' | 'full';
}

// STANDARD: component name matches filename
export function ExampleFeatureComponent({
  userId,
  variant = 'full', // STANDARD: default here, not in the interface
}: ExampleFeatureComponentProps) {
  // STANDARD: hook for data fetching — never fetch in the component body
  const { user, isLoading, error } = useUserProfile(userId);

  // STANDARD: early returns for loading and error states
  // before the main render — keeps the happy path clean
  if (isLoading) return <Skeleton />;
  if (error) return <ErrorMessage message={error} />;
  if (!user) return null;

  return (
    <div>
      {/* STANDARD: conditional rendering with ternary for two states,
          short-circuit && for one state */}
      {variant === 'full' ? (
        <FullUserCard user={user} />
      ) : (
        <CompactUserCard user={user} />
      )}
    </div>
  );
}

Method 3: ESLint Rules That Enforce the Standard

The standard isn't just a document — it's code. Anything you can automate, automate.

// .eslintrc.js
module.exports = {
  rules: {
    // Enforce named exports — no default exports from component files
    'import/no-default-export': 'error',

    // Enforce consistent function component style
    'react/function-component-definition': [
      'error',
      { namedComponents: 'function-declaration' }
    ],

    // Prevent prop-types (we use TypeScript)
    'react/prop-types': 'off',

    // Enforce hook naming convention
    'react-hooks/rules-of-hooks': 'error',

    // Custom rule: warn when useState is used for values derivable from props
    // (This requires a custom ESLint plugin — the team built one)
    'custom/no-derived-state': 'warn',
  }
};

The Uncomfortable Truth About Standards

Here's what I want to say that most "coding standards" articles avoid:

A standards document that lives in Notion is worth less than no standard.

I've watched teams spend two days writing a beautiful standards document, put it in Notion, link it in the README, and then watch it be completely ignored within three weeks. Not from malice — from friction. Opening Notion is friction. Remembering the document exists is friction. The blank file with the Copilot suggestion is zero friction.

Your standard must live where developers work. That means:

In the repository — a Markdown file that's versioned alongside the code
In the linter — rules that enforce it automatically
In example files — reference implementations that Copilot reads
In code review — a checklist that reviewers actively use

The standard that requires no effort to follow is the one that survives.

And the other uncomfortable truth: your standard will be wrong in some places. Accept this upfront. The goal isn't a perfect standard — it's a shared standard. A team that consistently does the same slightly-suboptimal thing is more productive than a team that inconsistently does the theoretically-optimal thing five different ways.

Document the decisions. Include the reasoning. Make it easy to update. And revisit it every quarter — not to rewrite it, but to capture the decisions the team has been making implicitly, and make them explicit.

But

** "This is too much overhead for a small team. We don't need a standards document."**

A standards document for a three-person team takes half a day to write. The inconsistency that builds without one takes weeks to untangle six months later — and those weeks come at the worst possible time, when the team is scaling or a critical deadline is approaching. The overhead is front-loaded. The cost of not doing it is back-loaded and much higher.

"Copilot will just get better. Won't this be solved by the next model?"

Better models will give better suggestions — but "better" still means "better at the average." The average of all React codebases on the internet is not your codebase. No model, however good, knows the specific tradeoffs your team made in sprint three. The need for explicit team standards is not a temporary gap that AI will close. It's the permanent requirement of working with other humans.

"Standards slow down development. We move fast and break things."

Inconsistency slows down development. Standards speed it up. The developer who doesn't have to decide "should I use interface or type here?" every single time they open a new file makes that file faster. The developer who knows exactly where to put a new hook doesn't spend ten minutes deciding on folder structure. The code reviewer who isn't arguing about naming conventions is reviewing logic. Standards are a speed investment, not a speed cost.

📚 my notes

Copilot gives you answers. Your team has to ask the right questions first. The standard document is the list of questions your team has already answered — so Copilot can answer the new ones correctly.

✨ Let's keep the conversation going!

If you found this interesting, I'd love for you to check out more of my work or just drop in to say hello.

✍️ Read more on my blog: bishoy-bishai.github.io

☕ Let's chat on LinkedIn: linkedin.com/in/bishoybishai

📘 Curious about AI?: You can also check out my book: Surrounded by AI

How React + Vite Actually Works Behind the Scenes Breakdown

Bishoy Bishai — Sun, 26 Apr 2026 11:26:27 +0000

Missing

✨ Let's keep the conversation going!

If you found this interesting, I'd love for you to check out more of my work or just drop in to say hello.

✍️ Read more on my blog: bishoy-bishai.github.io

☕ Let's chat on LinkedIn: linkedin.com/in/bishoybishai

DEV Community: Bishoy Bishai

Rethinking Redux: Enhancing Your State Management Strategy

Rethinking Redux: Enhancing Your State Management Strategy

Why This Matters: Beyond Boilerplate Reduction

The Modern Redux Workflow: A Breath of Fresh Air

1. Defining Your Slice with createSlice

2. Configuring Your Store

3. Using in Your React Components

React Navigation Explained

Why rour AI agent struggles with full-stack apps

Why Our AI Agent Still Stumbles on Full-Stack Apps

The Seams, Not Just the Parts: Why Full-Stack is More Than Sum of Its Halves

A Deeper Dive: Where the AI Agent's Logic Crumbles (with Next.js Examples)

Insights from the Trenches: What Most Tutorials Miss (and AIs Can't Grasp)

Common Pitfalls and How to Bridge the Gap

So, What's the Play?

Debugging React: From Taking a Deep Breath to Finding the Root Cause

Debugging React: From Taking a Deep Breath to Finding the Root Cause

Why Debugging Matters More Than You Think

The Deep Breath: Establishing a Systematic Approach

Tools of the Trade: Beyond console.log

1. React DevTools: Your Best Friend

2. Browser DevTools: Network, Console, Sources

3. Understanding React's Core Concepts

Common Pitfalls and How to Avoid Them

Embracing the Debugging Journey

The bug took two days to find. The fix was one line. But we are solving the wrong problem

The Category Error That Costs Everyone Time

What the Two-Day Bug Actually Required to Fix Manually

The Same Component, Correctly, with React Query

The Mental Model That Actually Matters: Stale-While-Revalidate

Mutations and the Cache Invalidation That Actually Works

Query Keys: The Decision That Determines Everything Else

The Uncomfortable Truth About Adopting React Query

Next.js 15 Error Handling: error.tsx, Server Actions, and Sentry (2026)

Navigating the Storm: Next.js 15 Error Handling, Server Actions, and Sentry in 2026

The Declarative Embrace: error.tsx in Next.js 15

Taming the Backend Beast: Errors in Server Actions

The Watchful Eye: Sentry for Comprehensive Observability

Pitfalls to Avoid (Lessons Learned the Hard Way)

Wrapping It Up: Building Resilient Next.js Apps

The Two Hooks That Separate Junior from Senior React Developers

useState

useReducer — When Your State Has a Narrative

useRef — The Three Different Problems It Solves

Problem 1: DOM Access

Problem 2: Mutable Value Without Re-render

Problem 3: Stable Reference to a Changing Value

The Pattern That Combines Both

React Hooks in 2026: Not Just What They Do — When to Reach for Each One

Before We Start: The One Question That Changes Everything

useState — The Entry Point and Its Limits

useReducer — State Machines, Not Just Complex State

useEffect — The Most Misused Hook in React

useContext — Sharing State Without Prop Drilling

useCallback and useMemo — Performance Tools, Not Default Habits

useRef — Escaping React Without Losing Your Mind

useTransition — Making the UI Lie (In the Best Way)

useOptimistic — Telling the User "Done" Before It Is

Custom Hooks — The Real Power Move

Here's the thing nobody says at the end of a hooks guide:

The Unfinished Chapter

Next.js App Router Complete Guide: From Basics to Advanced Patterns

Navigating the Future: A Complete Guide to Next.js App Router for Professional Teams

The Core Shift: Server vs. Client Components – It’s Not Just an Optimization, It’s an Architecture

Data Fetching: A New Horizon of Performance

Routing and Layouts: Nested and Powerful

Advanced Patterns & Pitfalls

Wrapping Up: Embrace the New Mindset

How React Works (Part 2)? Why React Had to Build Its Own Execution Engine

Decoding React's Engine: Why It Built Its Own Scheduler

The Browser's Dilemma: Why React Needed Its Own Path

Enter the Virtual DOM: A Necessary Abstraction

The Heart of the Engine: React Fiber

Why Interruptible Work Matters

The "Why": React Had to Build Its Own Execution Engine

Pitfalls and Practical Takeaways

Wrapping Up

I Let GitHub Copilot Define My React Standards for Six Months. Here's the Damage It Did.

The Psychological Trap Nobody Names

1. Defining Your Slice with `createSlice`

Tools of the Trade: Beyond `console.log`

The Declarative Embrace: `error.tsx` in Next.js 15

`useState`

`useReducer` — When Your State Has a Narrative

`useRef` — The Three Different Problems It Solves

`useState` — The Entry Point and Its Limits

`useReducer` — State Machines, Not Just Complex State

`useEffect` — The Most Misused Hook in React

`useContext` — Sharing State Without Prop Drilling

`useCallback` and `useMemo` — Performance Tools, Not Default Habits

`useRef` — Escaping React Without Losing Your Mind

`useTransition` — Making the UI Lie (In the Best Way)

`useOptimistic` — Telling the User "Done" Before It Is