DEV Community: Bishoy Bishai

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

Mastering Navigation with React Router: A Comprehensive Guide

Bishoy Bishai — Sat, 25 Apr 2026 11:25:54 +0000

Mastering Navigation with React Router: A Comprehensive Guide

Let's be real for a moment. Building a single-page application (SPA) is exhilarating, but the moment you start thinking about navigation – how users move from one view to another, how the URL updates, how data is passed – it can quickly feel like you've stumbled into a labyrinth. I've been there, wrangling with conditional rendering based on URL segments, passing props through layers of components just to get a path parameter, and ultimately creating an unmanageable mess.

This is where React Router steps in, not just as a library, but as a philosophy for managing your application's state through its URL. It offers a declarative, component-based approach that, once truly understood, makes building complex navigation feel almost effortless. In my experience, a solid grasp of React Router isn't just a "nice-to-have"; it's foundational for building scalable, maintainable, and user-friendly React applications.

Why Does Navigation Matter So Much?

Think about it: navigation isn't just about changing the page; it's the core interaction model for your users. A smooth, predictable navigation experience leads to happy users. For developers, a well-structured routing solution simplifies state management, enables deep linking, and dramatically improves code organization. Without it, you're constantly fighting against the browser's native navigation patterns while trying to mimic them poorly.

The Core Building Blocks: A Quick Refresher

At its heart, React Router (specifically v6 and above, which is what I'll focus on) provides a set of components and hooks that let you map URLs to your React components.

Here's a basic setup that you'll see in almost every project:

// App.tsx
import React from 'react';
import { BrowserRouter, Routes, Route, Link } from 'react-router-dom';
import HomePage from './pages/HomePage';
import AboutPage from './pages/AboutPage';
import ProductPage from './pages/ProductPage';
import NotFoundPage from './pages/NotFoundPage';
import './App.css'; // Assume some basic styling

const App: React.FC = () => {
  return (
    <BrowserRouter>
      <nav>
        <Link to="/">Home</Link> | <Link to="/about">About</Link> | <Link to="/products/123">Product 123</Link>
      </nav>
      <Routes>
        <Route path="/" element={<HomePage />} />
        <Route path="/about" element={<AboutPage />} />
        <Route path="/products/:productId" element={<ProductPage />} />
        <Route path="*" element={<NotFoundPage />} /> {/* Catch-all for 404s */}
      </Routes>
    </BrowserRouter>
  );
};

export default App;

BrowserRouter: This is the top-level wrapper that uses the HTML5 history API to keep your UI in sync with the URL. It's almost always where you start.
Routes: This component defines a region where Route components are matched and rendered. It picks the best match, making route ordering less critical than in older versions.
Route: Maps a path to an element (your React component). The path can include dynamic segments like :productId.
Link: Your declarative way to navigate. It renders an <a> tag but prevents a full page reload, letting React Router handle the transition.

Diving Deeper: Power with Hooks

The real magic, the flexibility that makes React Router so powerful in complex scenarios, comes from its hooks. These are the tools you'll reach for when Link isn't enough.

`useNavigate`: Programmatic Navigation

Sometimes, a user action isn't just a simple click on a Link. Maybe they submit a form, and you need to redirect them. Or perhaps an API call fails, and you want to send them back to a safe page. That's where useNavigate shines.

// components/AuthForm.tsx
import React, { useState } from 'react';
import { useNavigate } from 'react-router-dom';

const AuthForm: React.FC = () => {
  const [username, setUsername] = useState('');
  const [password, setPassword] = useState('');
  const navigate = useNavigate(); // Get the navigate function

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    // In a real app, you'd send this to an API
    if (username === 'admin' && password === 'password') {
      alert('Login successful!');
      navigate('/dashboard', { replace: true }); // Redirect to dashboard, replacing current history entry
    } else {
      alert('Invalid credentials!');
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input type="text" value={username} onChange={(e) => setUsername(e.target.value)} placeholder="Username" />
      <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} placeholder="Password" />
      <button type="submit">Login</button>
      <button type="button" onClick={() => navigate(-1)}>Go Back</button> {/* Navigate back */}
    </form>
  );
};

export default AuthForm;

navigate can take a path string, or even a number to go back/forward in the browser history (e.g., navigate(-1)). The replace: true option is crucial when you don't want the user to be able to hit "back" to return to the previous page (like after a successful login).

`useParams` and `useSearchParams`: Dynamic Data

When your routes need to accept dynamic values, like an item ID or a filter, these hooks are your best friends.

useParams: For path segments (e.g., /products/:id).

// pages/ProductPage.tsx
import React from 'react';
import { useParams } from 'react-router-dom';

const ProductPage: React.FC = () => {
  const { productId } = useParams<{ productId: string }>(); // TypeScript magic!

  // In a real app, you'd fetch product data based on productId
  if (!productId) {
    return <div>Product ID not found in URL.</div>;
  }

  return (
    <div>
      <h1>Product Details</h1>
      <p>Displaying details for product ID: <strong>{productId}</strong></p>
      {/* ... more product details */}
    </div>
  );
};

export default ProductPage;

useSearchParams: For URL query parameters (e.g., /search?query=react&page=1).

// pages/SearchPage.tsx
import React, { useEffect, useState } from 'react';
import { useSearchParams } from 'react-router-dom';

const SearchPage: React.FC = () => {
  const [searchParams, setSearchParams] = useSearchParams();
  const query = searchParams.get('query') || '';
  const page = searchParams.get('page') || '1';
  const [results, setResults] = useState<string[]>([]);

  useEffect(() => {
    if (query) {
      console.log(`Searching for "${query}" on page ${page}`);
      // Simulate API call
      setResults([`Result 1 for "${query}"`, `Result 2 for "${query}"`]);
    } else {
      setResults([]);
    }
  }, [query, page]);

  const handleSearch = (newQuery: string) => {
    setSearchParams(prev => {
      prev.set('query', newQuery);
      prev.set('page', '1'); // Reset page on new search
      return prev;
    });
  };

  const handleNextPage = () => {
    setSearchParams(prev => {
      prev.set('page', String(parseInt(page) + 1));
      return prev;
    });
  };

  return (
    <div>
      <h1>Search Results</h1>
      <input
        type="text"
        value={query}
        onChange={(e) => handleSearch(e.target.value)}
        placeholder="Search..."
      />
      {results.length > 0 ? (
        <ul>
          {results.map((res, index) => <li key={index}>{res}</li>)}
        </ul>
      ) : (
        <p>No results found for "{query}"</p>
      )}
      {query && <button onClick={handleNextPage}>Next Page (Current: {page})</button>}
    </div>
  );
};

export default SearchPage;

useSearchParams is particularly powerful because it gives you both the current search parameters and a setter function (setSearchParams) that works just like useState. This allows you to easily update query parameters while maintaining the rest, triggering re-renders only when relevant.

Advanced Insights and Lessons Learned

Here's the thing: most tutorials cover the basics. But from real-world projects, I've found a few areas that often get overlooked or cause headaches.

Nested Routes and Layouts with Outlet: This is a game-changer for complex applications. Instead of defining every single route explicitly, you can define a parent route that handles a common layout, and then use Outlet to render child routes within it. This dramatically reduces boilerplate and keeps your UI consistent.

// layouts/DashboardLayout.tsx
import React from 'react';
import { Outlet, Link } from 'react-router-dom';

const DashboardLayout: React.FC = () => {
  return (
    <div style={{ display: 'flex' }}>
      <aside style={{ width: '200px', borderRight: '1px solid #ccc' }}>
        <nav>
          <ul>
            <li><Link to="profile">Profile</Link></li> {/* Relative path! */}
            <li><Link to="settings">Settings</Link></li>
          </ul>
        </nav>
      </aside>
      <main style={{ flexGrow: 1, padding: '20px' }}>
        <Outlet /> {/* Renders the matched child route here */}
      </main>
    </div>
  );
};

// App.tsx (excerpt)
<Routes>
  <Route path="/" element={<HomePage />} />
  <Route path="/dashboard" element={<DashboardLayout />}>
    <Route path="profile" element={<ProfilePage />} />
    <Route path="settings" element={<SettingsPage />} />
    {/* /dashboard/profile and /dashboard/settings */}
  </Route>
  <Route path="*" element={<NotFoundPage />} />
</Routes>

Notice the relative paths in Link within DashboardLayout. This is a subtle but powerful feature that keeps your nested navigation self-contained.

Protected Routes (Authentication/Authorization): This is almost guaranteed in any real application. Instead of littering if (!user) checks everywhere, create a wrapper component.

// components/ProtectedRoute.tsx
import React from 'react';
import { Navigate, Outlet } from 'react-router-dom';

interface ProtectedRouteProps {
  isAuthenticated: boolean;
  redirectPath?: string;
}

const ProtectedRoute: React.FC<ProtectedRouteProps> = ({
  isAuthenticated,
  redirectPath = '/login', // Default redirect
}) => {
  if (!isAuthenticated) {
    return <Navigate to={redirectPath} replace />; // Redirect if not authenticated
  }
  return <Outlet />; // Render child routes if authenticated
};

// App.tsx (excerpt)
const isAuthenticated = /* your auth logic here, e.g., from context/redux */;
<Routes>
  <Route path="/login" element={<LoginPage />} />
  <Route element={<ProtectedRoute isAuthenticated={isAuthenticated} />}>
    {/* All routes within this element are protected */}
    <Route path="/dashboard/*" element={<DashboardLayout />} />
    <Route path="/profile" element={<UserProfilePage />} />
  </Route>
  <Route path="*" element={<NotFoundPage />} />
</Routes>

By nesting routes under ProtectedRoute, you centralize your auth logic, keeping your actual page components clean.

Error Boundaries for Route-Specific Errors: While not strictly a React Router feature, combining React's error boundaries with your routes can provide a much better user experience when a specific page or component crashes. Wrap individual Route elements or even the Routes component itself.

Common Pitfalls to Avoid

Forgetting BrowserRouter: Your entire routing setup won't work without it (or HashRouter for specific use cases).
Mixing Link and <a> tags: Always use Link for internal navigation. Regular <a> tags will trigger a full page reload, defeating the purpose of an SPA.
Over-complexifying path matching: V6's Routes component does smart matching. Avoid creating overly specific path values unless truly necessary. Simpler paths are often better.
Not handling 404s: Always include a Route path="*" element={<NotFoundPage />} /> as the last Route within your Routes to gracefully handle unknown URLs.
Mismanaging replace in navigate: Understand when you want to replace the current history entry versus pushing a new one. replace: true is crucial for post-form submissions or logout flows to prevent users from navigating back to stale/inaccessible pages.

Bringing it All Together

Mastering React Router isn't about memorizing every prop or hook, but understanding the declarative way it allows you to connect your application's UI to its URL. It's about thinking in terms of routes as states, and navigation as state transitions. Once you embrace this mindset, you'll find yourself building more robust, intuitive, and enjoyable user experiences.

So, next time you're mapping out your application's flow, remember these tools. They're designed to empower you, not to complicate things. Go forth, build amazing things, and navigate with confidence!

✨ 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 Frontend World Just Changed: 5 Shifts for 2026

Bishoy Bishai — Tue, 21 Apr 2026 11:44:49 +0000

The Frontend World Just Changed: 5 Shifts Professional Devs Need to Master for 2026

Remember that feeling when your app's Lighthouse score just wouldn't budge, no matter how much you minified or lazy-loaded? Or perhaps the endless debate about client-side rendering versus server-side rendering, each with its own set of trade-offs? For years, we've been operating within certain boundaries, defining "frontend" as primarily what happens in the browser. Well, that definition is getting a radical overhaul.

The frontend world, as we know it, is undergoing a profound transformation. We’re not just talking about new frameworks or libraries; we’re seeing fundamental shifts in architecture, deployment, and even the very purpose of what we build. As we hurtle towards 2026, I’ve identified five critical shifts that professional developers and engineering teams absolutely need to understand and embrace. Ignore them at your peril, because these aren't just trends – they're the new bedrock.

1. The Server-First Frontend (and the Edge): Beyond SSR, Welcome Server Components

For a long time, the client-server boundary was pretty clear-cut. Data was fetched from an API, usually on the client, and then rendered. SSR offered a performance boost, but often came with its own hydration costs and complexity. The big shift now? Server Components are fundamentally redefining where and how we render.

Next.js App Router, for example, heavily leans into this paradigm. You're no longer just fetching data from the server; you're rendering on the server, allowing your components to directly access backend resources. This isn’t just SSR with a fancy name; it’s about making your backend and frontend feel like one cohesive unit, without shipping unnecessary server-side logic or data fetching code to the client.

Why this matters:
In my experience, this has been a game-changer for initial page load performance and reducing client-side JavaScript bundles. Imagine a component that fetches user data directly from a database or an internal API without ever touching a client-side API layer.

// app/dashboard/page.tsx - A Server Component
import { getUserData } from '@/lib/server-db'; // Direct database access from server!

export default async function DashboardPage() {
  const user = await getUserData(); // Fetched directly on the server

  return (
    <main>
      <h1>Welcome, {user.name}!</h1>
      <p>Your email: {user.email}</p>
      {/* Client components can be imported and rendered here,
          but their interactivity code only loads when needed */}
      <ClientOnlyChart data={user.activityGraph} />
    </main>
  );
}

What most tutorials miss: It's not about abandoning client-side JavaScript entirely. It’s about intentionality. You split your components into Server Components (for static, data-fetching, or secure logic) and Client Components (for interactivity, hooks, and browser APIs). The trick is to identify the right boundary and minimize the "hydration tax" – the cost of JavaScript taking over static HTML. Overusing use client is a common pitfall that negates many of the benefits. Remember, Client Components still fetch data, Server Components access data.

The "Edge" extends this further, pushing computation and data fetching closer to the user, dramatically reducing latency for global audiences. Think about how much faster a personalized content feed can load when it’s generated just miles from the user, rather than across a continent.

2. Hyper-Personalization & AI Integration: Beyond Chatbots

AI has been a buzzword, but in frontend, it's quickly moving beyond chatbots into genuinely transformative applications. We're talking about dynamic UI generation, context-aware user experiences, and predictive interfaces that adapt in real-time.

Imagine an e-commerce site where product descriptions are subtly re-phrased to match a user's known preferences, or a landing page that dynamically re-arranges its sections based on inferred user intent – all orchestrated by AI models running either at the edge or through serverless functions.

Practical application:
Integrating AI often means interacting with APIs from services like OpenAI or custom models. But the magic happens when we use this to influence our frontend. For instance, an edge function could detect a user's location and preferred language, then use an LLM to generate localized content variations for a hero section on the fly, before the main page even loads.

// Example: Edge function (pseudo-code)
export async function generatePersonalizedHero(request) {
  const userGeo = getUserGeo(request); // Get user's location
  const prompt = `Generate a compelling hero headline for a tech conference
                  in ${userGeo.city}, highlighting AI and developer experience.`;

  const aiResponse = await openai.generateText({ prompt }); // Call AI API

  return new Response(JSON.stringify({ headline: aiResponse.text }), {
    headers: { 'Content-Type': 'application/json' },
  });
}

Insights: This isn't just about calling an API; it's about intelligent data plumbing. Focus on prompt engineering for UI elements, efficient data streaming, and most critically, ethical AI design. Pitfalls include over-automating leading to generic or even biased experiences, and neglecting the performance overhead of external AI calls. Always consider fallback content.

3. Performance as a Core Feature, Not an Afterthought

Core Web Vitals aren't going anywhere; they're becoming the baseline for what constitutes a "good" user experience. The good news is that modern frameworks and deployment platforms are baking performance into their very foundations, rather than making it an optimization step at the end.

Features like streaming HTML, partial hydration, advanced image optimization, and font loading strategies are now often handled automatically. Tools like Next.js's built-in Image component or the <Suspense> boundary for lazy-loading sections of your UI are perfect examples.

// Using Suspense for streaming UI
import { Suspense } from 'react';
import Loading from './loading'; // A simple loading spinner

async function BigDataComponent() {
  const data = await fetchExpensiveData(); // Imagine a slow API call
  return <div>{JSON.stringify(data)}</div>;
}

export default function Page() {
  return (
    <main>
      <h1>Your Dashboard</h1>
      <Suspense fallback={<Loading />}>
        {/* This component will render only when its data is ready */}
        <BigDataComponent />
      </Suspense>
      {/* Other parts of the page can render immediately */}
      <SomeOtherFastComponent />
    </main>
  );
}

Lessons learned from real projects: Don't just rely on default optimizations; understand them. While your framework might handle image optimization, choosing the right image format or understanding priority on Next.js's Image component can still make a huge difference. Architect for performance from the beginning by thinking about component boundaries and data dependencies. A common pitfall is to introduce a blocking script or huge client-side library where a Server Component could have done the job, or an optimized static asset.

4. Developer Experience (DX) is Paramount: Beyond Just Speed

It’s easy to focus on end-user experience, but developer experience (DX) is increasingly recognized as a key differentiator for successful teams. This isn’t just about hot module reloading (though we love that!), it’s about a holistic approach to making development intuitive, enjoyable, and less prone to errors.

This shift manifests in several ways:

Type Safety: TypeScript is now virtually non-negotiable for professional teams. It catches errors early, provides incredible IDE support, and improves code readability and maintainability.
Integrated Tooling: Modern frameworks often come with opinionated, integrated build systems, linters, and testing environments, reducing configuration fatigue.
Standardized Patterns: Best practices are often codified into the framework itself, guiding developers towards scalable and maintainable solutions (e.g., app directory structure in Next.js).

In my experience, investing in DX pays dividends in developer happiness, fewer bugs, and faster iteration cycles. When developers aren't fighting their tools or guessing at data shapes, they can focus on delivering value. Pitfalls here often involve trying to fight the framework's opinions or not fully embracing type safety, which leads to slower development and more runtime errors down the line.

5. The Rise of the "Frontend Platform": Your New Backend is a Service

The lines are blurring not just between client and server, but also between development and operations. Platforms like Vercel, Netlify, and Cloudflare Pages are no longer just hosting providers; they've evolved into comprehensive "frontend clouds."

They integrate deployment, CI/CD, serverless functions (for API routes or edge logic), database integrations, asset optimization, and analytics into a seamless, managed experience. This "platformization" means frontend teams can now deploy full-stack applications with serverless backends and edge functions without needing dedicated DevOps engineers or complex infrastructure management.

Relatable example: Deploying a full-stack Next.js application that fetches data from a serverless database (like Vercel Postgres or Supabase), uses edge functions for A/B testing, and automatically scales globally – all with a simple git push. This dramatically shrinks the cognitive load of managing infrastructure and frees up teams to focus purely on product features.

Key takeaway: This isn't about giving up control; it's about strategic outsourcing of undifferentiated heavy lifting. The pitfall is becoming too reliant on a single vendor without understanding the underlying concepts, or conversely, reinventing the wheel when a robust platform solution already exists. Embrace these platforms, but always strive to understand the underlying architecture and how to leverage their unique capabilities.

Embracing the Future

The frontend isn't just growing; it's evolving into something more powerful, integrated, and impactful than ever before. These five shifts represent not just technological advancements, but a fundamental re-imagining of what frontend development entails. For professional developers, it's an incredibly exciting time – a period ripe with opportunities to build richer, faster, and more intelligent user experiences. The key is continuous learning, challenging old assumptions, and actively participating in shaping this new world. Get ready to build the future!

✨ 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 Every Link You Share Shows Your Homepage Logo

Bishoy Bishai — Tue, 21 Apr 2026 09:19:12 +0000

Picture this. Someone finds your product. They're excited. They share it on LinkedIn.

The preview that appears: your site's generic homepage logo, the default title "My App — Build Something Great," and a description that reads "The best platform for modern developers."

Not the product they found. Not the image. Not the name. Not the price.

The person they shared it with clicks — or they don't. Usually they don't. Because the preview looked like spam.

That's not a marketing failure. That's a technical failure that happened because somewhere in the codebase, the <head> was treated as a special zone outside the normal component architecture. Someone hardcoded the meta tags in index.html once, and nobody thought to make them dynamic, because "the head" felt different from "the component tree."

It isn't. And the moment you stop treating it as different, a whole category of SEO and social sharing problems disappears.

I've worked on products where fixing the meta tag architecture, taking three days of careful implementation, measurably improved the click-through rate on shared links. Not from any new feature. Not from any marketing campaign. From making the preview show the right thing.

The Mental Model Shift: Two UIs, One Page

Here's the frame that changed everything for me.

Your React application has two user interfaces. The one your human users see — the <body>. And the one your non-human users see — the <head>.

The non-human users are: Googlebot, Bingbot, the LinkedIn link preview crawler, the Twitter card parser, the Slack unfurler, the WhatsApp link expander. Every time someone pastes your URL somewhere, one of these crawlers visits your page, reads the <head>, and uses that data to build a preview. That preview is often the first impression a new user gets of your content — before they even click.

Your <body> UI is beautifully component-driven. Data flows down. Props are explicit. Every product page shows the right product. Every user profile shows the right user.

Your <head> UI, in most codebases I've seen, is one of three things:

Hardcoded in index.html — same title, same description, same og:image for every single page
Managed by a library that feels complex — react-helmet, set up once, then inconsistently maintained
Done correctly in some pages and forgotten in others — the product of three different developers implementing it differently across six months

None of these are what you'd accept for your <body> UI. So why accept it for the <head>?

The answer is simple: <head> is just a React component. Feed it data. Render it conditionally. Test it. Treat it like any other piece of your component tree.

Why Static Meta Tags Are a Product Bug

Let me be specific about what goes wrong

Scenario 1 — The Social Share Problem

Your e-commerce site has 5,000 product pages. Every product has a unique name, unique description, unique image. You have one og:image tag in your index.html: your company logo.

Every time anyone shares any product anywhere, the preview shows your logo and your site name. Not the product. Not the price. Not the image that would make someone click.

Your competitors' links preview with the product photo, the name, and the price. Their click-through rate on shared links is significantly higher than yours. You'll never know this from your analytics because you're not tracking it as a separate failure mode.

Scenario 2 — The Search Result Problem

Google uses the <title> and <meta name="description"> to populate search results. If every page has the same title and description, Google has no basis for showing different descriptions per page — it will either generate them from page content (inconsistent) or show the same one for everything (terrible UX).

A user searching for "waterproof hiking boots size 10" sees your result: "My Outdoor Store — The Best Gear for Modern Adventurers." They see your competitor's result: "Men's Waterproof Hiking Boots — Size 10 Available | Free Shipping." They click the competitor.

Scenario 3 — The Duplicate Content Signal

When hundreds of your pages share the same title and description, Google may interpret this as thin content or duplicate content — signals that negatively affect your domain's overall authority. This is a slow, invisible damage to your rankings that compounds over time.

None of these problems are dramatic. They're all slow and invisible. And they all have the same root cause: the <head> was never treated as data-driven.

The Pattern: RouteHeadMeta

The core pattern is simple. Every route that has unique data should have a component responsible for translating that data into head meta tags. That component is just a React component — it receives props, it returns markup.

Let's build it properly, starting with the shared SEO interface that every framework approach will use:

// types/seo.ts
// Define the SEO data shape separately from your domain data.
// Your product has a name. The SEO builder decides how that name
// becomes a page title. Keep the transformation logic in one place.

export interface SEOMeta {
  title: string;
  description: string;
  canonicalUrl: string;
  ogImage?: string;
  ogType?: 'website' | 'article' | 'product';
  noIndex?: boolean;
  structuredData?: Record<string, unknown>;
}

interface Product {
  id: string;
  name: string;
  description: string;
  tagline?: string;
  seoDescription?: string;
  slug: string;
  price: number;
  inStock: boolean;
  images: Array<{ url: string; ogUrl?: string }>;
  category?: { defaultImage?: string };
}

// Builder function — transforms domain data into SEO data.
// Single responsibility: knows how products become meta tags.
// Framework-agnostic — used by all four approaches below.
export function buildProductSEO(product: Product, baseUrl: string): SEOMeta {
  return {
    title: buildPageTitle(product.name, 'YourBrand'),
    description: buildDescription(product),
    canonicalUrl: `${baseUrl}/products/${product.slug}`,
    ogImage: buildOgImage(product, baseUrl),
    ogType: 'product',
    structuredData: {
      '@context': 'https://schema.org',
      '@type': 'Product',
      name: product.name,
      description: product.description,
      image: product.images.map(img => img.url),
      offers: {
        '@type': 'Offer',
        price: product.price,
        priceCurrency: 'USD',
        availability: product.inStock
          ? 'https://schema.org/InStock'
          : 'https://schema.org/OutOfStock',
      },
    },
  };
}

// Title: max 60 chars for search results. Cut at word boundary.
function buildPageTitle(productName: string, brandName: string): string {
  const full = `${productName} — ${brandName}`;
  if (full.length <= 60) return full;

  const maxNameLen = 60 - ` — ${brandName}`.length;
  const cut = productName.slice(0, maxNameLen).trimEnd();
  const lastSpace = cut.lastIndexOf(' ');
  const clean = lastSpace > 0 ? cut.slice(0, lastSpace) : cut;
  return `${clean}... — ${brandName}`;
}

// Description: lead with the most important detail. Max 155 chars.
function buildDescription(product: Product): string {
  const sources = [
    product.seoDescription,
    product.tagline,
    product.description,
  ];
  const raw = sources.find(s => s && s.trim().length > 0);

  if (!raw) {
    // No description exists — use a generic fallback.
    // In production, this should also trigger a CMS content alert.
    return `Discover ${product.name} at YourBrand. Free shipping on orders over $50.`;
  }

  if (raw.length <= 155) return raw;
  return raw.slice(0, 152).trimEnd() + '...';
}

// og:image: never undefined for a product page.
// Use the first available image source from priority list.
function buildOgImage(product: Product, baseUrl: string): string {
  if (product.images[0]?.ogUrl) return product.images[0].ogUrl;
  if (product.images[0]?.url) return product.images[0].url;
  if (product.category?.defaultImage) return product.category.defaultImage;
  return `${baseUrl}/images/og-product-default.jpg`;
}

Now the framework-specific implementations — all using the same buildProductSEO function.

Approach 1: Next.js App Router (The Current Standard)

In Next.js App Router, the framework handles meta tag injection via generateMetadata. You export a function that returns a metadata object — Next.js puts it in the <head> on the server before the HTML leaves.

// app/products/[slug]/page.tsx

import type { Metadata } from 'next';
import { notFound } from 'next/navigation';
import { buildProductSEO } from '@/types/seo';
import { getProduct } from '@/lib/api';

interface PageProps {
  params: { slug: string };
}

// generateMetadata runs server-side before the page renders.
// Meta tags are baked into the HTML — Googlebot reads them in Wave 1.
// No JavaScript required. No flash. No client-side injection.
export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
  try {
    const product = await getProduct(params.slug);

    if (!product) {
      // Missing product — return minimal metadata, tell Google not to index
      return {
        title: 'Product Not Found — YourBrand',
        robots: { index: false, follow: false },
      };
    }

    const seo = buildProductSEO(product, 'https://yourbrand.com');

    return {
      title: seo.title,
      description: seo.description,
      alternates: { canonical: seo.canonicalUrl },
      openGraph: {
        title: seo.title,
        description: seo.description,
        url: seo.canonicalUrl,
        type: 'website',
        images: seo.ogImage
          ? [{ url: seo.ogImage, width: 1200, height: 630, alt: product.name }]
          : undefined,
      },
      twitter: {
        card: 'summary_large_image',
        title: seo.title,
        description: seo.description,
        images: seo.ogImage ? [seo.ogImage] : undefined,
      },
      robots: seo.noIndex ? { index: false, follow: false } : undefined,
    };
  } catch (error) {
    // Network error or database down — return safe defaults
    console.error('generateMetadata failed:', error);
    return { title: 'YourBrand' };
  }
}

// Next.js deduplicates fetch calls within the same request.
// Both generateMetadata and the page component can call getProduct(params.slug)
// — only ONE network request is made. Trust the framework.
export default async function ProductPage({ params }: PageProps) {
  const product = await getProduct(params.slug);
  if (!product) notFound();

  const seo = buildProductSEO(product, 'https://yourbrand.com');

  return (
    <main>
      {/* Structured data as a script tag in the component —
          generateMetadata handles title/og/twitter, this handles JSON-LD */}
      {seo.structuredData && (
        <script
          type="application/ld+json"
          dangerouslySetInnerHTML={{ __html: JSON.stringify(seo.structuredData) }}
        />
      )}
      <h1>{product.name}</h1>
      <p>{product.description}</p>
    </main>
  );
}

Approach 2: Remix (The `meta` Export)

Remix's meta export is a function at the route level that returns an array of meta descriptors. It runs server-side. Same philosophy, different API.

// routes/products.$slug.tsx

import type { MetaFunction, LoaderFunctionArgs } from '@remix-run/node';
import { json } from '@remix-run/node';
import { useLoaderData } from '@remix-run/react';
import { buildProductSEO } from '~/types/seo';

export async function loader({ params }: LoaderFunctionArgs) {
  const product = await getProduct(params.slug!);
  if (!product) throw new Response('Not Found', { status: 404 });
  // One fetch — both meta and component use this same data.
  // No double-fetching. No extra network request.
  return json({ product });
}

export const meta: MetaFunction<typeof loader> = ({ data }) => {
  if (!data?.product) {
    return [
      { title: 'Product Not Found — YourBrand' },
      { name: 'robots', content: 'noindex' },
    ];
  }

  const seo = buildProductSEO(data.product, 'https://yourbrand.com');

  return [
    { title: seo.title },
    { name: 'description', content: seo.description },
    { tagName: 'link', rel: 'canonical', href: seo.canonicalUrl },
    { property: 'og:title', content: seo.title },
    { property: 'og:description', content: seo.description },
    { property: 'og:url', content: seo.canonicalUrl },
    { property: 'og:type', content: seo.ogType ?? 'website' },
    ...(seo.ogImage ? [{ property: 'og:image', content: seo.ogImage }] : []),
    { name: 'twitter:card', content: 'summary_large_image' },
    { name: 'twitter:title', content: seo.title },
    { name: 'twitter:description', content: seo.description },
    ...(seo.ogImage ? [{ name: 'twitter:image', content: seo.ogImage }] : []),
  ];
};

export default function ProductPage() {
  const { product } = useLoaderData<typeof loader>();
  return (
    <main>
      <h1>{product.name}</h1>
      <p>{product.description}</p>
    </main>
  );
}

Approach 3: Next.js Pages Router

Still fully valid and widely used. Meta tags go via next/head inside the component.

// pages/products/[slug].tsx

import Head from 'next/head';
import type { GetStaticProps, GetStaticPaths } from 'next';
import { buildProductSEO } from '@/types/seo';

interface PageProps {
  product: Product;
}

export const getStaticProps: GetStaticProps<PageProps> = async ({ params }) => {
  const product = await getProduct(params!.slug as string);
  if (!product) return { notFound: true };
  return { props: { product }, revalidate: 3600 };
};

export const getStaticPaths: GetStaticPaths = async () => {
  const slugs = await getAllProductSlugs();
  return {
    paths: slugs.map(slug => ({ params: { slug } })),
    fallback: 'blocking',
  };
};

export default function ProductPage({ product }: PageProps) {
  const seo = buildProductSEO(product, 'https://yourbrand.com');

  return (
    <>
      {/* next/head with SSG/ISR = server-rendered meta tags.
          Same SEO benefit as App Router's generateMetadata. */}
      <Head>
        <title>{seo.title}</title>
        <meta name="description" content={seo.description} />
        <link rel="canonical" href={seo.canonicalUrl} />
        <meta property="og:title" content={seo.title} />
        <meta property="og:description" content={seo.description} />
        <meta property="og:url" content={seo.canonicalUrl} />
        <meta property="og:type" content={seo.ogType ?? 'website'} />
        {seo.ogImage && <meta property="og:image" content={seo.ogImage} />}
        <meta name="twitter:card" content="summary_large_image" />
        <meta name="twitter:title" content={seo.title} />
        <meta name="twitter:description" content={seo.description} />
        {seo.ogImage && <meta name="twitter:image" content={seo.ogImage} />}
        {seo.structuredData && (
          <script
            type="application/ld+json"
            dangerouslySetInnerHTML={{ __html: JSON.stringify(seo.structuredData) }}
          />
        )}
      </Head>
      <main>
        <h1>{product.name}</h1>
        <p>{product.description}</p>
      </main>
    </>
  );
}

Approach 4: Bare React SPA with react-helmet-async

For client-side only apps — internal tools, dashboards, SPAs without SSR. Use react-helmet-async, not react-helmet (the original is no longer maintained).

// npm install react-helmet-async

// src/main.tsx — wrap your entire app
import { HelmetProvider } from 'react-helmet-async';

function App() {
  return (
    <HelmetProvider>
      <Router>
        <Routes>
          <Route path="/products/:slug" element={<ProductPage />} />
        </Routes>
      </Router>
    </HelmetProvider>
  );
}

// src/pages/ProductPage.tsx

import { Helmet } from 'react-helmet-async';
import { useProduct } from '@/hooks/useProduct';
import { buildProductSEO } from '@/types/seo';

export function ProductPage() {
  const { slug } = useParams<{ slug: string }>();
  const { product, loading, error } = useProduct(slug!);

  // Render meta in loading state too — prevents title flash to "undefined"
  if (loading) {
    return (
      <>
        <Helmet><title>Loading... — YourBrand</title></Helmet>
        <ProductSkeleton />
      </>
    );
  }

  if (error || !product) {
    return (
      <>
        <Helmet>
          <title>Product Not Found — YourBrand</title>
          <meta name="robots" content="noindex" />
        </Helmet>
        <NotFoundMessage />
      </>
    );
  }

  const seo = buildProductSEO(product, window.location.origin);

  return (
    <>
      <Helmet>
        <title>{seo.title}</title>
        <meta name="description" content={seo.description} />
        <link rel="canonical" href={seo.canonicalUrl} />
        <meta property="og:title" content={seo.title} />
        <meta property="og:description" content={seo.description} />
        <meta property="og:url" content={seo.canonicalUrl} />
        {seo.ogImage && <meta property="og:image" content={seo.ogImage} />}
        <meta name="twitter:card" content="summary_large_image" />
        <meta name="twitter:title" content={seo.title} />
        <meta name="twitter:description" content={seo.description} />
        {seo.ogImage && <meta name="twitter:image" content={seo.ogImage} />}
      </Helmet>
      <main>
        <h1>{product.name}</h1>
        <p>{product.description}</p>
      </main>
    </>
  );
}

Important caveat: react-helmet-async injects meta tags client-side, after JavaScript runs. For public-facing pages where SEO matters, this means you're back in two-wave indexing territory. For internal tools where SEO is irrelevant — completely fine.

The Uncomfortable Truth About Meta Tags

Here's what most implementation guides don't say:

Meta tags without content strategy are decoration.

You can implement the most elegant, perfectly fallback-handled, SSR-rendered meta tag system in the world. If the content team hasn't written unique descriptions for your 5,000 product pages, your meta description will be auto-generated from page content — and Google will probably generate its own anyway, because yours isn't compelling enough.

The technical implementation is the container. What goes in it is what matters.

Two questions that actually determine whether your meta tags help:

Is the title unique per page, specific, and under 60 characters? If your product names in the database are 80+ characters, you have a content problem that truncation logic only partially solves.
Is the description compelling for a human reading a search result or a social preview? "A great product with amazing features" is a placeholder someone forgot to replace.

The developer's job is to make the system capable of showing the right thing. The content team's job is to ensure the right thing exists. Both jobs are required. Only one of them is in this article.

Real Objections

** "react-helmet-async is fine for my Next.js project, why bother with generateMetadata?"**

If your pages are server-rendered (SSG, ISR, or SSR), react-helmet-async injects meta tags client-side — after React hydrates. This creates a brief window where the server HTML has different meta content than what React inserts, which can cause hydration mismatches. Some crawlers are HTML-only and will miss client-injected meta tags entirely. generateMetadata and next/head with SSR inject server-side. That's the correct behavior for a server-rendered app.

** "Won't both generateMetadata and the page component double-fetch the product?"**

No — Next.js deduplicates fetch calls within the same request. If both generateMetadata and your page component call getProduct(params.slug), only one network request is made. This is by design. Don't try to pass data between generateMetadata and the page component directly — the API doesn't support it. Call the same function from both; trust the deduplication.

"What about ISR — does the meta get stale when the product data changes?"

Yes — ISR regenerates the page including meta tags at the revalidation interval. If a product's price changes between revalidations, the structured data price might be stale for up to revalidate seconds. For price-sensitive data, use cache: 'no-store' on that specific fetch, or shorten the revalidation window. The tradeoff between freshness and performance is real — know where you land on it per page type.

For more

📄 "The Open Graph protocol" — Official Spec at ogp.me
📄 "Sharing Debugger" — Meta for Developers
🎥 "Next.js Metadata API Deep Dive" by Lee Robinson on YouTube
💬

"Content is king, but distribution is queen. And she wears the pants."
— Jonathan Perelman, BuzzFeed

The <head> is a React component. Feed it data. Give it fallbacks. Treat it with the same care you give the rest of your component tree.

The user who shares your product page on LinkedIn deserves a preview that shows the right product. The Googlebot that crawls your page deserves a title that describes what it found. The developer who comes after you deserves a system predictable enough to maintain without fear.

All three of those requirements are met by the same thing: treating the <head> as data.

Simple? Yes. Easy? Only after the fallbacks. 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

The best place to hide a dead body is the second page of Google search results

Bishoy Bishai — Wed, 08 Apr 2026 11:39:04 +0000

*In 2026, Google CAN render your SPA. The question is WHEN

"Google renders JavaScript" is true. Here's the part they don't tell you:

Google renders JavaScript in two waves. And the gap between those waves is where your rankings live or die.

Wave 1 — The Crawler Pass:
Googlebot visits your URL. It downloads the HTML. If the HTML has content — actual text, headings, meta tags — it indexes that content immediately. Fast. Reliable. This is what happens with server-rendered pages.

Wave 2 — The Renderer Queue:
If your HTML is an empty shell with a <div id="root"></div> and a script tag, Googlebot puts your URL in a separate queue for JavaScript rendering. This queue is processed by a headless Chrome instance — but not immediately. Not even that day. It could be hours. It could be days. For large sites, it could be weeks.

During the time between Wave 1 and Wave 2, your page exists in Google's index with whatever was in that initial HTML. Which, for a React SPA, is essentially nothing.

Here's what makes this genuinely dangerous: the page is indexed. Google Search Console shows it as "Discovered — currently not indexed" or "Crawled — currently not indexed" — and then eventually "Indexed." You see it move through the states. You think it's working. But the content that was indexed in Wave 1 was thin or empty, and that initial signal affects how the page is treated in rankings even after Wave 2 processes it.

The SPA indexing timeline:

Day 1:  Googlebot visits → Sees empty HTML → Queues for JS rendering
Day 1-7: JS rendering queue processes → Content indexed
        (During this window: page either not indexed or indexed with thin content)

Day 7+: Full content indexed
        (But the initial quality signal was already recorded)

vs. Server-Rendered:

Day 1:  Googlebot visits → Sees full HTML content → Indexed immediately
        LCP: fast → positive quality signal
        Content: complete → correct ranking signals from day one

I'm not making this up. Google has documented the two-wave process. What they've been less clear about is the timing — which varies by site size, crawl budget, and how frequently you publish new content.

For a small site with fifty pages, this might be manageable. For a product with thousands of pages — a catalog, a marketplace, a documentation site — the crawl budget implications are significant. Google allocates a limited number of crawl requests per site per day. If each page requires two crawl passes (Wave 1 HTML + Wave 2 JavaScript rendering), you've effectively halved your crawl budget efficiency.

The Core Web Vitals Problem Nobody Talks About

Here's the second way client-side rendering hurts SEO even after your content is indexed:

Core Web Vitals are ranking factors. And client-side rendering has a structural disadvantage on the most important one.

LCP — Largest Contentful Paint measures how long it takes for the largest visible element on the page to render. For most pages, that's the hero image, the product photo, or the main heading.

In a client-side rendered React app, the sequence for the LCP element looks like this:

Browser receives empty HTML
Browser downloads JavaScript bundle (200KB? 500KB? More?)
React initializes
Component renders
useEffect fires, API call goes out
Data returns
Component re-renders with actual content
LCP element finally appears

Steps 2 through 8 all happen before the LCP clock stops. On a fast connection, this might be 1.5 seconds. On a 4G connection dropping to 3G in a moving car, this is 4-6 seconds. Google's threshold for "Good" LCP is under 2.5 seconds. "Poor" is over 4 seconds.

Client-Side Rendering LCP waterfall:

0ms      HTML received (empty)
|
200ms    JS bundle starts downloading
|
800ms    JS bundle finished downloading
|
850ms    React initializes
|
900ms    Component renders (shows loading spinner)
|
950ms    useEffect fires, API request sent
|
1400ms   API response received
|
1450ms   Component re-renders with content
|        ← LCP recorded here
1450ms   [LCP: 1.45s on fast fiber. Multiply by 3x on mobile 4G.]

Server-Side Rendering LCP waterfall:

0ms      HTML request sent
|
300ms    Server fetches data + renders HTML
|
300ms    Browser receives full HTML with content already inside
|        ← LCP recorded here (the heading/image was in the HTML)
300ms    [LCP: ~300ms. JS loads in background for interactivity.]

The difference isn't a performance trick. It's architectural. The server did the work before the bytes left the data center. The browser got a complete page, not a promise of a page.

The product I work on at currently — we have pages where LCP improvements directly correlated with conversion rate improvements. A 400ms improvement in LCP on the support portal's main landing pages reduced bounce rate measurably. The SEO and the business outcome are the same metric wearing different clothes.

Which Pages You Cannot Afford to Get Wrong

Not every page in your app carries the same SEO risk. The mistake is treating them all the same.

Pages that absolutely need server rendering:

These are the pages where a search engine discovering thin content, slow LCP, or missing metadata will cost you rankings that are hard to recover.

Landing pages — your homepage, product pages, category pages. These are where acquisition happens. Get them wrong and you're invisible to people who haven't heard of you.
Blog and content pages — the long-tail keywords live here. If the content isn't in the initial HTML, you're competing at a disadvantage.
Product detail pages — especially if you have thousands of them. Crawl budget matters at scale.
Any page you want to rank for a specific keyword — if ranking matters, server rendering matters.

Pages where client-side rendering is absolutely fine:

Authenticated dashboards — nobody Googles their way into your admin panel. SEO is irrelevant here.
Real-time features — live data, WebSocket-driven UIs, collaborative tools. Server rendering adds complexity for zero SEO benefit.
Highly interactive tools — calculators, configurators, complex form flows. The interactivity IS the product.
User-generated content behind login — private by design, no crawlers should see it.

The architectural decision: know which pages are acquisition pages and which are retention pages. Acquisition pages need server rendering. Retention pages can be client-side. Most apps contain both — and treating them all the same is leaving rankings on the table.

Building the Next.js SEO Stack — Complete Implementation

Let's build this properly. Four layers: rendering strategy, metadata, structured data, performance.

Layer 1: Rendering Strategy Per Page Type

The App Router makes this natural — each page's data fetching strategy determines its rendering behavior.

// app/products/[id]/page.tsx
// Server Component — rendered on the server, HTML sent to browser
// Googlebot receives full product content in Wave 1. No Wave 2 needed.

interface Product {
  id: string;
  name: string;
  description: string;
  price: number;
  images: string[];
  category: string;
  inStock: boolean;
}

interface ProductPageProps {
  params: { id: string };
}

async function ProductPage({ params }: ProductPageProps) {
  // This fetch runs on the server during the request.
  // Product data is baked into the HTML before it leaves your server.
  // No useEffect. No loading state for the initial content.
  const product = await fetch(`https://api.yourstore.com/products/${params.id}`, {
    // revalidate: 3600 = cache this for 1 hour, then revalidate in background.
    // ISR behavior — static-site speed, fresh-enough data.
    next: { revalidate: 3600 }
  }).then(res => {
    if (!res.ok) throw new Error('Product not found');
    return res.json() as Promise<Product>;
  });

  return (
    <main>
      {/* This H1 is in the HTML. Googlebot reads it in Wave 1.
          It's the most important on-page SEO signal. */}
      <h1>{product.name}</h1>

      {/* Product description — in the HTML, indexed immediately */}
      <p>{product.description}</p>

      {/* Price — in the HTML, used for rich snippets with structured data */}
      <p aria-label={`Price: $${product.price}`}>${product.price}</p>

      {/* The add-to-cart interaction is client-side — that's fine.
          The CONTENT is server-rendered. The INTERACTION is client-side.
          This is the correct split. */}
      <AddToCartButton productId={product.id} inStock={product.inStock} />
    </main>
  );
}

export default ProductPage;

// components/AddToCartButton.tsx
// 'use client' — this component runs in the browser
// It handles interaction. It doesn't need to be server-rendered.
'use client';

import { useState } from 'react';

interface AddToCartButtonProps {
  productId: string;
  inStock: boolean;
}

export function AddToCartButton({ productId, inStock }: AddToCartButtonProps) {
  const [adding, setAdding] = useState(false);
  const [added, setAdded] = useState(false);

  if (!inStock) {
    return <button disabled>Out of Stock</button>;
  }

  const handleClick = async () => {
    setAdding(true);
    await addToCart(productId);
    setAdding(false);
    setAdded(true);
  };

  return (
    <button onClick={handleClick} disabled={adding}>
      {added ? '✓ Added to Cart' : adding ? 'Adding...' : 'Add to Cart'}
    </button>
  );
}

For static content like blog posts — build-time generation:

// app/blog/[slug]/page.tsx
// generateStaticParams: generate HTML for all posts at build time.
// Result: CDN-served static HTML. Zero server computation per request.
// Googlebot gets full content instantly on Wave 1. Always.

export async function generateStaticParams() {
  const posts = await fetch('https://cms.yoursite.com/posts?fields=slug')
    .then(res => res.json());

  return posts.map((post: { slug: string }) => ({
    slug: post.slug,
  }));
}

async function BlogPost({ params }: { params: { slug: string } }) {
  const post = await fetch(`https://cms.yoursite.com/posts/${params.slug}`)
    .then(res => res.json());

  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.htmlContent }} />
    </article>
  );
}

Layer 2: Metadata That Actually Works

// app/layout.tsx — Root layout metadata, the defaults every page inherits

import type { Metadata } from 'next';

export const metadata: Metadata = {
  title: {
    template: '%s | YourBrand',
    default: 'YourBrand — What You Do in One Line',
  },
  description: 'Your default meta description — 150-160 characters, compelling, includes your main keyword.',

  openGraph: {
    type: 'website',
    locale: 'en_US',
    url: 'https://yourbrand.com',
    siteName: 'YourBrand',
    images: [
      {
        url: 'https://yourbrand.com/og-image.jpg',
        width: 1200,
        height: 630,
        alt: 'YourBrand — brief description',
      },
    ],
  },

  twitter: {
    card: 'summary_large_image',
    site: '@yourbrandhandle',
  },

  alternates: {
    canonical: 'https://yourbrand.com',
  },

  robots: {
    index: true,
    follow: true,
    googleBot: {
      index: true,
      follow: true,
      'max-video-preview': -1,
      'max-image-preview': 'large',
      'max-snippet': -1,
    },
  },
};

// app/products/[id]/page.tsx — page-level metadata override

export async function generateMetadata(
  { params }: { params: { id: string } }
): Promise<Metadata> {
  const product = await fetch(`https://api.yourstore.com/products/${params.id}`)
    .then(res => res.json() as Promise<Product>);

  const description = product.description.slice(0, 155);
  const canonicalUrl = `https://yourbrand.com/products/${params.id}`;
  const imageUrl = product.images[0] ?? 'https://yourbrand.com/og-default.jpg';

  return {
    title: product.name, // Renders as "Product Name | YourBrand"
    description,
    openGraph: {
      type: 'website',
      title: product.name,
      description,
      url: canonicalUrl,
      images: [{ url: imageUrl, width: 1200, height: 630, alt: product.name }],
    },
    // Canonical URL — critical for products accessible via multiple URLs
    alternates: {
      canonical: canonicalUrl,
    },
  };
}

Layer 3: Structured Data — The Part Everyone Skips

Structured data is the difference between appearing in search results and appearing in rich search results. Product prices, ratings, availability, article publish dates, FAQ dropdowns — these all come from structured data. They improve click-through rates, which improves rankings. The loop is real.

// components/ProductStructuredData.tsx

interface ProductSDProps {
  product: {
    id: string;
    name: string;
    description: string;
    price: number;
    currency: string;
    inStock: boolean;
    images: string[];
    brand: string;
    sku: string;
    rating?: { average: number; count: number };
  };
  url: string;
}

export function ProductStructuredData({ product, url }: ProductSDProps) {
  const structuredData = {
    '@context': 'https://schema.org',
    '@type': 'Product',
    name: product.name,
    description: product.description,
    image: product.images,
    brand: { '@type': 'Brand', name: product.brand },
    sku: product.sku,
    offers: {
      '@type': 'Offer',
      url,
      priceCurrency: product.currency,
      price: product.price,
      // Use Schema.org availability values — not custom strings
      availability: product.inStock
        ? 'https://schema.org/InStock'
        : 'https://schema.org/OutOfStock',
      seller: { '@type': 'Organization', name: product.brand },
    },
    // Only include aggregateRating if you have REAL ratings visible on the page.
    // Google validates structured data against visible content.
    // Fake ratings get you penalized.
    ...(product.rating && {
      aggregateRating: {
        '@type': 'AggregateRating',
        ratingValue: product.rating.average,
        reviewCount: product.rating.count,
        bestRating: 5,
        worstRating: 1,
      },
    }),
  };

  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: JSON.stringify(structuredData) }}
    />
  );
}

// For blog posts — Article structured data
export function ArticleStructuredData({ post, url, authorName }: ArticleSDProps) {
  const structuredData = {
    '@context': 'https://schema.org',
    '@type': 'Article',
    headline: post.title,
    description: post.excerpt,
    image: post.featuredImage,
    author: {
      '@type': 'Person',
      name: authorName,
      url: `https://yourbrand.com/authors/${post.authorSlug}`,
    },
    publisher: {
      '@type': 'Organization',
      name: 'YourBrand',
      logo: {
        '@type': 'ImageObject',
        url: 'https://yourbrand.com/logo.png',
      },
    },
    datePublished: post.publishedAt,
    dateModified: post.updatedAt,
    mainEntityOfPage: {
      '@type': 'WebPage',
      '@id': url,
    },
  };

  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: JSON.stringify(structuredData) }}
    />
  );
}

Layer 4: The next/image Non-Negotiable

Red card for any developer using <img> instead of Next.js Image on content pages.

import Image from 'next/image';

// 🚫 The LCP killer
function BadProductImage({ src, alt }: { src: string; alt: string }) {
  return (
    <img
      src={src}
      alt={alt}
      // No width/height = layout shift = bad CLS score
      // No lazy loading = all images load at once = slow LCP
      // No format optimization = 800KB JPEG instead of 80KB WebP
    />
  );
}

// ✅ The correct implementation
function ProductImage({ src, alt }: { src: string; alt: string }) {
  return (
    <Image
      src={src}
      alt={alt}
      width={800}
      height={600}
      // priority = "this is the LCP element — preload it"
      // Use on the main product image, hero images, above-the-fold content.
      // Don't use on every image — that defeats the purpose.
      priority
      // sizes = which image size to download at which viewport.
      // Without this, mobile downloads the full 800px image unnecessarily.
      sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 800px"
      style={{ objectFit: 'cover' }}
    />
  );
}

The priority prop is the one developers most consistently miss. Without it, even with Next.js image optimization, the LCP image might be lazy-loaded — which means it doesn't start loading until the user's viewport encounters it. For the main product image that's always above the fold, that's wrong. priority preloads the image, which is often the difference between a Good and a Poor LCP score.

The Sitemap You're Probably Not Generating Correctly

// app/sitemap.ts — generates /sitemap.xml dynamically

import { MetadataRoute } from 'next';

export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  const [products, posts] = await Promise.all([
    fetch('https://api.yourstore.com/products?fields=id,updatedAt').then(r => r.json()),
    fetch('https://cms.yoursite.com/posts?fields=slug,updatedAt').then(r => r.json()),
  ]);

  const productUrls: MetadataRoute.Sitemap = products.map(
    (product: { id: string; updatedAt: string }) => ({
      url: `https://yourbrand.com/products/${product.id}`,
      lastModified: new Date(product.updatedAt),
      changeFrequency: 'weekly',
      priority: 0.8,
    })
  );

  const postUrls: MetadataRoute.Sitemap = posts.map(
    (post: { slug: string; updatedAt: string }) => ({
      url: `https://yourbrand.com/blog/${post.slug}`,
      lastModified: new Date(post.updatedAt),
      changeFrequency: 'monthly',
      priority: 0.6,
    })
  );

  return [
    {
      url: 'https://yourbrand.com',
      lastModified: new Date(),
      changeFrequency: 'daily',
      priority: 1.0,
    },
    ...productUrls,
    ...postUrls,
  ];
}

// app/robots.ts — generates /robots.txt

import { MetadataRoute } from 'next';

export default function robots(): MetadataRoute.Robots {
  return {
    rules: [
      {
        userAgent: '*',
        allow: '/',
        // Don't waste crawl budget on authenticated routes
        disallow: ['/dashboard/', '/account/', '/api/'],
      },
    ],
    sitemap: 'https://yourbrand.com/sitemap.xml',
  };
}

Here's what I want to say:

Technical SEO is necessary but not sufficient. You can implement everything in this article perfectly — server rendering, metadata, structured data, image optimization, sitemaps — and still rank poorly if your content is thin, your site has no backlinks, and your pages don't answer the questions people are actually searching for.

The technical foundation is the floor. It's the thing that stops technical mistakes from being the reason you don't rank. But it doesn't create rankings by itself.

The developers who understand this stop treating SEO as a technical checklist and start asking: "Does this page genuinely answer the question someone typed into Google?" That question is harder than any of the implementation work. It requires talking to the product team, the content team, the users. It requires humility about whether what you've built is actually useful to a stranger.

Technical excellence in service of thin content is a well-optimized empty shelf.

That said — the technical floor matters enormously. The page that answers the question perfectly AND has proper server rendering AND fast LCP AND correct metadata beats the page that answers the question perfectly but delivers it as a client-side spinner. Every time.

Build the floor. Then fill the shelf.

But

** "Google has gotten better at rendering JavaScript. Isn't this all outdated advice?"**

Google has genuinely improved JavaScript rendering. For small sites with limited pages, client-side rendering might work fine. But "works fine" and "optimal" are different things. The two-wave indexing delay is real and documented. The LCP disadvantage of client-side rendering is architectural, not a rendering quality issue. And for sites at scale — thousands of pages — crawl budget efficiency still strongly favors server rendering. The advice isn't outdated; the risk profile has changed. It's lower risk than 2018. It's not zero risk.

"I can fix LCP with client-side rendering by optimizing my bundle and using React.lazy."

Bundle optimization and code splitting reduce JavaScript parsing time, which helps. But they don't change the fundamental sequence: the browser still needs to download JS, execute JS, and fetch data before the LCP element appears. Server rendering moves the data fetch to the server, before the first byte reaches the browser. These are different optimizations solving different bottlenecks. You can optimize a client-rendered app to good LCP scores — but you're working harder to reach the same place a server-rendered app starts at.

"This is all Next.js specific. What about Remix, Astro, or other frameworks?"

The principles — server rendering acquisition pages, proper metadata, structured data, image optimization — apply regardless of framework. Remix has excellent SSR. Astro's island architecture naturally server-renders content with minimal JavaScript. The Next.js implementation details in this article are specific, but the mental model transfers. Pick the framework that fits your team; implement the principles regardless.

📚 For more you can check

✨ 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

Dark Mode Isn't a Feature. It's a Promise. Here's How to Keep It.

Bishoy Bishai — Tue, 07 Apr 2026 12:13:19 +0000

Every flash of white on a dark-mode screen is your app saying: "I wasn't listening." Let's fix that.

"Good design is invisible."
— Dieter Rams

There's a specific kind of frustration that lives in the gap between what a user has configured and what your app delivers.

The user has been running their entire OS in dark mode for two years. Their phone, their terminal, their code editor, their email client — everything dark. Then they open your web app. The screen explodes with white. Their eyes adjust. They find the toggle buried in settings somewhere. They switch to dark mode. They close the tab.

Tomorrow, they open the app again. White screen. Again.

That's not a UX bug. That's a broken promise. The user told your application something — "I prefer dark" — and your application ignored it, forgot it, or never listened in the first place.

I've been that user. I've also been the developer who shipped that app. Both experiences are instructive, but only one of them is embarrassing in retrospect.

At one of my ex-company — the mental health platform where I built the first mobile app — UI decisions carried weight I hadn't fully considered before. When the product is something people use during difficult moments, at night, often in bed, a blinding white flash on load isn't just annoying. It's the app announcing its indifference to the person on the other side of the screen. That's when I stopped treating dark mode as a checkbox feature and started treating it as the first test of whether the UI actually listens.

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

Build a dark mode implementation that respects the OS preference without requiring user action
Eliminate FOUC (Flash of Unstyled Content) completely — including why it happens and the exact script that kills it
Build a persistence layer that remembers the user's explicit choice without fighting against their system preferences
Understand the three trust layers of a correct dark mode implementation and which one most apps get wrong
Walk away with production-ready code you can drop into any React app today

This is not a "here's the toggle" tutorial. Those exist. This is the thinking behind the implementation — the part that makes the difference between dark mode that works and dark mode that listens.

The Three Trust Layers — This Is the Mental Model

Before a single line of code, understand this framework. Every dark mode implementation lives somewhere on a spectrum of how much it trusts the user. Most implementations get Layer 1 wrong, ignore Layer 2 entirely, and accidentally break Layer 3.

Layer 1 — Trust the System

Your user has already told their operating system their preference. That preference is a signal. Ignoring it on first load is the equivalent of asking someone "what language do you speak?" when they've already been talking to you for five minutes.

The prefers-color-scheme media query gives you this signal for free. The question is whether you're listening.

Layer 2 — Trust the Session

The user has explicitly toggled your app's theme. That's an override — they're saying "I know what my system says, but for this app, I want this." This explicit choice must survive page reloads, browser restarts, and new tabs. localStorage is your memory here.

Layer 3 — Trust the Render

This is the one most apps fail. Even if you've correctly read the system preference and correctly stored the user's choice — if your JavaScript runs after your CSS paints, the user sees the wrong theme for 100-300 milliseconds before it corrects itself. That flash is your app saying "I knew the right answer, I just told you the wrong thing first."

A correct implementation satisfies all three layers, in this order of priority:

Layer 2 (explicit user choice) > Layer 1 (system preference) > default (light)

And Layer 3 — the render trust — is not optional. It's the silent contract. The user never sees it when it works. They only notice when it breaks.

The Foundation: CSS Variables as Theme Tokens

Here's the thing about dark mode implementations that use JavaScript to swap classes or manipulate styles directly: they're fighting the browser. CSS already knows how to cascade values. CSS already knows how to respond to selectors. Let it do its job.

CSS Custom Properties — CSS Variables — are the right primitive for this problem. Not because they're modern or elegant (though they are both), but because they let you express the relationship between a theme decision and a visual result in one place, and then change the decision without touching the visual rules.

/* globals.css */

/* Layer 1: System preference — the default, no JavaScript required */
:root {
  --color-bg-primary: #ffffff;
  --color-bg-secondary: #f5f5f5;
  --color-bg-card: #ffffff;
  --color-text-primary: #1a1a1a;
  --color-text-secondary: #666666;
  --color-text-muted: #999999;
  --color-accent: #0070f3;
  --color-accent-hover: #0051cc;
  --color-border: #e5e5e5;
  --color-shadow: rgba(0, 0, 0, 0.08);

  /* Transitions — applied once here, inherited everywhere */
  --transition-theme: background-color 0.25s ease, color 0.25s ease, border-color 0.25s ease;
}

/* System prefers dark — no JavaScript, no React, pure CSS */
@media (prefers-color-scheme: dark) {
  :root {
    --color-bg-primary: #0d0d0d;
    --color-bg-secondary: #1a1a1a;
    --color-bg-card: #1e1e1e;
    --color-text-primary: #ededed;
    --color-text-secondary: #a0a0a0;
    --color-text-muted: #666666;
    --color-accent: #3b82f6;
    --color-accent-hover: #60a5fa;
    --color-border: #2a2a2a;
    --color-shadow: rgba(0, 0, 0, 0.4);
    /* Note: shadows in dark mode need MORE opacity, not less.
       Light on dark needs a stronger shadow to maintain depth perception. */
  }
}

/* Layer 2: Explicit user choice via data-theme attribute.
   These override the @media query above.
   If the user says "light" on a dark-mode system, we listen. */
[data-theme='light'] {
  --color-bg-primary: #ffffff;
  --color-bg-secondary: #f5f5f5;
  --color-bg-card: #ffffff;
  --color-text-primary: #1a1a1a;
  --color-text-secondary: #666666;
  --color-text-muted: #999999;
  --color-accent: #0070f3;
  --color-accent-hover: #0051cc;
  --color-border: #e5e5e5;
  --color-shadow: rgba(0, 0, 0, 0.08);
}

[data-theme='dark'] {
  --color-bg-primary: #0d0d0d;
  --color-bg-secondary: #1a1a1a;
  --color-bg-card: #1e1e1e;
  --color-text-primary: #ededed;
  --color-text-secondary: #a0a0a0;
  --color-text-muted: #666666;
  --color-accent: #3b82f6;
  --color-accent-hover: #60a5fa;
  --color-border: #2a2a2a;
  --color-shadow: rgba(0, 0, 0, 0.4);
}

/* Component styles use variables — never hardcoded values.
   This is the rule. No exceptions. */
body {
  background-color: var(--color-bg-primary);
  color: var(--color-text-primary);
  transition: var(--transition-theme);
}

Notice the naming: --color-text-primary, not --dark-grey or --almost-white. This is semantic naming — the variable describes its role, not its current value. When you name it --dark-grey, you're forcing yourself to use a confusingly-named variable in light mode. When you name it --color-text-primary, it means the same thing in both themes: "this is what primary text looks like."

I've inherited codebases where someone named variables --light-background and then used it in the dark theme because it was "the right shade." Don't be that person. Name the role. Let the value change.

Layer 3 First: Killing the FOUC Before React Loads

I'm going to explain Layer 3 before building the React implementation — because if you don't understand why the flash happens, you'll implement the React part correctly and still ship the flash.

Here's the sequence of events when a user loads your React app:

Browser requests the HTML file
Browser receives HTML — at this point, no CSS, no JavaScript has run
Browser parses HTML, discovers <link> for CSS and <script> for JS
Browser downloads and applies CSS — page renders with default theme values (no data-theme attribute yet)
Browser downloads JavaScript bundle
React initializes
ThemeProvider runs, reads localStorage, calls document.documentElement.setAttribute('data-theme', ...)
CSS variables update, theme corrects

Steps 4 through 7 can take anywhere from 50ms to 500ms depending on bundle size and network. In that window, the user sees the default theme — light — even if their localStorage says dark and their system says dark.

That's the flash. It's not a React bug. It's a timing problem. JavaScript runs after CSS renders.

The only solution is to run the theme-detection code before JavaScript loads. Not in React. Not in a hook. In a synchronous <script> tag in the <head> — the kind that blocks rendering until it executes.

<!-- public/index.html — inside <head>, BEFORE any stylesheet links -->
<!-- Why before stylesheets? Because we want data-theme set before CSS cascades. -->
<script>
  (function() {
    // This runs synchronously, before the browser renders anything.
    // No React. No hooks. Just vanilla JavaScript at the earliest possible moment.

    function getInitialTheme() {
      // Priority 1: explicit user choice stored in localStorage
      try {
        // Wrap in try/catch — localStorage can throw in some 
        // private browsing modes or with certain security policies
        var storedTheme = localStorage.getItem('app-theme');
        if (storedTheme === 'dark' || storedTheme === 'light') {
          return storedTheme;
        }
      } catch (e) {
        // localStorage unavailable — fall through to system preference
      }

      // Priority 2: system preference
      if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
        return 'dark';
      }

      // Priority 3: default
      return 'light';
    }

    // Set the attribute immediately — before CSS cascades, before React runs.
    // When the browser renders the first frame, data-theme is already correct.
    document.documentElement.setAttribute('data-theme', getInitialTheme());
  })();
</script>

This script is intentionally minimal. No imports. No dependencies. No async operations. It runs in under a millisecond, sets the data-theme attribute, and gets out of the way. By the time the browser renders the first frame of your page, the attribute is already set, and the CSS variables already have the correct values.

For Next.js users: the public/index.html approach doesn't work in Next.js. You need _document.tsx:

// pages/_document.tsx
import { Html, Head, Main, NextScript } from 'next/document';

// This is a string — intentional.
// We're injecting raw JavaScript into the document.
// It needs to be a script that runs before React hydration.
const themeScript = `
  (function() {
    function getInitialTheme() {
      try {
        var stored = localStorage.getItem('app-theme');
        if (stored === 'dark' || stored === 'light') return stored;
      } catch (e) {}
      return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
    }
    document.documentElement.setAttribute('data-theme', getInitialTheme());
  })();
`;

export default function Document() {
  return (
    <Html>
      <Head>
        {/* dangerouslySetInnerHTML is correct here — we're injecting a known, 
            controlled script. The "dangerous" part is using it with user input.
            This is a static string we wrote. */}
        <script dangerouslySetInnerHTML={{ __html: themeScript }} />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

Test this: disable JavaScript in your browser. Open your app. The correct theme should still be applied — because the CSS @media (prefers-color-scheme: dark) handles the system preference without any JavaScript at all. Enable JavaScript. The data-theme attribute handles user overrides. This is a graceful degradation stack, not a JavaScript dependency.

The React Layer: Context, Hook, and State Management

Now we build the React side. The job of the React layer is to:

Read the initial theme (which the inline script already set on <html>)
Provide a toggle that updates both the DOM attribute and localStorage
Listen for OS-level changes and respond — but only if the user hasn't made an explicit choice

// src/contexts/ThemeContext.tsx

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

type Theme = 'light' | 'dark';

interface ThemeContextValue {
  theme: Theme;           // Current active theme
  toggleTheme: () => void; // Flip between light and dark
  setTheme: (t: Theme) => void; // Set explicitly
  isSystemTheme: boolean; // True if no explicit user choice has been made
  clearOverride: () => void; // Remove the explicit choice, defer back to system
}

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

// The localStorage key — define once, reference everywhere.
// Changing this key means existing user preferences are lost.
const STORAGE_KEY = 'app-theme';

function readStoredTheme(): Theme | null {
  try {
    const stored = localStorage.getItem(STORAGE_KEY);
    if (stored === 'light' || stored === 'dark') return stored;
  } catch {
    // localStorage unavailable
  }
  return null;
}

function getSystemTheme(): Theme {
  if (typeof window === 'undefined') return 'light'; // SSR guard
  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
}

function applyTheme(theme: Theme): void {
  // Set the attribute that our CSS variables respond to.
  // This is the single source of visual truth.
  document.documentElement.setAttribute('data-theme', theme);
}

export function ThemeProvider({ children }: { children: ReactNode }) {
  // Initialize from localStorage first, then system preference.
  // This mirrors the inline script exactly — they must agree.
  const [explicitTheme, setExplicitTheme] = useState<Theme | null>(() => {
    return readStoredTheme();
  });

  const [systemTheme, setSystemTheme] = useState<Theme>(() => {
    return getSystemTheme();
  });

  // The active theme: explicit choice wins over system
  const theme: Theme = explicitTheme ?? systemTheme;
  const isSystemTheme = explicitTheme === null;

  // Apply theme to DOM whenever it changes.
  // This handles the React lifecycle — the inline script handles first paint.
  useEffect(() => {
    applyTheme(theme);
  }, [theme]);

  // Listen for OS-level theme changes.
  // Respond ONLY if the user hasn't made an explicit choice.
  useEffect(() => {
    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');

    const handleSystemChange = (e: MediaQueryListEvent) => {
      const newSystemTheme: Theme = e.matches ? 'dark' : 'light';
      setSystemTheme(newSystemTheme);
      // If the user has an explicit override, don't touch it.
      // If they're on system default, follow the system.
      if (readStoredTheme() === null) {
        applyTheme(newSystemTheme);
      }
    };

    mediaQuery.addEventListener('change', handleSystemChange);
    return () => mediaQuery.removeEventListener('change', handleSystemChange);
  }, []);

  const setTheme = useCallback((newTheme: Theme) => {
    try {
      localStorage.setItem(STORAGE_KEY, newTheme);
    } catch {
      // localStorage unavailable — theme will still work for the session
    }
    setExplicitTheme(newTheme);
    // applyTheme is called by the useEffect above when explicitTheme changes
  }, []);

  const toggleTheme = useCallback(() => {
    setTheme(theme === 'light' ? 'dark' : 'light');
  }, [theme, setTheme]);

  // Let the user go back to "follow the system" — remove their explicit choice.
  const clearOverride = useCallback(() => {
    try {
      localStorage.removeItem(STORAGE_KEY);
    } catch {}
    setExplicitTheme(null);
    // Theme will now follow systemTheme
  }, []);

  return (
    <ThemeContext.Provider value={{ theme, toggleTheme, setTheme, isSystemTheme, clearOverride }}>
      {children}
    </ThemeContext.Provider>
  );
}

export function useTheme(): ThemeContextValue {
  const context = useContext(ThemeContext);
  if (!context) {
    throw new Error('useTheme must be used within a ThemeProvider');
  }
  return context;
}

One thing I added that the original article didn't have: isSystemTheme and clearOverride. These matter more than they seem.

If your user is on system dark mode, explicitly switches to light in your app, and then changes their OS to light mode — what happens? With isSystemTheme, you can show a UI hint: "You're using light mode (your system is now also light — sync?)" and give them the clearOverride option to stop managing it manually. Small detail. Enormous UX thoughtfulness.

The Toggle Component — and the Three-State Option

// src/components/ThemeToggle.tsx
'use client'; // Next.js App Router users need this

import { useTheme } from '../contexts/ThemeContext';

export function ThemeToggle() {
  const { theme, toggleTheme, isSystemTheme, clearOverride } = useTheme();

  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
      <button
        onClick={toggleTheme}
        // aria-label is not optional. A screen reader user needs to know
        // what the button will DO, not what the current state is.
        // "Switch to dark mode" tells them the action. "Dark mode: on" tells them the state.
        // Both have valid use cases — pick one and be consistent.
        aria-label={`Switch to ${theme === 'light' ? 'dark' : 'light'} mode`}
        aria-pressed={theme === 'dark'} // Tells screen readers this is a toggle
        style={{
          background: 'none',
          border: '1px solid var(--color-border)',
          borderRadius: '6px',
          padding: '6px 12px',
          cursor: 'pointer',
          color: 'var(--color-text-primary)',
          // The button itself uses theme variables — it doesn't need special dark mode handling
        }}
      >
        {theme === 'light' ? '🌙 Dark' : '☀️ Light'}
      </button>

      {/* Only show the "use system" option if the user has an explicit override.
          No point offering "follow system" if they're already following it. */}
      {!isSystemTheme && (
        <button
          onClick={clearOverride}
          aria-label="Use system theme preference"
          style={{
            background: 'none',
            border: 'none',
            cursor: 'pointer',
            color: 'var(--color-text-muted)',
            fontSize: '0.8rem',
            padding: '6px',
          }}
        >
          Use system
        </button>
      )}
    </div>
  );
}

Wire it up in your app root:

// src/App.tsx (or app/layout.tsx in Next.js App Router)
import { ThemeProvider } from './contexts/ThemeContext';
import { ThemeToggle } from './components/ThemeToggle';

export default function App({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider>
      <header>
        <ThemeToggle />
      </header>
      <main>{children}</main>
    </ThemeProvider>
  );
}

The Uncomfortable Truth About Dark Mode

Here's what the tutorials won't tell you, and what took me too long to learn properly:

Dark mode is not just an inverted color palette. And the moment you treat it that way, you've already shipped a subpar experience.

Three things that break in naive dark mode implementations:

1. Shadows

In light mode, shadows are dark on a light background — they create depth. In dark mode, if you keep the same shadow with the same opacity, it becomes nearly invisible because the background is already dark. You need to increase shadow opacity in dark mode, not decrease it. The CSS variable approach handles this automatically if you define --color-shadow separately for each theme — which the code above does.

2. Images and Media

A logo that's dark text on a transparent background — beautiful in light mode, invisible in dark mode. A photograph of a white product on a white background — completely loses its edges in dark mode. These don't fix themselves with CSS variables. They require actual design decisions: separate logo variants, CSS mix-blend-mode for certain images, or the picture element with different srcset per theme.

/* One pattern for images that need to be less harsh in dark mode */
[data-theme='dark'] img:not([data-theme-exempt]) {
  /* Slightly reduce brightness on photos that look blown-out in dark mode */
  filter: brightness(0.9);
}

/* Logo that needs to be inverted */
[data-theme='dark'] .logo-dark-variant {
  display: block;
}
[data-theme='light'] .logo-dark-variant,
:root .logo-dark-variant {
  display: none;
}

3. Third-Party Components

You've built perfect dark mode. Then you add a date picker, a chart library, a rich text editor. They bring their own CSS. They don't know about your data-theme attribute. They don't use your CSS variables.

This is where the real work is — and tutorials never talk about it because it's not clean and universal. Each library needs its own theming approach, and sometimes "dark mode support" for a library is a GitHub issue from 2019 with twelve thumbs-up and no resolution. Budget time for this. It will surprise you.

Real Objections

Objection 1: "Why not just use a CSS class instead of data-theme attribute?"

You can. [data-theme='dark'] and .dark-theme both work as CSS selectors. I prefer data-theme for a semantic reason: attributes are meant to carry metadata about an element's state. A class implies visual styling — which is a different concern. data-theme="dark" reads as "this document is in dark theme" which is accurate. .dark-theme reads as "apply dark theme styles to this element" which is also accurate but conflates what it is with how it looks.

In practice: it doesn't matter much. Pick one, be consistent, document it in your CSS architecture notes.

Objection 2: "The inline script in <head> is a render-blocking script. Isn't that bad for performance?"

Yes and no. Render-blocking scripts delay the first paint. But in this case, that's intentional — we want to block rendering until we know the correct theme, because the alternative is rendering the wrong theme and then correcting it (the flash). The script is tiny — about 200 bytes, runs in under a millisecond. The performance cost is negligible. The UX benefit is significant. This is one of the rare cases where render-blocking is the right call.

Objection 3: "What about users who have JavaScript disabled?"

The CSS @media (prefers-color-scheme: dark) query requires zero JavaScript. If the user has JavaScript disabled, the data-theme attribute never gets set, but the media query still applies the correct theme based on system preference. The only thing that doesn't work without JavaScript is the user's explicit override being remembered across sessions — which requires localStorage. Graceful degradation is built in.

📚 Nice to read more about dark mode

✨ 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 vs React: When Should You Use Each?

Bishoy Bishai — Mon, 06 Apr 2026 11:34:33 +0000

Next.js vs. React: Stop Asking "Which Is Better?" Ask This Instead.

The question isn't about features. It's about who renders your app first — and why that changes everything.

Let me tell you about a mistake I've watched teams make more times than I can count.

They're starting a new project. Excitement is high. The tech discussion begins. Someone says "should we use React or Next.js?" Someone else opens a comparison article. The article has a bullet list of features. The team picks based on the longest list of features that match their current requirements.

Six months later, the product has grown. Requirements have shifted. And suddenly they're either:

A) Fighting Next.js's server/client boundaries because they built a deeply stateful, real-time dashboard that didn't need SSR at all — and now every new developer onboarding asks "wait, why is this a Server Component again?"

Or B) Trying to bolt SEO and performance onto a bare React SPA that was always meant to be public-facing, discovering that client-side rendering and Googlebot have a complicated relationship.

Both of these are expensive mistakes. Not because the technology is bad — React and Next.js are both excellent. But because the decision was made for the wrong reasons.

I've been building React applications since 2017. And the question I get asked most consistently by mid-level developers is: "When do I use Next.js and when do I not?"

The tutorials answer this with feature lists. I'm going to answer it with the question that actually matters.

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

Apply the one diagnostic question that cuts through every "React vs. Next.js" debate in under two minutes
Understand why the rendering model difference matters — not just that it exists
Recognize the two most expensive architectural mistakes teams make, and when you're about to make them
Walk away with a decision framework you can use on your next project kickoff, without needing to re-read a comparison article

This is Pillar 4 content — Tactical Analysis. Not a tutorial. Not a beginner guide. This is the thinking you need for architectural decisions, written for developers who've already built things and broken them.

The One Question That Settles It

Before we touch a single feature comparison, I want to give you the diagnostic tool that makes this decision fast and clear. Every time.

"Who is the first person to execute your code — the server or the browser?"

That's it. That's the question.

I know it sounds too simple. Stay with me.

When the browser executes your code first, you're in client-side rendering territory. The user receives an HTML shell — basically empty — and JavaScript that, once downloaded and parsed, builds the UI in the browser. React SPA. This is Vite + React. This is Create React App. The browser does the work.

When the server executes your code first, HTML with actual content is generated before anything hits the browser. The user receives a fully-formed page. The browser can display it before a single line of JavaScript runs. This is Next.js's default behavior — and it's not just an optimization, it's a fundamentally different architecture.

Every consequence of choosing one over the other flows from this distinction. Not from feature lists. From this.

Let me show you what I mean in concrete terms, because the abstraction matters less than what actually happens in practice.

What "Client Renders First" Means in Production

When you build a standard React SPA, here's the sequence of events every time a user opens your app:

Browser requests the page from your server
Server responds with a nearly empty HTML file — <div id="root"></div> and a script tag
Browser downloads your JavaScript bundle (could be 200KB, could be 2MB, depends on your dependencies)
Browser parses and executes the JavaScript
React initializes, renders your component tree
Your components call their useEffect hooks
API calls go out to fetch data
Data comes back
Components re-render with actual content
The user finally sees something meaningful

Steps 3 through 10 all happen in the user's browser. On a fast laptop in Berlin with fiber internet, this feels instant. On a mid-range Android phone in Cairo on a 4G connection that drops to 3G when the elevator doors close — this is a blank screen for 3 to 5 seconds. Sometimes longer.

And for Googlebot? Googlebot doesn't execute JavaScript the way a browser does. It's gotten better — Google now processes JavaScript — but it's slower, it's not guaranteed, and it puts your SEO at the mercy of a crawler's JavaScript budget. For internal tools where nobody cares about Google, this is fine. For a product where organic search is a revenue channel, this is a real problem that doesn't show up in development and shows up painfully in production.

// The standard React SPA data fetch
// What's actually happening: the user sees NOTHING until this whole sequence completes
import React, { useState, useEffect } from 'react';

function ProductListing() {
  const [products, setProducts] = useState<Product[]>([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    // Step 6-8 in the sequence above.
    // This runs AFTER the JS bundle downloaded and executed.
    // AFTER React initialized.
    // The user has been looking at a blank div (or a spinner) until this moment.
    fetch('/api/products')
      .then(res => res.json())
      .then(data => {
        setProducts(data);
        setLoading(false);
      });
  }, []);

  // The user sees this first: just a spinner.
  // No content. No products. Nothing for the search crawler to index.
  if (loading) return <div>Loading...</div>;

  return (
    <ul>
      {products.map(product => (
        <li key={product.id}>{product.name} — €{product.price}</li>
      ))}
    </ul>
  );
}

This works perfectly well for an internal dashboard where users are authenticated, the audience is known, and nobody is Googling their way to your CRM. But ship this as a public product catalog and you've built a performance and SEO problem that will require a framework migration to fully fix.

What "Server Renders First" Changes

Now the same scenario in Next.js with Server Components (App Router):

// app/products/page.tsx
// This is a React Server Component — it runs on the server, not in the browser.
// The user receives actual HTML with products already inside it.
// No loading state. No useEffect. No spinner for the initial load.

interface Product {
  id: string;
  name: string;
  price: number;
}

// Notice: no 'use client' directive. This runs on the server.
// Notice: no useEffect, no useState, no loading state.
// The data is fetched before the HTML is generated.
async function ProductsPage() {
  // This fetch runs on the server during the request.
  // It never runs in the browser.
  // The database (or API) response is baked into the HTML before it leaves the server.
  const response = await fetch('https://api.yourstore.com/products', {
    // Next.js extends fetch with caching control.
    // revalidate: 3600 means "cache this for an hour, then refresh"
    // This is ISR — Incremental Static Regeneration.
    // The user gets static speed WITH dynamic data. Chef's kiss.
    next: { revalidate: 3600 }
  });
  const products: Product[] = await response.json();

  // By the time this JSX reaches the browser, it's already HTML.
  // The browser renders it immediately — no JavaScript needed for the initial view.
  return (
    <ul>
      {products.map(product => (
        <li key={product.id}>{product.name} — €{product.price}</li>
      ))}
    </ul>
  );
}

export default ProductsPage;

Walk through what happens now from the user's perspective:

Browser requests the page
Server fetches data from the API
Server renders the React component tree to HTML — with products already in it
Browser receives HTML with actual content
User sees the product list immediately
JavaScript loads in the background for interactivity (adding to cart, filters, etc.)

The user sees content on step 5. In the SPA version, content appears on step 10. That gap — those missing steps — is what Lighthouse scores measure. That gap is what Googlebot indexes. That gap is what users feel on slow connections.

The Rendering Model Spectrum — This Is Not Binary

Here's where most comparison articles fail you. They present this as a binary choice: SPA (React) vs. SSR (Next.js). It's not. Next.js gives you a spectrum of rendering strategies that you can apply per page, per component, even per fetch call.

Understanding this spectrum is what separates developers who use Next.js correctly from developers who fight it constantly.

** The four strategies:**

Strategy 1: Static Site Generation (SSG)

The page is rendered at build time. HTML is generated once, stored, and served from a CDN. Zero server computation per request. Zero database calls per visitor.

// app/blog/[slug]/page.tsx
// generateStaticParams tells Next.js: "build HTML for all of these at compile time"
// Result: blazing fast, CDN-served pages with zero per-request overhead

export async function generateStaticParams() {
  const posts = await getAllBlogPosts(); // Runs once at build time
  return posts.map(post => ({ slug: post.slug }));
}

async function BlogPost({ params }: { params: { slug: string } }) {
  // This also runs at build time, not per request.
  const post = await getBlogPost(params.slug);
  return <article>{post.content}</article>;
}

Use this when: content doesn't change per user and doesn't change frequently. Blog posts. Marketing pages. Documentation.

Strategy 2: Incremental Static Regeneration (ISR)

Static generation, but with a revalidation window. The page is served statically (CDN speed) and regenerated in the background when the cache expires.

// This product page is generated statically but refreshes every hour.
// Users get static speed. Content stays reasonably fresh.
// No server computation per request — unless the cache is stale.
async function ProductPage({ params }: { params: { id: string } }) {
  const product = await fetch(`/api/products/${params.id}`, {
    next: { revalidate: 3600 } // Regenerate at most once per hour
  }).then(r => r.json());

  return <ProductDetails product={product} />;
}

Use this when: content changes occasionally but not per-user. Product catalogs. News articles. Pricing pages.

Strategy 3: Server-Side Rendering (SSR)

Generated fresh on every request. Full server computation per visit.

// This page is different for every logged-in user.
// It can't be cached — the data is user-specific.
// SSR is the right call here.
import { cookies } from 'next/headers';

async function DashboardPage() {
  const cookieStore = cookies();
  const sessionToken = cookieStore.get('session')?.value;

  // Fetch user-specific data on the server.
  // Sensitive. Can't be cached. Must be fresh.
  const userData = await fetchUserDashboard(sessionToken);

  return <Dashboard data={userData} />;
}

Use this when: content is user-specific, real-time, or can't be cached. User dashboards. Account pages. Personalized feeds.

Strategy 4: Client-Side Rendering (CSR) — still valid inside Next.js

Some parts of your app are highly interactive and genuinely belong in the browser.

// 'use client' tells Next.js: this component renders in the browser
// Use for: real-time interactions, browser APIs, complex local state
'use client';

import { useState } from 'react';

function AddToCartButton({ productId }: { productId: string }) {
  const [isAdding, setIsAdding] = useState(false);
  const [added, setAdded] = useState(false);

  const handleClick = async () => {
    setIsAdding(true);
    await addToCart(productId);
    setIsAdding(false);
    setAdded(true);
  };

  return (
    <button onClick={handleClick} disabled={isAdding}>
      {added ? '✓ Added to Cart' : isAdding ? 'Adding...' : 'Add to Cart'}
    </button>
  );
}

A real Next.js application uses all four of these strategies simultaneously. The product listing page is ISR. The product detail is ISR with a shorter window. The cart is CSR. The checkout is SSR (user-specific, must be fresh). The blog is SSG.

This is not complexity for its own sake. This is precision — matching the rendering strategy to the actual data requirements of each part of your application.

The Two Expensive Mistakes

I've seen both of these destroy project timelines. Not hypothetically — in real codebases.

Expensive Mistake #1 — Reaching for Next.js when you need a React SPA

This one is subtler than it looks.

You're building an internal analytics dashboard. Real-time charts. Complex filtering. Heavy client-side state. Users authenticate first — nobody is landing on these pages from Google. SEO is irrelevant. The data updates every 30 seconds via WebSocket.

Someone on the team suggests Next.js because "it's the standard now."

Six months in:

Every new component requires the 'use client' decision
The WebSocket connection logic is fighting the Server Component model
Real-time state is awkward to manage when half your tree is server-rendered
Developers keep hitting hydration mismatches that take hours to debug
Onboarding new developers requires explaining the client/server boundary before they can write their first component

Was Next.js wrong? Technically no. Was it the right tool for this job? Absolutely not. A Vite + React SPA with React Query for data fetching would have been faster to build, easier to reason about, and had zero hydration issues. The complexity of Next.js added zero value to a private, highly interactive, SEO-irrelevant application.

The diagnostic: Before reaching for Next.js, ask: "Does the server rendering this page first give ANY benefit to my users?" For authenticated-only dashboards where the content is entirely dynamic — the answer is usually no.

Expensive Mistake #2 — Building a public product with bare React

This one is more painful because you don't feel it immediately. You feel it at month four when marketing starts asking why your Core Web Vitals are tanking. You feel it when the product manager notices you're not appearing in Google search for your own product name. You feel it when a user on a slow connection tweets that your app feels broken.

I've watched teams spend three months building a public-facing e-commerce product in bare React and then spend another two months migrating to Next.js because the performance gap was affecting conversion rates. That's five months on what should have been three.

// The telltale sign you need Next.js and you're in a React SPA:
// You start adding libraries to solve problems Next.js solves natively.

// react-helmet for SEO meta tags (Next.js has this built-in)
import { Helmet } from 'react-helmet-async';

// You're pre-rendering with react-snap or similar tools
// You're adding react-query with complex cache configuration
// You're writing custom webpack config for code splitting

// When you're recreating the framework, it's time to use the framework.

The diagnostic: if your app is public-facing, content-heavy, or depends on search engine visibility — Next.js should be your starting point, not a migration destination.

The App Router Reality Check

Okay, I want to spend time on something the comparison articles either gloss over or get wrong: Next.js App Router is a paradigm shift, not just an API change.

The Pages Router (the "old" Next.js with getServerSideProps and getStaticProps) was familiar — it felt like React with some special export functions. The App Router with React Server Components is a genuinely different mental model.

What Most Developers Think: Server Components are just components that fetch data on the server. Basically getServerSideProps but cleaner.

What's Actually True in Production: Server Components don't run in the browser at all. They have no access to browser APIs. They can't use useState or useEffect. They can't have event handlers. They're not hydrated — the browser never receives their JavaScript. They exist only as HTML output from the server.

Why the Gap Exists: Because the tutorials show you a Server Component that fetches data and renders it, and it looks almost exactly like a Client Component. The difference isn't visible until you try to add interactivity and get an error, or until you try to access window and your server crashes.

// ⚠️ This will fail — and the error message isn't always clear about why

// app/some-page/page.tsx — this is a Server Component by default
// No 'use client' directive

import { useState } from 'react'; // ❌ ERROR: useState in a Server Component

async function SomePage() {
  const [count, setCount] = useState(0); // ❌ This doesn't exist on the server

  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
  // ❌ Event handlers don't work in Server Components either
}

// ✅ The correct pattern: Server Component + Client Component composition

// app/some-page/page.tsx — Server Component
// Fetches data on the server, passes it down
async function SomePage() {
  const initialData = await fetchInitialData();

  // InteractiveCounter is a Client Component — it gets hydrated in the browser
  // SomePage itself stays server-only — its JavaScript never ships to the browser
  return (
    <div>
      <h1>Static heading — rendered in HTML, no JS needed</h1>
      <InteractiveCounter initialValue={initialData.count} />
    </div>
  );
}

// components/InteractiveCounter.tsx
'use client'; // ← This component runs in the browser

import { useState } from 'react';

function InteractiveCounter({ initialValue }: { initialValue: number }) {
  const [count, setCount] = useState(initialValue);

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

The mental model shift: in App Router, think of your component tree as two layers. The server layer handles data fetching and generates HTML. The client layer handles interactivity and browser APIs. The server layer wraps the client layer — not the other way around.

Once this clicks, App Router becomes powerful and intuitive. Before it clicks, it's a source of confusing errors and "why doesn't this work" moments that make teams question whether they should have stayed on Pages Router.

My honest advice: if your team is new to Next.js AND new to App Router — consider starting with Pages Router for your first project. It's still fully supported. It has a gentler learning curve. And it teaches you the "why" of server rendering in a way that makes App Router make more sense when you get to it.

A Decision Framework You Can Use Tomorrow

Stop asking "which is better?" Start asking these questions at your project kickoff:

Question 1: Who are your users and how do they arrive?

If users arrive via search engines, social shares, or direct links to content — the server needs to render that content before it reaches them. Next.js.

If users arrive via login and spend their time inside an authenticated application — the initial render can happen in the browser. React SPA is fine.

Question 2: How dynamic is your content, and for whom?

Content that's the same for everyone and changes rarely → Static generation. Next.js with SSG or ISR.

Content that's the same for everyone but changes frequently → Server rendering with short cache windows. Next.js with ISR.

Content that's different per user → Either SSR (in Next.js) or CSR (React SPA or 'use client' in Next.js).

Question 3: What is your team's relationship with the server/client boundary?

Teams with strong full-stack experience tend to find Next.js's model natural. Teams that have only done client-side React may find the App Router's server/client boundary genuinely confusing at first.

Factor in the learning curve. A slightly less optimal tool your team understands deeply ships faster than the perfect tool your team fights constantly.

Question 4: Will this application grow to need both?

Here's the thing about React SPAs: you can always add Next.js later. The migration is painful, but it's a known path. Many successful products started as React SPAs and migrated when SEO and performance became priorities.

But the reverse — migrating from Next.js to a React SPA because you don't need SSR — is almost never worth doing. You don't lose anything by using Next.js for an app that doesn't fully use SSR. The overhead is minimal.

When in doubt: if there's any chance this product will become public-facing, default to Next.js. The cost of migrating TO it later is higher than the learning curve of starting with it.

The Uncomfortable Truth

Here's what I want to say that nobody is saying loudly enough:

Next.js won. For production React applications, Next.js is the default. The question is no longer "React or Next.js?" — it's "which Next.js rendering strategy, and which parts of my app need client-side rendering?"

React without a framework is still absolutely valid — for SPAs, for dashboards, for internal tools, for learning. But when someone asks me "should I learn Next.js or just React?" my honest answer is: learn React first (you'll be writing React components regardless), then learn Next.js, because that's what you'll use in most production jobs.

The fact that we're still debating "React vs. Next.js" as equals in 2024 is a symptom of an industry that moves fast but talks slowly. The ecosystem has largely settled. Next.js ships with Vercel, with the React team's blessing, with RSC as the direction React itself is heading. Fighting this is like arguing about whether you should use TypeScript in 2024 — technically optional, practically the default.

That said — understand WHY Next.js makes sense before you default to it. Because developers who use Next.js without understanding the rendering model are the same developers who slap 'use client' on everything to make errors go away, effectively building a React SPA inside a Next.js wrapper. They've paid the complexity cost with zero benefit.

Know the model. Then use the tool.

Real Objections

Objection 1: "Next.js is overkill for a simple project. Vite + React is faster to set up."

Completely valid. If you're building a small side project, a prototype, or a learning exercise — the cognitive overhead of Next.js routing conventions and rendering strategies adds friction you don't need. Vite + React is fast, simple, and excellent for things that don't need SSR. The calculus changes the moment "going to production with real users" enters the picture.

Objection 2: "React Query / TanStack Query solves the same problems as SSR without changing your framework."

Partially true. React Query dramatically improves client-side data fetching — caching, background refetching, loading states. But it doesn't change when the browser receives content. The user still waits for JavaScript to load before seeing anything meaningful. React Query makes the SPA experience better. It doesn't change the fundamental rendering model. If initial load performance and SEO are requirements, React Query is not a substitute for SSR.

Objection 3: "Server Components add too much complexity. I'll just use Pages Router with getServerSideProps."

Legitimate choice and not a wrong one. Pages Router is stable, well-understood, and still fully supported. If your team is productive with it, there's no urgency to migrate to App Router. The main things you lose are automatic streaming, more granular caching control, and the performance benefits of shipping less JavaScript to the client. For many applications, those tradeoffs favor staying on Pages Router until App Router stabilizes further in your team's comfort zone.

That said — new projects should probably start on App Router. The ecosystem is moving there. The documentation is better now. And the performance benefits at scale are real.

📚 Nice to see too

📄 Article: "Rendering Patterns" by Addy Osmani & Lydia Hallie on patterns.dev
- Why it made my brain itch: The most comprehensive visual breakdown of every rendering strategy — SPA, SSR, SSG, ISR, Streaming — with performance implications for each. Bookmark this one. You'll come back to it every time someone asks you to justify an architecture choice.
📄 Article: "Understanding React Server Components" on the Next.js Blog
- Why it made my brain itch: Coming directly from the team building it, this explains the why behind RSC in a way that makes the constraints feel intentional rather than arbitrary. Read this before your first App Router project.
🎥 Video: "React Server Components from Scratch" by Theo Browne (t3.gg) on YouTube
- Skip to minute 6:30: Where he builds RSC from first principles. Watching it get built from scratch is the fastest way to truly understand what the boundary between server and client means.
"The best tool is the one that ships."
— Everyone who's survived a framework debate

✨ 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

Your React Component Isn't Too Big. It Has Too Many Reasons to Change.

Bishoy Bishai — Thu, 02 Apr 2026 11:31:47 +0000

And yes — there's a difference. A massive one.

I want to tell you something that took me an embarrassingly long time to learn.

In 2017, I shipped a feature I was proud of. A live order tracking component at Elemnus — real-time updates, smooth UI, clean-looking code by my standards at the time. My team lead reviewed it, nodded slowly, and said: "It works. But when the next requirement comes, we're going to regret this."

I thought he was being dramatic.

Three weeks later, a new requirement landed: "Add a cancellation reason modal when the user cancels an order." Simple, right? I opened the component. It was 340 lines long. It was fetching data, managing five different UI states, animating transitions, and handling form submissions — all in one place, all tangled together like earphones at the bottom of a backpack.

I spent two days on a change that should have taken two hours. I introduced three bugs fixing one. We shipped on Friday. Something broke on Saturday.

My team lead didn't say "I told you so." He just opened the component and said: "How many reasons does this thing have to change?"

I counted. Seven. At least seven different reasons this single component would need to be touched if anything in the system changed.

That question — how many reasons does this have to change? — is the one I want to answer with you today. Because if you've ever felt the specific dread of opening a component you wrote six months ago, if you've ever thought "I'll just add this one thing here" and immediately regretted it — this article is for Bishoy at 3 AM. The one staring at a 400-line component wondering where to even start.

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

Diagnose exactly why a component is hard to change (not just that it's "too big")
Apply the Change Isolation Test to any component in under 60 seconds
Refactor a bloated component into a structure that lets you sleep at night
Know when to memoize and when memoization is costing you more than it saves
Walk away with a mental model that makes every future component decision faster

This is not a "here's the before, here's the after" tutorial. Those exist. They're fine. This is the thinking behind the refactor — the stuff that actually stops you from recreating the same mess six months later in a different component with a different name.

The Uncomfortable Truth Nobody Says Out Loud

Here's what the React documentation won't tell you, what most tutorials gloss over, and what I got wrong for longer than I'd like to admit:

Single Responsibility Principle is not about size. It's about reasons to change.

I know. You've heard "keep your components small." You've nodded. You've maybe even split a big component into three smaller ones and felt good about yourself. But here's the trap: you can split a component into five pieces and still violate Single Responsibility completely if those pieces are coupled to the same reasons for change.

Let me be specific. Imagine you have a UserProfile component. You decide to be responsible and split it into UserAvatar, UserBio, and UserActions. Excellent. Three components now. But all three of them directly call the same API endpoint, and all three of them have their own loading state. Now you have three components, all of which need to change the moment the API contract changes. You've split the file. You haven't split the responsibilities.

This distinction is the whole game. Everything else is noise.

The question to ask about any component, large or small, is this: "If X changes, does this component need to change too?" Ask that for every X you can think of — API shape, UI design, business logic, error handling strategy, animation library. Count the yeses. That number is your responsibility score. The goal is not zero — one is fine, even two can be fine in context. But when you hit five, six, seven? You've built a component that is afraid of the future. And it should be. Because every future change is coming for it.

What "Doing Too Much" Actually Looks Like in Production

Let's build the actual broken thing first. Not Hello world. A real-world UserProfile component the way it grows organically in a real codebase under real deadline pressure.

// 🚫 The component that "just grew this way"
// Responsibility Score: 7 (fetching, loading state, error state, 
// display logic, edit mode toggle, form state, save logic)
// Time to understand cold: ~25 minutes
// Time to safely add a feature: "let me just try this and see"

import React, { useState, useEffect } from 'react';

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

// These would normally live in an API layer — but they ended up here
// because "it was faster at the time"
async function fetchUser(userId: string): Promise<User> {
  const response = await fetch(`/api/users/${userId}`);
  if (!response.ok) throw new Error('Failed to fetch');
  return response.json();
}

async function updateUser(userId: string, data: Partial<User>): Promise<User> {
  const response = await fetch(`/api/users/${userId}`, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data),
  });
  if (!response.ok) throw new Error('Failed to update');
  return response.json();
}

const UserProfile: React.FC<{ userId: string }> = ({ userId }) => {
  // Responsibility 1: Fetched data
  const [user, setUser] = useState<User | null>(null);
  // Responsibility 2: Loading state (shared between fetch AND save — 
  // which means the spinner shows when you save, which blocks the form,
  // which you'll only notice in QA if you're lucky)
  const [loading, setLoading] = useState(true);
  // Responsibility 3: Error state (also shared — same problem)
  const [error, setError] = useState<string | null>(null);
  // Responsibility 4: Edit mode toggle
  const [isEditing, setIsEditing] = useState(false);
  // Responsibility 5 & 6: Form state for name and bio
  // (These will get out of sync with `user` in subtle ways)
  const [editName, setEditName] = useState('');
  const [editBio, setEditBio] = useState('');

  useEffect(() => {
    const loadUser = async () => {
      setLoading(true);
      setError(null);
      try {
        const userData = await fetchUser(userId);
        setUser(userData);
        // Syncing form state with fetched data — a sign that
        // these should not live in the same place
        setEditName(userData.name);
        setEditBio(userData.bio);
      } catch (err) {
        setError('Failed to fetch user.');
      } finally {
        setLoading(false);
      }
    };
    loadUser();
  }, [userId]);

  // Responsibility 7: Save logic
  const handleSave = async () => {
    if (!user) return;
    setLoading(true); // ← This disables the form AND shows the spinner.
                      // If you only wanted to show a spinner on the save button,
                      // you'd need ANOTHER state variable. This is how state multiplies.
    setError(null);
    try {
      const updatedUser = await updateUser(user.id, { name: editName, bio: editBio });
      setUser(updatedUser);
      setIsEditing(false);
    } catch (err) {
      setError('Failed to update user.');
    } finally {
      setLoading(false);
    }
  };

  if (loading) return <div>Loading profile...</div>;
  if (error) return <div style={{ color: 'red' }}>Error: {error}</div>;
  if (!user) return null;

  return (
    <div>
      <h2>{user.name}'s Profile</h2>
      {isEditing ? (
        <div>
          <label>
            Name:
            <input
              type="text"
              value={editName}
              // Every keystroke re-renders the ENTIRE UserProfile component.
              // Including the header. Including any siblings. 
              // This is invisible in development. Painful at scale.
              onChange={(e) => setEditName(e.target.value)}
            />
          </label>
          <label>
            Bio:
            <textarea
              value={editBio}
              onChange={(e) => setEditBio(e.target.value)}
            />
          </label>
          <button onClick={handleSave} disabled={loading}>Save</button>
          <button onClick={() => setIsEditing(false)} disabled={loading}>Cancel</button>
        </div>
      ) : (
        <div>
          <p><strong>Email:</strong> {user.email}</p>
          <p><strong>Bio:</strong> {user.bio}</p>
          <button onClick={() => setIsEditing(true)}>Edit Profile</button>
        </div>
      )}
    </div>
  );
};

Now let me apply the Change Isolation Test. I'll go through every realistic change request and ask: does this component need to change?

The API endpoint changes → Yes. The fetch functions are defined inside the file.
The loading spinner design changes → Yes. Loading state is here.
We want different loading behavior for fetch vs. save → Yes. And it's painful — you need to add a whole new state variable.
The display design changes (new layout, colors, added avatar) → Yes.
The form validation rules change → Yes.
We add a new editable field (phone number) → Yes. And it touches every section of this component.
The error handling strategy changes (toast instead of inline error) → Yes.

Seven reasons. Seven. Every one of those is a future regression waiting to happen. Every one of those is a code review comment waiting to become a heated discussion. Every one of those is a bug that shows up in production on a Friday.

Open your React DevTools Profiler right now and record a session while typing in the edit form. You'll see UserProfile lighting up on every single keystroke. The entire component tree underneath it re-renders. For a name input. Because the form state, the display state, and the data state are all the same state in the same component.

The Refactor: Change Isolation, Not Just Code Splitting

here's the approach. We're not just moving code around. We're identifying each reason to change and giving it its own home.

Reason to change #1 & #7: Data fetching and saving → Custom Hook

The hook's only job is to know about the user. It fetches. It saves. It knows nothing about forms, nothing about edit mode, nothing about what the UI looks like. If the API contract changes tomorrow, you touch exactly one file.

// useUser.ts
// Responsibility: ONE — managing the user data lifecycle
// Reason to change: ONLY when the data fetching or update logic changes
// Time to understand cold: ~5 minutes

import { useState, useEffect, useCallback } from 'react';

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

async function fetchUser(userId: string): Promise<User> {
  const response = await fetch(`/api/users/${userId}`);
  if (!response.ok) throw new Error('Network response was not ok');
  return response.json();
}

async function saveUserToApi(userId: string, data: Partial<User>): Promise<User> {
  const response = await fetch(`/api/users/${userId}`, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data),
  });
  if (!response.ok) throw new Error('Failed to save');
  return response.json();
}

interface UseUserReturn {
  user: User | null;
  isFetching: boolean;     // ← Separate loading states. Intentional.
  isSaving: boolean;       // ← Now the form can show a save spinner
  fetchError: string | null; // without blocking the entire UI.
  saveError: string | null;
  saveUser: (data: Partial<User>) => Promise<User | undefined>;
  refetch: () => void;
}

export function useUser(userId: string): UseUserReturn {
  const [user, setUser] = useState<User | null>(null);
  // Notice: two separate loading states.
  // This solves the "spinner blocks the form during save" bug
  // that you'd only catch in QA — or production.
  const [isFetching, setIsFetching] = useState(true);
  const [isSaving, setIsSaving] = useState(false);
  const [fetchError, setFetchError] = useState<string | null>(null);
  const [saveError, setSaveError] = useState<string | null>(null);

  const loadUser = useCallback(async () => {
    setIsFetching(true);
    setFetchError(null);
    try {
      const userData = await fetchUser(userId);
      setUser(userData);
    } catch (err) {
      setFetchError('Could not load profile. Please try again.');
    } finally {
      setIsFetching(false);
    }
  }, [userId]);

  // saveUser is separate from loadUser.
  // It has its own loading state, its own error state.
  // If the product team asks "can we show a spinner only on the save button?"
  // the answer is: already done.
  const saveUser = useCallback(async (data: Partial<User>) => {
    if (!user) return;
    setIsSaving(true);
    setSaveError(null);
    try {
      const updatedUser = await saveUserToApi(user.id, data);
      setUser(updatedUser); // Update local state on success
      return updatedUser;
    } catch (err) {
      setSaveError('Could not save changes. Please try again.');
      throw err; // Re-throw so the calling component can react (e.g., keep form open)
    } finally {
      setIsSaving(false);
    }
  }, [user]);

  useEffect(() => {
    loadUser();
  }, [loadUser]);

  return {
    user,
    isFetching,
    isSaving,
    fetchError,
    saveError,
    saveUser,
    refetch: loadUser,
  };
}

Reason to change #5 & #6: Form state and validation → UserEditForm

This component knows nothing about the API. It knows nothing about the user data structure beyond what it receives as props. Its only job: manage the inputs, validate them locally, and call onSave when the user is done.

// UserEditForm.tsx
// Responsibility: ONE — managing the edit form experience
// Reason to change: ONLY when form fields, validation, or form UX changes
// Note: Every keystroke now re-renders ONLY this component.
// UserDisplay, UserProfileContainer — completely unaffected.

import React, { useState } from 'react';

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

interface UserEditFormProps {
  // We pass the initial values explicitly so the form owns its state fully.
  // The form doesn't know what the "current user" is — it just knows
  // what it started with and what the user wants to change it to.
  initialName: string;
  initialBio: string;
  // isSaving comes from the hook via the container.
  // The form doesn't know WHY it's saving — just that it is.
  isSaving: boolean;
  onSave: (name: string, bio: string) => Promise<void>;
  onCancel: () => void;
}

export const UserEditForm: React.FC<UserEditFormProps> = React.memo(({
  initialName,
  initialBio,
  isSaving,
  onSave,
  onCancel,
}) => {
  const [name, setName] = useState(initialName);
  const [bio, setBio] = useState(initialBio);
  // Local form error — separate from the API save error.
  // "Name is required" is a form concern. "Server rejected the request" is an API concern.
  // They live in different places.
  const [validationError, setValidationError] = useState<string | null>(null);

  const handleSubmit = async () => {
    // Local validation before hitting the API.
    // If validation rules change, this is the only place you touch.
    if (!name.trim()) {
      setValidationError('Name cannot be empty.');
      return;
    }
    if (bio.length > 500) {
      setValidationError('Bio must be 500 characters or less.');
      return;
    }
    setValidationError(null);
    await onSave(name.trim(), bio);
  };

  return (
    <div>
      {validationError && (
        // This is a local validation error — shows inline immediately.
        // The save error from the API is shown in the container.
        <p style={{ color: 'orange' }}>{validationError}</p>
      )}
      <label>
        Name:
        <input
          type="text"
          value={name}
          // This onChange now only re-renders UserEditForm.
          // Nothing else in the tree is affected.
          onChange={(e) => setName(e.target.value)}
          disabled={isSaving}
        />
      </label>
      <label>
        Bio ({bio.length}/500):
        <textarea
          value={bio}
          onChange={(e) => setBio(e.target.value)}
          disabled={isSaving}
        />
      </label>
      <button onClick={handleSubmit} disabled={isSaving}>
        {isSaving ? 'Saving...' : 'Save Changes'}
      </button>
      <button onClick={onCancel} disabled={isSaving}>
        Cancel
      </button>
    </div>
  );
});

UserEditForm.displayName = 'UserEditForm';

Reason to change #4: Display logic → UserDisplay

Pure. Presentational. No state. No side effects. It receives data, it renders data. If the entire visual design of the profile changes, this is the only file you touch.

// UserDisplay.tsx
// Responsibility: ONE — rendering the user profile view
// Reason to change: ONLY when the display design or displayed fields change
// Testable with zero mocks. Just render and assert.

import React from 'react';

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

interface UserDisplayProps {
  user: User;
  onEditClick: () => void;
}

export const UserDisplay: React.FC<UserDisplayProps> = React.memo(({ user, onEditClick }) => (
  <div>
    {user.avatarUrl && (
      <img
        src={user.avatarUrl}
        alt={`${user.name}'s avatar`}
        style={{ width: 80, height: 80, borderRadius: '50%' }}
      />
    )}
    <p><strong>Name:</strong> {user.name}</p>
    <p><strong>Email:</strong> {user.email}</p>
    <p><strong>Bio:</strong> {user.bio}</p>
    <button onClick={onEditClick}>Edit Profile</button>
  </div>
));

UserDisplay.displayName = 'UserDisplay';

Reasons to change #2, #3, #4 (orchestration): The Container

The container is the conductor. It doesn't play any instrument. It just knows what everyone else is doing and coordinates between them.

// UserProfileContainer.tsx
// Responsibility: ONE — orchestrating the profile feature
// Reason to change: ONLY when the feature's flow or composition changes
// (e.g., "add a confirmation step before saving")

import React, { useState } from 'react';
import { useUser } from './useUser';
import { UserDisplay } from './UserDisplay';
import { UserEditForm } from './UserEditForm';

interface UserProfileContainerProps {
  userId: string;
}

export const UserProfileContainer: React.FC<UserProfileContainerProps> = ({ userId }) => {
  const {
    user,
    isFetching,
    isSaving,
    fetchError,
    saveError,
    saveUser,
  } = useUser(userId);

  const [isEditing, setIsEditing] = useState(false);

  const handleSave = async (name: string, bio: string) => {
    try {
      await saveUser({ name, bio });
      // Only close the form if save succeeded.
      // If it throws, the form stays open — user doesn't lose their work.
      setIsEditing(false);
    } catch {
      // The error is already in saveError from the hook.
      // We don't need to do anything here except NOT close the form.
    }
  };

  // Fetch loading state — full page spinner, reasonable here
  if (isFetching) return <div>Loading profile...</div>;
  if (fetchError) return <div style={{ color: 'red' }}>{fetchError}</div>;
  if (!user) return null;

  return (
    <div style={{ border: '1px solid #ccc', padding: '20px', borderRadius: '8px' }}>
      <h2>{user.name}'s Profile</h2>

      {/* API save error — shown at the container level, not buried in the form */}
      {saveError && (
        <div style={{ color: 'red', marginBottom: '12px' }}>
          {saveError}
        </div>
      )}

      {isEditing ? (
        <UserEditForm
          initialName={user.name}
          initialBio={user.bio}
          isSaving={isSaving}
          onSave={handleSave}
          onCancel={() => setIsEditing(false)}
        />
      ) : (
        <UserDisplay
          user={user}
          onEditClick={() => setIsEditing(true)}
        />
      )}
    </div>
  );
};

Now apply the Change Isolation Test again:

API endpoint changes → Touch useUser.ts only
Loading spinner design changes → Touch UserProfileContainer.tsx only (or create a LoadingSpinner component — one file)
We want a different spinner during save → Already handled. isSaving vs isFetching are separate.
Display design changes → Touch UserDisplay.tsx only
Form validation rules change → Touch UserEditForm.tsx only
Add a new editable field → Touch UserEditForm.tsx and useUser.ts only
Error handling strategy changes → Touch UserProfileContainer.tsx only

Seven changes. Seven files affected. But now each file is affected by exactly one of those changes, not all seven. That's not just cleaner code. That's confidence. That's the difference between shipping on Friday and sweating on Saturday.

The Performance Win You Didn't Know You Were Getting

Here's the thing tutorials always get backwards: they show you React.memo and useCallback as the solution to re-render problems. They're not. They're tools that become useful once you've fixed the architecture.

Before the refactor, every keystroke in the name input caused UserProfile to re-render. The entire component. Including the display section, including the header, including any sibling components that happened to be nearby. You could slap React.memo on the whole thing and it wouldn't help — because the state was inside the component, so React.memo has nothing to compare against.

After the refactor, every keystroke in the name input causes UserEditForm to re-render. Only UserEditForm. UserDisplay is sitting there completely unbothered. UserProfileContainer is unbothered. The rest of your page is unbothered.

You got the performance win for free. Not from memoization. From architecture.

Now, about memoization specifically — because this is where I've watched developers cargo-cult their way into slower apps:

What Most Developers Think: useCallback and React.memo prevent re-renders, so more of both = faster app.

What's Actually True in Production: useCallback preserves function reference identity across renders. Whether that prevents re-renders depends entirely on whether the receiving component is wrapped in React.memo. Without React.memo, useCallback adds memory overhead and dependency comparison on every render with zero benefit.

Why the Gap Exists: Because tutorials show the "happy path" where you add React.memo to the child AND useCallback to the parent AND it works. They don't show the case where you add useCallback to a function that's only used inside a useEffect — which is valid — or the case where you wrap a function in useCallback and pass it to a component that isn't memoized — which is just overhead with no upside.

// ⚠️ Common memoization mistake: paying the cost, getting nothing back

// Parent component
const Parent = () => {
  const handleClick = useCallback(() => {
    // some handler
  }, []); // ← useCallback here creates a stable reference

  // But if Child is NOT wrapped in React.memo...
  return <Child onClick={handleClick} />;
  // ...then the stable reference doesn't matter.
  // Child re-renders whenever Parent re-renders regardless.
  // You've paid for the dependency array comparison on every render
  // and received nothing in return.
};

// ✅ useCallback is justified when the child IS memoized:
const Child = React.memo(({ onClick }: { onClick: () => void }) => {
  // Now the stable reference matters.
  // React.memo can say "onClick reference didn't change — skip re-render."
  return <button onClick={onClick}>Click me</button>;
});

The rule: Profile first. Optimize second. Open React DevTools Profiler. Record a session while using the feature. Look for components that render more than once when you'd expect them to render zero times. Then reach for React.memo and useCallback. Not before.

I've seen codebases where every function was wrapped in useCallback "for performance." The actual profiler showed zero difference in render counts. What it did show was slightly longer render times — from the dependency array comparisons that were happening on every render for no reason.

The State Discipline Rule You'll Use Every Day

Before you add a new useState call, ask one question: "Can this be derived from state that already exists?"

Derived state is one of the most common sources of bugs in React applications. It's not dramatic — it doesn't throw errors. It just silently gets out of sync.

// 🚫 The bug factory
const ProfileStats = ({ user }: { user: User }) => {
  // These three are derived from user — but stored as separate state.
  // They'll be correct on mount. But what happens when user changes?
  // You have to remember to update all three. Every time. Forever.
  const [displayName, setDisplayName] = useState(user.name);
  const [isVerified, setIsVerified] = useState(user.email.endsWith('@company.com'));
  const [bioWordCount, setBioWordCount] = useState(user.bio.split(' ').length);

  // Later, when user updates...
  // Did you remember to update displayName?
  // Did you remember to update isVerified?
  // Did you remember to update bioWordCount?
  // This is how subtle data inconsistency bugs are born.

  return <div>{displayName} ({bioWordCount} words in bio)</div>;
};

// ✅ Derive it. Don't store it.
const ProfileStats = ({ user }: { user: User }) => {
  // These are computed on every render.
  // They are ALWAYS in sync with user. No exceptions. No bugs.
  // And because they're simple calculations, the performance cost is negligible.
  const displayName = user.name;
  const isVerified = user.email.endsWith('@company.com');
  const bioWordCount = user.bio.split(' ').length;

  return <div>{displayName} ({bioWordCount} words in bio)</div>;
};

The only time to reach for useMemo on derived values is when the computation is genuinely expensive — we're talking sorting a list of ten thousand items, running a heavy calculation, or building a complex data structure. For everything else, compute it inline. React is fast. Your render functions are fast. Trust the platform.

The Uncomfortable Truth: You Will Recreate This Problem

Here's what I want to tell you that nobody else will.

You can do this refactor perfectly today. Every responsibility in its own file, every hook clean, every component pure. And six months from now, after three sprints of feature requests and two rounds of "just put it here for now, we'll clean it up later" — you'll have a new component with seven reasons to change.

This is not a failure of discipline. This is gravity. Codebases accumulate complexity the way kitchen drawers accumulate miscellaneous objects. The question isn't "how do I prevent it forever?" It's "how do I recognize it early enough to fix it before it becomes a legacy nightmare?"

The Change Isolation Test. Run it on your components every time you're about to open one to add a feature. Not as a refactoring ceremony — just as a quick gut-check. "How many reasons does this component have to change?" If the number is more than two, and you're about to add another feature to it, stop. Spend twenty minutes extracting just the thing you're about to add into its own home. You don't have to refactor the whole thing. Just don't make it worse.

Real Objections, Real Answers

Objection 1: "This is over-engineering for a simple component. Not everything needs four files."

Completely valid — with a caveat. A truly simple component with one responsibility doesn't need to be split. A LoadingSpinner that takes a message prop and renders a spinner? That's one file, one responsibility, done. The rule applies when the component has multiple reasons to change, not as a blanket "always split into hooks and containers." Use the Change Isolation Test. If the number is one, you're fine. If it's growing, that's the signal.

Objection 2: "Prop drilling gets worse with this pattern. Now I'm passing isSaving through multiple layers."

Fair. And the answer depends on your scale. For a contained feature like UserProfile, passing isSaving one level down (from container to form) is absolutely fine — it's one prop, one level. When you're passing the same prop through five layers to reach a deeply nested component, that's when context or a state management solution earns its place. The pattern I've shown here doesn't create prop drilling — it creates clear data flow. Those are different problems.

Objection 3: "Custom hooks are just moving the problem. The hook is still doing multiple things."

If your hook is doing multiple things, yes — it's the same problem, different location. useUser as I've written it has one job: manage the lifecycle of user data (fetch and save). If your hook is also managing UI state, routing, and analytics events, then the hook needs the same treatment the component got. The principle doesn't change based on whether you're looking at a component or a hook.

That said — there ARE cases where a single hook managing fetch AND save makes sense because they're tightly coupled to the same data entity. The test is still "how many reasons does this have to change?" If the fetch strategy and save strategy will always change together, they belong together. If they could evolve independently, separate them.

Resuources

📄 Article: "Making Sense of React Hooks" by Dan Abramov
- Why it made my brain itch: He explains the why behind hooks in a way that makes the design feel inevitable rather than arbitrary. Read it after you feel comfortable with hooks, not before.
📄 Article: "Application State Management with React" by Kent C. Dodds
- Why it made my brain itch: He makes the case for colocation — keeping state as close to where it's used as possible. Changed how I think about where things live.
🎥 Video: "React Performance" by Jack Herrington on YouTube
- Skip to minute 8:00: Where he shows an actual real-world app getting slower from too much memoization. Worth every second.
💬 Quote I'm stealing:

"Make it work, make it right, make it fast."
— Kent Beck

Why this stays with me: In that order. Most re-render problems I've seen were caused by trying to make it fast before making it right.

Here's what I'm still working through:

Where does the line between "this hook is doing too much" and "this hook is appropriately managing a domain" live in practice? In theory, useUser should only know about user data. But in a real application, saving a user profile might invalidate a cache, trigger an analytics event, update a global notification — at what point does the hook need to hand those concerns off, and to whom?

I've gone back and forth on this. My current position: the hook hands back the raw result and lets the caller decide what to do with it. Side effects like analytics belong in the container. Cache invalidation belongs in the API layer or a library like React Query that handles it natively.

But I've been wrong about this before. And I'll probably refine it again.

What's your current pattern for managing side effects that cut across concerns? I'm genuinely curious — drop it in the comments.

Code is not a sculpture. It's a public square. Other people have to walk through it after you.

The UserProfile component I described at the start of this article — the one with seven reasons to change — it wasn't written by a bad developer. It was written by me, under deadline pressure, making what felt like a reasonable call at the time. "It's just one component. I'll clean it up later."

Later never came. The feature shipped. The component grew. The Saturday bug happened.

The Change Isolation Test is the "clean it up later" that you do now, in twenty minutes, before the component becomes someone else's problem. Or your future self's problem. Which is worse.

Simple? Yes. Easy? Absolutely not. 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

React 19 Is Already Here. You're Just Not Ready for It.

Bishoy Bishai — Wed, 01 Apr 2026 11:36:44 +0000

React 19 Is Already Here. You're Just Not Ready for It.

And that's not an insult. It's the most honest thing I can say.

React 19 dropped stable in December 2024. The React Compiler — what you might know as "React Forget" — hit beta the same month. React Server Components have been in production via Next.js since 2023. The feature set is real. The ecosystem is catching up. The question isn't "is React 19 ready?" anymore.

The question is: are you ready to understand what it actually means?

Because here's the uncomfortable truth most articles won't tell you: React 19 doesn't forgive ignorance. If you don't understand why re-renders happen, the Compiler won't save you. If you don't understand the server-client boundary, RSCs will break your app in ways that take hours to debug. This isn't React asking you to re-learn everything — it's React asking you to finally understand the fundamentals you skipped.

This article is for the senior who's been doing React for 5 years but never actually understood what useMemo costs. It's for Bishoy at 23, who would have wasted two weeks on this without someone honest to explain it.

After reading this, you will be able to:

Explain the React Compiler to your Tech Lead without hand-waving
Know exactly when to use Server Components and when they'll blow up in your face
Debug the most common RSC mistakes before they hit production
Make a confident, specific decision about whether to migrate today or wait

Let's get into it.

THE SETUP — Why React 19, Why Now

React has always had one fundamental problem. It's not a bug. It's a feature that became its own worst enemy: the re-render.

Every time state changes in a React component, React re-renders that component and — by default — every component below it in the tree. This is fine when your component tree is small. It becomes a production nightmare when you have a dashboard with 200+ components, complex state management, and users who notice when things feel slow.

The traditional solution was manual memoization: React.memo for components, useMemo for computed values, useCallback for functions passed as props. Developers learned this the hard way — usually after their first profiling session revealed that one parent component was causing 80% of their re-renders.

Here's what nobody tells juniors: memoization has a cost. Every useMemo call allocates memory and runs a comparison check on every render, even when it's not needed. Used incorrectly, you can make your app slower by trying to optimize it. I've done this.

React 19 addresses this problem from two different directions simultaneously. The Compiler handles the memoization problem. RSCs handle the data fetching problem. And a set of new hooks — useActionState, useFormStatus, useOptimistic — handle the async interaction problem.

This isn't a version bump. This is React paying off years of technical debt it accumulated from its own success.

THE BREAKDOWN — The Problem React 19 Is Actually Solving

Before I explain what React 19 does, I need to show you what breaks without it. This is the pattern I've seen in every React codebase I've touched in 15 years — from the IoT dashboards I was building in 2014 to the enterprise security panels I work on today.

The Re-render Waterfall

// This is a real pattern. I've seen it in production.
// It looks innocent. It is not.

function Dashboard() {
  const [searchText, setSearchText] = useState('');
  const [selectedFilter, setSelectedFilter] = useState('all');

  return (
    <div>
      <SearchBar
        value={searchText}
        onChange={setSearchText}
      />
      <FilterPanel
        selected={selectedFilter}
        onFilterChange={setSelectedFilter}
      />
      {/* This re-renders on EVERY searchText change */}
      {/* Even though it only cares about selectedFilter */}
      <ExpensiveDataTable
        filter={selectedFilter}
        search={searchText}
      />
    </div>
  );
}

Every time the user types a character in SearchBar, the entire Dashboard re-renders. FilterPanel re-renders. ExpensiveDataTable re-renders. If ExpensiveDataTable has 50 child rows, each of those re-renders too.

The traditional fix:

// The "optimized" version — before React 19

function Dashboard() {
  const [searchText, setSearchText] = useState('');
  const [selectedFilter, setSelectedFilter] = useState('all');

  // Memoize the search handler so SearchBar doesn't
  // cause unnecessary re-renders downstream
  const handleSearchChange = useCallback((text: string) => {
    setSearchText(text);
  }, []); // Empty deps — this function never changes

  const handleFilterChange = useCallback((filter: string) => {
    setSelectedFilter(filter);
  }, []); // Same here

  // Memoize the filtered data computation
  const tableProps = useMemo(() => ({
    filter: selectedFilter,
    search: searchText,
  }), [selectedFilter, searchText]);

  return (
    <div>
      <SearchBar
        value={searchText}
        onChange={handleSearchChange} // Stable reference
      />
      <FilterPanel
        selected={selectedFilter}
        onFilterChange={handleFilterChange} // Stable reference
      />
      <MemoizedDataTable {...tableProps} />
    </div>
  );
}

// And you need this too:
const MemoizedDataTable = React.memo(ExpensiveDataTable);

This works. But look at what you had to do:

Add useCallback twice
Add useMemo once
Wrap the child component in React.memo
Think carefully about dependency arrays
Pray you didn't miss a dependency

And this is a simple example. In production, with 10 developers working on the same codebase, this pattern breaks constantly. Someone forgets React.memo. Someone adds a prop to the dependency array that shouldn't be there. Someone passes an inline object as a prop and breaks memoization silently.

This is the problem React 19's Compiler exists to solve.

THE MATCH REPORT — What React 19 Actually Changes

1, 2, 3, Tap — The React Compiler

The React Compiler (previously called React Forget) is a build-time tool that analyzes your component code and automatically inserts memoization where it's needed. You write clean, obvious code. The compiler makes it performant.

// What YOU write with React Compiler enabled:

function Dashboard() {
  const [searchText, setSearchText] = useState('');
  const [selectedFilter, setSelectedFilter] = useState('all');

  // No useCallback. No useMemo. No React.memo.
  // Just... code.

  return (
    <div>
      <SearchBar
        value={searchText}
        onChange={(text) => setSearchText(text)} // Inline function — FINE now
      />
      <FilterPanel
        selected={selectedFilter}
        onFilterChange={(f) => setSelectedFilter(f)} // Also fine
      />
      <ExpensiveDataTable
        filter={selectedFilter}
        search={searchText}
      />
    </div>
  );
}

The compiler looks at this code and figures out: "The inline function (text) => setSearchText(text) doesn't depend on anything outside Dashboard that changes. I can make it stable." It inserts memoization at compile time. The output is performant code without you having to think about it.

But here's what the tutorials don't say — and this is the Red Card moment:

Red Card 🟥 — The Compiler only works if your code follows React's rules.

The Rules of React aren't just guidelines. They're the contract the Compiler depends on. If you violate them, the Compiler silently opts that component out of optimization. Your code still runs. It's just not optimized. And you have no idea.

The three rules that trip up the most developers:

Rule 1: Components must be pure — same inputs, same output. Side effects only in useEffect.

// 🚫 This breaks the Compiler's analysis:
let globalCounter = 0;

function BadComponent({ name }: { name: string }) {
  globalCounter++; // Mutation of external variable
  return <div>{name} — render #{globalCounter}</div>;
}

// ✅ This is what the Compiler can optimize:
function GoodComponent({ name, renderCount }: { name: string; renderCount: number }) {
  return <div>{name} — render #{renderCount}</div>;
}

Rule 2: Hooks rules — no conditional hooks, no hooks in loops. The Compiler depends on the hook call order being stable.

Rule 3: Don't mutate props or state — always create new objects/arrays.

// 🚫 The Compiler cannot optimize components that do this:
function BadList({ items }: { items: Item[] }) {
  items.push({ id: 'temp', name: 'Loading...' }); // Mutation!
  return <ul>{items.map(i => <li key={i.id}>{i.name}</li>)}</ul>;
}

// ✅ Create new arrays:
function GoodList({ items }: { items: Item[] }) {
  const displayItems = [...items, { id: 'temp', name: 'Loading...' }];
  return <ul>{displayItems.map(i => <li key={i.id}>{i.name}</li>)}</ul>;
}

The Compiler is not magic. It's a very smart tool that rewards clean code.

If your codebase has violations — and most production codebases do — you need to fix them before the Compiler helps you. The good news: the React team ships an ESLint plugin that surfaces violations. Run it. Fix what it finds. Then enable the Compiler.

How to Enable It Today

npm install -D babel-plugin-react-compiler
# or with Next.js 15+:
# It's already in the experimental config

// next.config.js
const nextConfig = {
  experimental: {
    reactCompiler: true,
  },
};

module.exports = nextConfig;

// For non-Next.js projects, babel.config.js:
module.exports = {
  plugins: [
    ['babel-plugin-react-compiler', {
      // Start with specific files to test
      sources: (filename) => filename.includes('src/components'),
    }],
  ],
};

My recommendation: Don't enable it globally on day one. Enable it file by file, watch your bundle analyzer, run your tests. The Compiler is in beta. It's stable enough to use, but you want to be able to isolate issues.

2. React Server Components — The Thing Most Developers Get Wrong

RSCs are the most powerful and the most misunderstood feature in the React 19 ecosystem. Let me explain them the way I wish someone had explained them to me.

The mental model shift:

Before RSCs, there were two ways to get data into your component:

Fetch in useEffect (client-side, after render)
Fetch in getServerSideProps or getStaticProps (Next.js patterns, tied to pages)

Both have problems. useEffect fetching causes waterfalls — component A renders, fires a request, waits, then renders component B, which fires another request. You've seen this: the spinning spinner on top of a spinning spinner.

getServerSideProps solves the waterfall but creates a new problem: it's page-level only. If your data is needed by a deeply nested component, you have to pass it through 5 layers of props, or put it in global state. Neither is clean.

RSCs give components the ability to fetch their own data on the server, in parallel, before anything reaches the client.

// @/app/dashboard/page.tsx
// This is a Server Component by default in Next.js App Router

import { getUserMetrics } from '@/lib/db';
import { getActiveAlerts } from '@/lib/alerts';
import MetricsPanel from '@/components/MetricsPanel';
import AlertsPanel from '@/components/AlertsPanel';
import FilterControls from '@/components/FilterControls'; // Client Component

export default async function DashboardPage() {
  // These run IN PARALLEL on the server
  // No waterfall. No loading state. No useEffect.
  const [metrics, alerts] = await Promise.all([
    getUserMetrics(),
    getActiveAlerts(),
  ]);

  return (
    <div className="dashboard">
      {/* Server Component — no JS shipped to client */}
      <MetricsPanel data={metrics} />

      {/* Server Component — no JS shipped to client */}
      <AlertsPanel alerts={alerts} />

      {/* Client Component — needs interactivity */}
      <FilterControls />
    </div>
  );
}

MetricsPanel and AlertsPanel are Server Components. They render on the server, produce HTML, and ship zero JavaScript to the client. The browser receives rendered HTML for those components. Instant paint. No hydration delay.

FilterControls needs client-side interactivity — state, event handlers — so it's a Client Component. It gets hydrated in the browser.

The bundle size impact is real. In a project I was analyzing recently, moving data-display components to Server Components reduced the client bundle by 34%. Components that imported heavy libraries (date formatters, chart utilities) for display-only purposes now ran those imports exclusively on the server. The client never downloaded them.

The Server-Client Boundary — Where Everything Goes Wrong

This is where I need to slow down and be precise, because this is where developers spend hours debugging.

The boundary rule: A Server Component can import and render Client Components. A Client Component cannot import Server Components.

// ✅ This works — Server Component rendering a Client Component:

// ServerComponent.tsx (no 'use client' directive)
import ClientButton from './ClientButton'; // Client Component

export default async function ServerComponent() {
  const data = await fetchData();
  return (
    <div>
      <p>{data.title}</p>
      <ClientButton label="Click me" /> {/* Fine */}
    </div>
  );
}

// 🚫 This BREAKS — Client Component trying to use a Server Component:

'use client';
// ClientWrapper.tsx
import ServerDataFetcher from './ServerDataFetcher'; // Server Component

export default function ClientWrapper() {
  const [count, setCount] = useState(0);
  return (
    <div>
      <ServerDataFetcher /> {/* This will error. Server Component inside Client. */}
      <button onClick={() => setCount(c => c + 1)}>{count}</button>
    </div>
  );
}

The error message you'll see: Error: async/await is not yet supported in Client Components, only Server Components.

It's confusing because the reason is that Server Components are async by nature — they can await promises. Client Components can't run async code at the top level. When you try to nest a Server Component inside a Client Component, React doesn't know how to handle the async boundary.

The fix: Pass server data as props, or pass Server Components as children.

// ✅ Pattern 1: Pass data down as props

// ServerParent.tsx
import ClientWrapper from './ClientWrapper';

export default async function ServerParent() {
  const data = await fetchData(); // Runs on server
  return <ClientWrapper initialData={data} />; // Pass as prop
}

// ClientWrapper.tsx
'use client';
export default function ClientWrapper({ initialData }) {
  const [data, setData] = useState(initialData);
  // Now you have client-side state AND server-fetched initial data
  return <div>{/* render data */}</div>;
}

// ✅ Pattern 2: Pass Server Components as children (the elegant solution)

// ServerParent.tsx
import ClientWrapper from './ClientWrapper';
import ServerDisplay from './ServerDisplay';

export default async function ServerParent() {
  return (
    <ClientWrapper>
      <ServerDisplay /> {/* Server Component passed as children prop */}
    </ClientWrapper>
  );
}

// ClientWrapper.tsx
'use client';
export default function ClientWrapper({ children }) {
  const [isOpen, setIsOpen] = useState(false);
  return (
    <div>
      <button onClick={() => setIsOpen(!isOpen)}>Toggle</button>
      {isOpen && children} {/* ServerDisplay renders here, still on server */}
    </div>
  );
}

Pattern 2 is the one most tutorials skip. It feels strange at first — how can a Client Component render a Server Component? The answer: it doesn't. The Server Component was already rendered on the server. The Client Component is just deciding where to place the already-rendered output.

When NOT to Use Server Components

This is the part I want tattooed somewhere visible.

Don't use Server Components for:

Anything with event handlers — onClick, onChange, onSubmit. These require client-side JS. Server Components can't have them.
Anything with React state — useState, useReducer. No state on the server.
Anything with browser APIs — window, localStorage, navigator. The server doesn't have a browser.
Anything that needs real-time updates — WebSockets, polling. Server Components render once, at request time.

// 🚫 Common mistake — trying to use state in a Server Component:

// ProductCard.tsx (accidentally Server Component — no 'use client')
export default async function ProductCard({ productId }) {
  const product = await getProduct(productId);

  // THIS WILL ERROR:
  const [isWishlisted, setIsWishlisted] = useState(false);

  return (
    <div>
      <h3>{product.name}</h3>
      <button onClick={() => setIsWishlisted(!isWishlisted)}>
        {isWishlisted ? '❤️' : '🤍'}
      </button>
    </div>
  );
}

The fix: Split it. The data-fetching part is a Server Component. The interactive part is a Client Component.

// ✅ ProductCard.tsx — Server Component
import WishlistButton from './WishlistButton'; // Client Component

export default async function ProductCard({ productId }) {
  const product = await getProduct(productId);

  return (
    <div>
      <h3>{product.name}</h3>
      <p>{product.description}</p>
      {/* Interactivity lives in the Client Component */}
      <WishlistButton productId={productId} />
    </div>
  );
}

// WishlistButton.tsx — Client Component
'use client';
export default function WishlistButton({ productId }) {
  const [isWishlisted, setIsWishlisted] = useState(false);

  return (
    <button onClick={() => setIsWishlisted(!isWishlisted)}>
      {isWishlisted ? '❤️' : '🤍'}
    </button>
  );
}

3. The New Hooks — Actions and Async State

React 19 ships three new hooks that change how you handle form submissions and async operations. These are smaller in footprint than the Compiler and RSCs, but they'll show up in your daily code immediately.

`useActionState` — The End of Verbose Form State

Before React 19, a form with proper loading, error, and success states looked like this:

// Before React 19 — the verbose version
function ContactForm() {
  const [isPending, setIsPending] = useState(false);
  const [error, setError] = useState<string | null>(null);
  const [success, setSuccess] = useState(false);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setIsPending(true);
    setError(null);
    setSuccess(false);

    try {
      await submitContactForm(new FormData(e.target as HTMLFormElement));
      setSuccess(true);
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Something went wrong');
    } finally {
      setIsPending(false);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="email" type="email" />
      <button disabled={isPending}>
        {isPending ? 'Sending...' : 'Send'}
      </button>
      {error && <p className="error">{error}</p>}
      {success && <p className="success">Message sent!</p>}
    </form>
  );
}

Six state variables and a try/catch/finally. Every form. Every time.

With useActionState:

// React 19 — useActionState
import { useActionState } from 'react';

type FormState = {
  error: string | null;
  success: boolean;
};

async function submitAction(
  prevState: FormState,
  formData: FormData
): Promise<FormState> {
  try {
    await submitContactForm(formData);
    return { error: null, success: true };
  } catch (err) {
    return {
      error: err instanceof Error ? err.message : 'Something went wrong',
      success: false,
    };
  }
}

function ContactForm() {
  const [state, formAction, isPending] = useActionState(submitAction, {
    error: null,
    success: false,
  });

  return (
    <form action={formAction}>
      <input name="email" type="email" />
      <button disabled={isPending}>
        {isPending ? 'Sending...' : 'Send'}
      </button>
      {state.error && <p className="error">{state.error}</p>}
      {state.success && <p className="success">Message sent!</p>}
    </form>
  );
}

Notice action={formAction} on the form. In React 19, <form> elements can accept async functions as their action prop. React handles the pending state automatically. Your component logic is now: define the action, render based on state. That's it.

`useFormStatus` — Knowing What's Happening Above You

This hook solves a specific but very common problem: a submit button that needs to know if the form it's inside is pending, without passing props through multiple layers.

// useFormStatus — the button knows its own form's state
import { useFormStatus } from 'react-dom';

function SubmitButton() {
  const { pending } = useFormStatus();
  // 'pending' is true when the parent form's action is running
  // No props needed. No context. It just knows.

  return (
    <button type="submit" disabled={pending}>
      {pending ? 'Submitting...' : 'Submit'}
    </button>
  );
}

// Use it anywhere inside a form:
function MyForm() {
  return (
    <form action={someServerAction}>
      <input name="data" />
      <SubmitButton /> {/* Automatically aware of form state */}
    </form>
  );
}

This sounds small. It isn't. In a design system with a shared Button component used across dozens of forms, this eliminates an entire class of prop-threading.

`useOptimistic` — The UX Win You Can Ship This Week

Optimistic updates have always been possible in React. They've never been this clean.

// useOptimistic — update UI immediately, sync with server after
import { useOptimistic, useActionState } from 'react';

type Message = {
  id: string;
  text: string;
  sending?: boolean; // Optimistic flag
};

function MessageThread({ messages }: { messages: Message[] }) {
  const [optimisticMessages, addOptimisticMessage] = useOptimistic(
    messages,
    (currentMessages, newMessage: Message) => [
      ...currentMessages,
      { ...newMessage, sending: true }, // Show immediately with 'sending' flag
    ]
  );

  const [, formAction] = useActionState(
    async (prevState: null, formData: FormData) => {
      const text = formData.get('text') as string;
      const tempMessage: Message = { id: crypto.randomUUID(), text };

      addOptimisticMessage(tempMessage); // Update UI immediately

      await sendMessage(text); // Then actually send
      return null;
    },
    null
  );

  return (
    <div>
      <ul>
        {optimisticMessages.map((msg) => (
          <li
            key={msg.id}
            style={{ opacity: msg.sending ? 0.5 : 1 }} // Visual feedback
          >
            {msg.text}
            {msg.sending && ' (sending...)'}
          </li>
        ))}
      </ul>
      <form action={formAction}>
        <input name="text" />
        <button type="submit">Send</button>
      </form>
    </div>
  );
}

The message appears in the UI instantly. If the server call fails, React automatically rolls back to the previous state. If it succeeds, the optimistic message gets replaced by the real one. This is the UX pattern that makes apps feel fast — and React 19 makes it a handful of lines instead of a whole state machine.

THE TECHNICAL DEEP DIVE — React 18 vs React 19: What Changed in Production

Let me be specific. Here's a side-by-side of the most common patterns and how they change:

Data Fetching

// React 18 — data fetching in useEffect
function UserProfile({ userId }: { userId: string }) {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    let cancelled = false;

    async function fetchUser() {
      try {
        const data = await getUser(userId);
        if (!cancelled) {
          setUser(data);
        }
      } catch (err) {
        if (!cancelled) {
          setError(err instanceof Error ? err : new Error('Unknown error'));
        }
      } finally {
        if (!cancelled) {
          setLoading(false);
        }
      }
    }

    fetchUser();
    return () => { cancelled = true; }; // Cleanup for StrictMode
  }, [userId]);

  if (loading) return <Spinner />;
  if (error) return <ErrorState message={error.message} />;
  if (!user) return null;

  return <div>{user.name}</div>;
}

// React 19 with RSC — data fetching is just... async/await
// UserProfile.tsx (Server Component)

export default async function UserProfile({ userId }: { userId: string }) {
  // This runs on the server. No useEffect. No loading state.
  // Errors bubble to the nearest error.tsx boundary.
  const user = await getUser(userId);

  return <div>{user.name}</div>;
}

The Server Component version is not simpler by accident. It's simpler because you've moved the async work to where async work belongs: the server, where there's no browser paint to block and no cleanup function needed because there's no component lifecycle.

Error Handling

React 19 improves Error Boundaries with better integration:

// app/users/[id]/error.tsx — Next.js App Router error boundary
'use client'; // Error boundaries must be client components

export default function UserError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <div>
      <h2>Something went wrong loading this profile.</h2>
      <p>{error.message}</p>
      <button onClick={() => reset()}>Try again</button>
    </div>
  );
}

When the Server Component throws, Next.js catches it and renders this boundary automatically. No manual try/catch in your component. No complex error state management. The error surface is clean and predictable.

`use()` — The New Data Primitive

React 19 ships a new primitive called use() that lets you read promises and context in Client Components without useEffect:

// The new use() hook
import { use, Suspense } from 'react';

// In a Client Component:
'use client';

function UserCard({ userPromise }: { userPromise: Promise<User> }) {
  // use() suspends the component until the promise resolves
  // No useEffect. No useState. No loading flag.
  const user = use(userPromise);

  return <div>{user.name}</div>;
}

// In the parent Server Component:
export default function Page({ params }) {
  // Start fetching immediately, pass the Promise down
  const userPromise = getUser(params.id);

  return (
    <Suspense fallback={<Spinner />}>
      <UserCard userPromise={userPromise} />
    </Suspense>
  );
}

This pattern — start the fetch in the Server Component, pass the promise to the Client Component — eliminates the waterfall without requiring the Client Component to be async. The Suspense boundary handles the loading state.

THE UNCOMFORTABLE TRUTH

Here it is. The thing the hype doesn't say.

React 19's improvements are most valuable for developers who already understand React 18 deeply.

The Compiler helps you avoid bugs with memoization — but only if you already know what memoization is for. If you don't understand why useCallback exists, you can't tell when the Compiler has opted your component out. You'll think it's working. It isn't.

RSCs simplify data fetching — but only if you understand the server-client boundary well enough to know what can't go on the server. The number one RSC bug in production is trying to use browser APIs (localStorage, window) in a Server Component. The error message is confusing. The fix is trivial — but only if you understand the mental model.

The trap for mid-level developers: seeing the simplified code, learning the patterns by imitation, and building apps that work in development but fail in production edge cases. I've seen this happen. At Selfapy, building the first mobile app with React Native, I watched a developer copy patterns from tutorials without understanding the execution environment — and we found the bugs three days before launch.

There's no shortcut here. React 19 rewards understanding. It punishes cargo-culting.

The trap for senior developers: dismissing these features because "the fundamentals haven't changed." They have. The mental model for data fetching has changed. The boundary between server and client is a new concept that doesn't have a clean equivalent in React 18. Seniors who don't engage with RSCs seriously are going to be debugging Next.js App Router issues they don't understand.

Both traps have the same solution: go slow, go deep, understand before you build.

PRO TIP — The Migration Playbook I'd Follow Today

I wish someone had given me this specific, ordered list when App Router shipped.

Week 1 — Audit, don't migrate:

Run the React Compiler's ESLint plugin on your codebase:

npm install -D eslint-plugin-react-compiler

// .eslintrc
{
  "plugins": ["react-compiler"],
  "rules": {
    "react-compiler/react-compiler": "error"
  }
}

Count your violations. If you have more than 20, fix them before enabling the Compiler. Each violation is a component the Compiler won't optimize.

Week 2 — Enable the Compiler on leaf components first:

Leaf components — components that don't have complex children — are the safest to enable first. Enable it on your design system components: buttons, inputs, cards. Watch your Lighthouse scores.

Week 3 — Identify your Server Component candidates:

A component is a good Server Component candidate if:

It fetches data directly
It doesn't have event handlers or state
It imports heavy libraries purely for display (date-fns, lodash, chart libs)

Mark them. Plan the split.

Week 4 — Migrate one feature end-to-end:

Pick one route in your app. Migrate it fully — Server Components for data, Client Components for interactivity. Measure the bundle size difference before and after. That number becomes your business case for the rest of the migration.

The thing I wish I'd known: Don't migrate the layout layer first. Start with leaf data components. The layout layer is where the server-client boundary gets complicated, and you want to understand the pattern before you wrestle with it in the most complex part of your app.

VAR SECTION — The Objections I'd Raise in Code Review

Objection 1: "The Compiler is in beta. It's not production-ready."

Partially fair. The Compiler is beta — but it's running in production at Meta. The Instagram web app uses it. The risk profile is: the Compiler opts out of optimizing components it's unsure about, rather than optimizing them incorrectly. Your app won't break. You just might not get the optimization. For low-risk components (pure display components with no side effects), enabling it in production today is reasonable. For complex stateful components, wait for the stable release.

Objection 2: "We're not on Next.js. RSCs don't apply to us."

Currently, RSCs require framework support. Next.js App Router and Remix (via Vite + React Router v7) are the main options. If you're on Vite with React only, you're not getting RSCs yet. But the React team is working on standalone RSC support. Keep watching the React server rendering RFC. This will come to more frameworks.

Objection 3: "We don't have performance problems. Why migrate?"

That's the wrong frame. React 19 isn't about fixing performance problems you already have — it's about not building performance problems into your next project. If you're starting a new app today and not using RSCs, you're going to write waterfall data fetching that you'll need to fix in 18 months. The correct time to learn the patterns is before the technical debt exists, not after.

That said: if you have a stable, working React 18 app with no performance issues and no new features planned, there's no urgency to migrate. React 18 is supported. Don't fix what isn't broken.

BISHOY'S BOOKMARKS — إذا عاوز تغوص أعمق

📄 Article: "React Compiler Beta Release" — React Official Blog (October 2024)

Why it made my brain itch: The section explaining why the Compiler opts out of optimizing non-compliant components — silently, without errors — is the most important paragraph in the whole post. Read it twice before you enable the Compiler on your codebase.

📄 Article: "Making Sense of React Server Components" — Josh W. Comeau

Why it made my brain itch: The best visual explanation of the server-client boundary I've found anywhere. Josh draws the line between SSR and RSCs in a way that makes the 'use client' directive finally click. The diagrams alone are worth 30 minutes of your time.

📄 RFC: "React Server Components RFC #0188" — reactjs/rfcs on GitHub

Why it made my brain itch: Reading the "Motivation" section of the original RFC answers every "but why did they build this?" question. The React team wasn't chasing a trend — they were solving specific, measured pain points. Understanding those pain points makes every RSC decision obvious.

🎥 Video: "The Modern Full-Stack React Tutorial" — Theo Browne (t3dotgg) on YouTube

Why it's here: Theo covers RSCs, Server Actions, and the App Router mental model in the most honest, opinionated way I've seen. He doesn't hand-wave the hard parts. Search his channel for "React 19" — his reaction videos to the React team's announcements are unfiltered and technically solid.

📄 Docs: "React Compiler — Rules of React" — react.dev

Why it made my brain itch: This is the contract the Compiler depends on. Every violation is a component the Compiler will silently skip. Run the ESLint plugin against your codebase and count the violations before you do anything else.

💬 Quote I'm keeping:

"React Compiler is able to compile code safely by modeling both the rules of JavaScript and the rules of React." — React Labs blog, February 2024

Why this stays with me: The operative word is "safely." The Compiler won't break your app. It will just quietly not optimize the parts that don't follow the rules. That's both reassuring and dangerous — because you can think it's working when it isn't.

THE UNFINISHED CHAPTER

I want to be honest about what I don't fully understand yet.

The Compiler's interaction with complex custom hooks — I know it works well with simple hooks. I'm not confident yet about highly stateful hooks with complex dependency graphs. I've seen it behave unexpectedly with hooks that have nested useEffect calls. I'm still testing this.

The cache() primitive — React 19 ships a cache() function for deduplicating requests in Server Components. I understand the theory. I haven't built enough with it yet to have opinions about where it fails. If you have, I want to hear about it.

The long-term of RSC and client state management — Redux, Zustand, Jotai. These all work with Client Components. But as more logic moves to the server, I have a genuine open question: does the role of client-side state management shrink dramatically? In five years, is most of what we put in Zustand today just... server state managed by RSCs? I think yes. I'm not sure.

And here's the thing I got wrong for two years: I thought SSR and RSCs were the same thing. They're not even close. SSR is a rendering technique. RSCs are an architectural model. Conflating them caused me to dismiss RSC discussions as "we already do SSR." If I had understood the distinction earlier, I would have been more useful to my team when we migrated.

What are you still confused about? Drop it in the comments. I'll write the follow-up.

✨ 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? Check out my book: Surrounded by AI

DEV Community: Bishoy Bishai

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

What "Averageness at Scale" Looks Like

The Standard Document: What It Contains and Why

1. Folder Structure — The First Decision That Shapes Everything

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

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

4. State Management Decision Tree

Making Copilot Enforce Your Standard

The Uncomfortable Truth About Standards

But

📚 my notes

How React + Vite Actually Works Behind the Scenes Breakdown

Mastering Navigation with React Router: A Comprehensive Guide

Mastering Navigation with React Router: A Comprehensive Guide

Why Does Navigation Matter So Much?

The Core Building Blocks: A Quick Refresher

Diving Deeper: Power with Hooks

useNavigate: Programmatic Navigation

useParams and useSearchParams: Dynamic Data

Advanced Insights and Lessons Learned

Common Pitfalls to Avoid

Bringing it All Together

The Frontend World Just Changed: 5 Shifts for 2026

The Frontend World Just Changed: 5 Shifts Professional Devs Need to Master for 2026

1. The Server-First Frontend (and the Edge): Beyond SSR, Welcome Server Components

2. Hyper-Personalization & AI Integration: Beyond Chatbots

3. Performance as a Core Feature, Not an Afterthought

4. Developer Experience (DX) is Paramount: Beyond Just Speed

5. The Rise of the "Frontend Platform": Your New Backend is a Service

Embracing the Future

Why Every Link You Share Shows Your Homepage Logo

The Mental Model Shift: Two UIs, One Page

Why Static Meta Tags Are a Product Bug

The Pattern: RouteHeadMeta

Approach 1: Next.js App Router (The Current Standard)

Approach 2: Remix (The meta Export)

Approach 3: Next.js Pages Router

Approach 4: Bare React SPA with react-helmet-async

The Uncomfortable Truth About Meta Tags

Real Objections

For more

The best place to hide a dead body is the second page of Google search results

The Core Web Vitals Problem Nobody Talks About

Which Pages You Cannot Afford to Get Wrong

Building the Next.js SEO Stack — Complete Implementation

Layer 1: Rendering Strategy Per Page Type

Layer 2: Metadata That Actually Works

Layer 3: Structured Data — The Part Everyone Skips

Layer 4: The next/image Non-Negotiable

The Sitemap You're Probably Not Generating Correctly

But

📚 For more you can check

Dark Mode Isn't a Feature. It's a Promise. Here's How to Keep It.

The Three Trust Layers — This Is the Mental Model

The Foundation: CSS Variables as Theme Tokens

Layer 3 First: Killing the FOUC Before React Loads

The React Layer: Context, Hook, and State Management

The Toggle Component — and the Three-State Option

The Uncomfortable Truth About Dark Mode

Real Objections

📚 Nice to read more about dark mode

Next.js vs React: When Should You Use Each?

`useNavigate`: Programmatic Navigation

`useParams` and `useSearchParams`: Dynamic Data

Approach 2: Remix (The `meta` Export)

`useActionState` — The End of Verbose Form State

`useFormStatus` — Knowing What's Happening Above You

`useOptimistic` — The UX Win You Can Ship This Week

`use()` — The New Data Primitive