Forem: Meriç Cintosun

Reducing Network Overhead with Layout Deduplication in the Next.js App Router

Meriç Cintosun — Wed, 08 Apr 2026 15:21:20 +0000

Why Layout Deduplication Exists

Every meaningful performance optimization in a framework emerges from a concrete bottleneck that enough production applications hit. Layout deduplication in the Next.js App Router addresses a specific class of redundancy that becomes visible at scale: when a user navigates between dozens of routes that share a common layout tree, the browser should not pay the cost of re-fetching or re-evaluating static portions of that tree on each navigation. In an e-commerce application with 50 product category pages all mounted under the same shell, the problem is not theoretical.

The App Router's file-system routing model introduced nested layouts as a first-class primitive. A layout.tsx file at any directory level wraps all routes beneath it, and that wrapper persists across navigations within its subtree. The deduplication work extends this mental model into the prefetching layer: when the router prefetches multiple links simultaneously, it should recognize that many of those targets share layout segments and issue only the work necessary for their diverging leaves.

Understanding the engineering decisions behind this requires understanding how the router represents routes, how prefetch payloads are structured, and where the React Server Components protocol intersects with HTTP cache semantics. We will cover each of these before examining how the optimization manifests in a real e-commerce scenario.

How the App Router Represents Routes Internally

The App Router models every URL as a tree of segments. A URL like /shop/electronics/laptops decomposes into the segments shop, electronics, and laptops, each of which may have an associated layout.tsx, page.tsx, loading.tsx, and error.tsx. The router stores its understanding of the current UI as a segment tree in a client-side cache.

Each node in that cache holds a React Server Component (RSC) payload for its segment. RSC payloads are serialized representations of server-rendered component trees, transmitted as a streaming text format over the network. When a navigation occurs, the router compares the incoming segment tree against the cached one and requests only the RSC payloads for segments that have changed. Segments whose layout files have not changed and whose props remain identical are served directly from the client cache.

This diffing is possible because the App Router assigns a stable identity to each layout segment based on its file path. /app/shop/layout.tsx always maps to the shop layout node regardless of what leaf page is active beneath it. The router can therefore determine before issuing any network request whether a given layout segment is already in cache and still valid.

The RSC Payload Format and Segment Boundaries

RSC payloads use a line-delimited JSON format (sometimes called the Flight protocol). Each line encodes a chunk of the virtual DOM tree, and chunks reference each other by integer identifiers. A simplified payload for a page under a shared layout looks approximately like this:

1:["$","div",null,{"className":"shop-shell","children":"$L2"}]
2:["$","main",null,{"children":"$L3"}]
3:["$","article",null,{"children":"Laptop Pro 14 details..."}]

The layout contributes chunks 1 and 2. The page contributes chunk 3. When the router already holds chunks 1 and 2 in its segment cache, it can request a payload that starts at chunk 3, skipping the layout entirely. The server must therefore be capable of rendering and streaming partial subtrees, starting from any segment boundary. Next.js accomplishes this through its internal renderToReadableStream pipeline, which accepts a renderOpts.postponed mechanism that allows resuming rendering from a specific point in the tree.

Prefetching: The Problem Space

Navigation in a modern web application is not purely reactive. When a user's cursor moves toward a link or when a link enters the viewport, the framework can speculatively fetch the destination page before the click occurs. Next.js implements this through the <Link> component, which triggers a prefetch when a link becomes visible in the viewport by default.

The problem emerges when a page renders many links simultaneously. Consider a category listing page in an e-commerce application: it may render 50 product cards, each linking to a product detail page. All 50 product pages share the same layout tree: RootLayout -> ShopLayout -> ProductLayout -> ProductPage. If the browser fires a prefetch request for each link as it enters the viewport, the server receives 50 requests. Without deduplication, the response to each request includes the RSC payload for RootLayout, ShopLayout, and ProductLayout, plus the leaf ProductPage payload. The shared layout data is transmitted 50 times.

At a conservative estimate, a typical React Server Component layout for a shop shell might serialize to 8 to 15 kilobytes of RSC payload. Multiplied across 50 prefetch requests, that means 400 to 750 kilobytes of redundant layout data on top of the actual page content. On a mobile connection or in a region with high latency, this consumes bandwidth that should be reserved for content the user will actually read.

Prefetch Granularity Before Deduplication

Before layout deduplication, the prefetch system operated at the route level. A prefetch for /shop/products/laptop-pro-14 would return the full RSC payload for the entire route, from root layout to leaf page. The client cache stored the result keyed by the full pathname. Two prefetch requests for /shop/products/laptop-pro-14 and /shop/products/gaming-chair-x would both return full payloads including the identical ShopLayout and ProductLayout segments.

The client cache did store these payloads and would serve subsequent navigations from cache, but the network cost during the prefetch phase was fully duplicated. The deduplication work moves the optimization earlier, into the prefetch request itself.

Layout Deduplication: The Engineering Approach

Layout deduplication restructures prefetching around segment-level cache keys rather than full-pathname keys. The router maintains a segment cache that maps a (layoutPath, params) tuple to an RSC payload promise. When a prefetch request is about to be issued, the router first checks which segments along the target route are already in the segment cache. It then requests only the missing segments from the server.

The server-side rendering pipeline exposes a prefetchSegments API that accepts a list of segment paths and returns a response containing only those segments' RSC payloads. Two concurrent prefetch requests for two different product pages will both find ShopLayout already in-flight or cached after the first request resolves, and neither will request it again.

// Simplified representation of the segment cache lookup
// in the Next.js client router internals

interface SegmentCacheEntry {
  payload: Promise<RSCPayload>;
  expiresAt: number;
}

type SegmentCacheKey = `${string}:${string}`; // layoutPath:serializedParams

const segmentCache = new Map<SegmentCacheKey, SegmentCacheEntry>();

function getCacheKey(layoutPath: string, params: Record<string, string>): SegmentCacheKey {
  return `${layoutPath}:${JSON.stringify(params)}`;
}

async function prefetchRoute(href: string): Promise<void> {
  const segments = parseRouteIntoSegments(href);
  const missingSegments: RouteSegment[] = [];

  for (const segment of segments) {
    const key = getCacheKey(segment.layoutPath, segment.params);
    if (!segmentCache.has(key) || isCacheStale(segmentCache.get(key)!)) {
      missingSegments.push(segment);
    }
  }

  if (missingSegments.length === 0) return;

  const payload = fetchSegmentPayloads(missingSegments);

  for (const segment of missingSegments) {
    const key = getCacheKey(segment.layoutPath, segment.params);
    segmentCache.set(key, {
      payload,
      expiresAt: Date.now() + PREFETCH_CACHE_TTL,
    });
  }
}

The actual Next.js implementation is more involved, handling streaming, suspense boundaries, and cache invalidation on mutation, but the core logic follows this shape. The segment cache entries store promises, which means concurrent prefetch requests for the same segment key will await the same in-flight network request rather than issuing duplicates.

Deduplication of In-Flight Requests

Promise-based cache entries handle the race condition where multiple links enter the viewport near-simultaneously and all trigger prefetches before any response has arrived. When the first prefetch for ShopLayout begins, the cache stores a pending promise at that key. Every subsequent prefetch that needs ShopLayout finds the pending promise and awaits it rather than starting a new request. The network connection is established exactly once per unique segment.

This behavior is analogous to how swr and react-query implement request deduplication for data fetching. The key insight is that the cache must store the promise itself, not the resolved value, so that in-flight requests can be shared.

// Demonstrating promise deduplication for concurrent prefetches

async function fetchSegmentPayloads(
  segments: RouteSegment[]
): Promise<Map<SegmentCacheKey, RSCPayload>> {
  const url = buildPrefetchURL(segments);

  // This fetch is shared across all callers awaiting the same segments
  const response = await fetch(url, {
    headers: { "RSC": "1", "Next-Router-Prefetch": "1" },
  });

  return parseMultiSegmentResponse(response);
}

The Next-Router-Prefetch header signals to the server that this is a prefetch request. The server uses this signal to adjust rendering behavior: it renders only the static shell of server components and defers dynamic content that would be streamed on actual navigation. This distinction matters because a prefetch should not waste server CPU on personalized or frequently changing data.

Applying This to an E-Commerce Application

Consider a product listing page that renders 50 product cards. Each card links to a product detail page. The routing structure looks like this:

/app
  layout.tsx          <- RootLayout (nav, footer, global providers)
  /shop
    layout.tsx        <- ShopLayout (sidebar, category nav)
    /products
      layout.tsx      <- ProductLayout (breadcrumbs, structured data wrapper)
      /[slug]
        page.tsx      <- ProductPage (images, description, price, CTA)

Without layout deduplication, prefetching all 50 links issues 50 requests, each returning payloads for RootLayout, ShopLayout, ProductLayout, and ProductPage. With deduplication, the first prefetch request fetches all four segments for the first product. The 49 subsequent requests find RootLayout, ShopLayout, and ProductLayout already cached and request only the ProductPage segment for each remaining product.

The network savings scale with the depth of the shared layout tree and the number of co-located links. Three shared layout segments at an average of 10 kilobytes each is 30 kilobytes per prefetch. Across 49 additional navigations, deduplication saves approximately 1.47 megabytes of prefetch traffic. The actual savings depend on how much JavaScript and component state each layout serializes into its RSC payload.

Configuring Prefetch Behavior for Maximum Benefit

The <Link> component's prefetch prop controls when prefetching occurs. The default behavior in the App Router prefetches the static layout shell immediately when a link enters the viewport and defers the dynamic leaf page until hover. This two-phase approach fits well with the deduplication model: shared layout segments are fetched and cached early, and only the cheap leaf segments are fetched on hover.

// app/shop/products/page.tsx

import Link from "next/link";
import { getProducts } from "@/lib/products";

export default async function ProductListingPage() {
  const products = await getProducts();

  return (
    <ul className="product-grid">
      {products.map((product) => (
        <li key={product.slug}>
          {/*
            Default prefetch behavior: prefetches static layout shell
            on viewport entry, full page on hover.
            Set prefetch={false} to disable entirely for low-priority links.
          */}
          <Link href={`/shop/products/${product.slug}`}>
            <img src={product.thumbnailUrl} alt={product.name} />
            <span>{product.name}</span>
          </Link>
        </li>
      ))}
    </ul>
  );
}

For server components that render large lists, it is worth measuring the prefetch volume before and after. The Next.js DevTools panel in the browser shows prefetch requests grouped by segment. A healthy prefetch pattern for 50 links sharing three layout levels should show three segment requests for the first navigation target and one segment request for each subsequent target once the layout cache is warm.

Cache Invalidation and Stale Layouts

The segment cache respects the staleTime that Next.js assigns to prefetch entries, which defaults to 30 seconds for static segments and 0 seconds for dynamic segments. A ShopLayout that reads from a database on every request will be marked dynamic and will not benefit from cross-route deduplication, because each prefetch must re-fetch it to get fresh data.

The practical advice here is to push dynamic data as far down the component tree as possible. If the sidebar in ShopLayout shows a cart item count, consider moving that count into a client component that fetches independently from the layout's RSC payload. The layout itself becomes static and cacheable, while the cart count fetches on the client after hydration.

// app/shop/layout.tsx

import { Suspense } from "react";
import { CategoryNav } from "@/components/CategoryNav";
import { CartCountBadge } from "@/components/CartCountBadge"; // client component

// This layout is now static: no await calls that produce dynamic output.
// Next.js will mark it as static and the segment cache will hold it
// for the full staleTime window.
export default function ShopLayout({ children }: { children: React.ReactNode }) {
  return (
    <div className="shop-wrapper">
      <aside>
        <CategoryNav />
        <Suspense fallback={<span>...</span>}>
          {/* CartCountBadge fetches client-side; does not make this layout dynamic */}
          <CartCountBadge />
        </Suspense>
      </aside>
      <main>{children}</main>
    </div>
  );
}

Measuring the Impact

Quantifying the savings from layout deduplication requires measuring at the network layer, not just in Lighthouse scores. Lighthouse runs a single navigation and does not simulate concurrent prefetches. The more useful measurement is the total bytes transferred during a browsing session that includes entering a listing page and hovering over several product links.

The browser's Network panel in DevTools, filtered by RSC requests (look for requests with the RSC: 1 header), shows the payload sizes for each prefetch. Comparing the total RSC bytes with deduplication enabled against a baseline with prefetch={false} across all links gives a concrete transfer savings number.

A server-side perspective requires logging the segments requested in each prefetch call. Next.js exposes the requested segment paths in the URL of the prefetch request, typically as query parameters like ?_rsc=segmentHash. Aggregating these logs over a session shows how often shared segments are requested versus served from client cache.

# Example: using curl to simulate a prefetch request and inspect response size
curl -s -o /dev/null -w "%{size_download}" \
  -H "RSC: 1" \
  -H "Next-Router-Prefetch: 1" \
  "https://your-app.com/shop/products/laptop-pro-14"

Running this command against a route and then comparing it to a request that omits the shared layout segments demonstrates the per-request savings. In a well-structured application, the layout-only prefetch payload for three layout levels should be significantly smaller than the full-route payload, often by 40 to 60 percent of the total prefetch transfer.

Interaction with the HTTP Cache

The App Router's segment-level prefetch requests are standard HTTP requests and participate in the HTTP cache. When a CDN sits in front of the Next.js application, layout segment responses can be cached at the edge with Cache-Control: public, max-age=30, stale-while-revalidate=60 headers. Subsequent users who visit the same listing page will receive layout segment prefetches from the CDN rather than from the origin.

This layering of client segment cache and HTTP edge cache produces a hierarchy of deduplication. At the client level, a single user browsing 50 product links pays the layout segment cost once per session. At the CDN level, many users browsing the same listing page all receive layout prefetches from cache. The origin server handles only the dynamic leaf page segments that cannot be cached.

Next.js automatically sets Cache-Control headers based on whether a segment is static or dynamic. Static segments receive a s-maxage value that allows CDN caching. Dynamic segments receive no-store. Ensuring that shared layout segments remain static therefore produces benefits at both the client deduplication layer and the HTTP cache layer simultaneously.

If you work on professional Web3 documentation or need a production-grade Next.js application built end to end, take a look at the services available at fiverr.com/meric_cintosun.

Web MCP and Agent-Ready Architectures: Building Next.js Sites for AI Agents

Meriç Cintosun — Mon, 06 Apr 2026 15:21:21 +0000

What the Model Context Protocol Actually Does on the Web

The Model Context Protocol (MCP) is an open standard, originally published by Anthropic, that defines how AI agents communicate with external data sources and tools. On the server side, MCP has been used extensively to connect language models to databases, APIs, and file systems. The web variant of MCP, often called Web MCP, extends this idea to the browser and to publicly accessible HTTP surfaces, enabling agents to read, reason over, and take action on web pages and web-hosted interfaces.

When an AI agent navigates the web today without any MCP integration, it is essentially screen-reading. It receives rendered HTML, attempts to extract structure from what is visually presented, and uses heuristics to decide which elements are interactive. This approach works poorly at scale. Pages built for human visual perception carry enormous noise from a machine-reasoning perspective: decorative wrappers, layout scaffolding, duplicate navigation trees, and implicit semantics that humans resolve through visual context. Web MCP addresses this by giving developers a formal channel through which they can expose structured, action-oriented representations of their interfaces directly to agents.

Google's work on Web MCP, announced as part of the broader ecosystem push following the MCP open-sourcing, focuses on making web pages first-class participants in agentic workflows. A page that implements Web MCP exposes a manifest describing its capabilities: what actions are available, what data can be read, and what schemas govern both input and output. The agent consults this manifest before attempting any interaction, which eliminates the guesswork that makes headless browsing fragile and expensive.

Why HTML Semantics Are an Agent Interface

Before reaching for MCP tooling, every developer building an agent-ready interface needs to understand a more fundamental constraint: agents parse HTML, and the information density of that HTML determines how much useful signal the agent can extract without any additional tooling.

Semantic HTML is not a best practice retrofit for accessibility audits. For an agent, the difference between a <button> and a <div class="btn"> is the difference between a clearly typed interaction target and an element that requires learned heuristics to classify. The <button> element carries implicit ARIA role button, is keyboard focusable by default, and appears in the accessibility tree in a way that programmatic clients can enumerate. The styled <div> carries none of that information unless the developer adds it manually and correctly.

The same principle applies at every level of document structure. A <main> landmark tells an agent where primary content begins, allowing it to skip navigation, sidebars, and footer content when answering a question about page content. An <article> element signals a self-contained unit of content with its own meaning. <nav> delineates navigation regions. <section> with an associated aria-labelledby attribute creates a labeled content region that an agent can reference by name rather than by position. None of this requires MCP. It is the baseline on top of which MCP becomes genuinely useful rather than a patch over a structural deficit.

For interactive surfaces, the implications are even more direct. An agent attempting to complete a form needs to know which label corresponds to which input. The <label for="..."> / id pairing provides this unambiguously. The aria-describedby attribute points to supplementary instructions. The required attribute on an <input> communicates validation constraints without requiring the agent to submit the form and parse an error response. These are not conveniences; they are the load-bearing structural elements of a machine-readable interface.

The Web MCP Architecture

A Web MCP implementation has three components: a capability manifest served at a well-known URL, a set of action endpoints that the agent can invoke, and the annotated HTML interface that the agent reads and interacts with when direct API access is insufficient or unavailable.

The manifest is a JSON document, typically served at /.well-known/mcp.json, that describes the page or application in structured terms. It lists named actions with their input schemas, specifies the data types a reading agent can extract, and declares any authentication requirements. When an agent encounters a domain that serves this file, it can shift from heuristic page-reading to structured capability invocation.

{
  "schema_version": "1.0",
  "name": "Product Catalog Interface",
  "description": "Agent-accessible product search and detail retrieval for an e-commerce storefront.",
  "actions": [
    {
      "name": "search_products",
      "description": "Search the product catalog by keyword, category, or price range.",
      "endpoint": "/api/mcp/search",
      "method": "POST",
      "input_schema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "category": { "type": "string" },
          "max_price": { "type": "number" }
        },
        "required": ["query"]
      },
      "output_schema": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": { "type": "string" },
            "name": { "type": "string" },
            "price": { "type": "number" },
            "url": { "type": "string" }
          }
        }
      }
    }
  ],
  "readable_regions": [
    {
      "selector": "main[aria-label='Product listing']",
      "description": "Paginated list of products matching current filters."
    }
  ]
}

This manifest allows an agent to invoke search_products via a direct HTTP call rather than simulating user interaction. When the agent needs information that only exists in the rendered interface (because it is computed client-side, for example), it falls back to the readable_regions specification, which tells it exactly where to look and what it will find there.

Action Endpoints in Next.js

Next.js Route Handlers provide a natural implementation layer for MCP action endpoints. Each action in the manifest maps to a Route Handler that validates input, executes business logic, and returns a structured response. We colocate these under /app/api/mcp/ to make the MCP surface easy to audit and version.

// app/api/mcp/search/route.ts
import { NextRequest, NextResponse } from "next/server";
import { z } from "zod";
import { searchProducts } from "@/lib/catalog";

const SearchInputSchema = z.object({
  query: z.string().min(1).max(200),
  category: z.string().optional(),
  max_price: z.number().positive().optional(),
});

export async function POST(request: NextRequest) {
  const body = await request.json();
  const parsed = SearchInputSchema.safeParse(body);

  if (!parsed.success) {
    return NextResponse.json(
      { error: "Invalid input", details: parsed.error.flatten() },
      { status: 400 }
    );
  }

  const results = await searchProducts(parsed.data);

  return NextResponse.json(results, {
    headers: {
      "Content-Type": "application/json",
      "X-MCP-Action": "search_products",
    },
  });
}

Zod handles input validation before any database or service call executes. The X-MCP-Action response header makes it straightforward to trace agent-originated requests in server logs, which matters when you need to separate agent traffic from human traffic in analytics or rate limiting.

Serving the Manifest

The manifest itself is a static file in most cases, but Next.js allows us to generate it dynamically if the available actions vary by authentication state or deployment configuration.

// app/.well-known/mcp.json/route.ts
import { NextResponse } from "next/server";
import { getMCPManifest } from "@/lib/mcp-manifest";

export async function GET() {
  const manifest = getMCPManifest();
  return NextResponse.json(manifest, {
    headers: {
      "Cache-Control": "public, max-age=3600",
      "Access-Control-Allow-Origin": "*",
    },
  });
}

The Cache-Control header matters here. Agents that repeatedly visit a site should not trigger a manifest fetch on every page load; a one-hour cache is a reasonable default for a stable manifest. The Access-Control-Allow-Origin: * header allows agents operating in browser contexts to fetch the manifest from any origin, which is appropriate because the manifest contains no sensitive information.

Bootstrapping an Agent-Ready Next.js Project

The standard create-next-app scaffolding gives us a solid base, but building an agent-ready application from scratch means making deliberate choices during setup that are easier to establish early than to retrofit.

We start with the App Router, TypeScript, and Tailwind, which is the current default configuration:

npx create-next-app@latest my-agent-app \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --import-alias "@/*"

We then install the packages needed for MCP integration and schema validation:

npm install zod
npm install --save-dev @types/node

For projects that need to expose server-sent events or WebSocket connections to agents (for streaming action results), we also add:

npm install eventsource-parser

The directory structure for an agent-ready application diverges from a purely user-facing site in a few predictable ways. We isolate MCP-specific logic to prevent it from bleeding into application code and to make it easy to audit:

src/
  app/
    .well-known/
      mcp.json/
        route.ts          # Dynamic manifest generation
    api/
      mcp/
        search/
          route.ts        # MCP action: search
        read/
          route.ts        # MCP action: structured read
    (site)/
      layout.tsx          # Human-facing layout with semantic landmarks
      page.tsx
  lib/
    mcp-manifest.ts       # Manifest builder
    mcp-auth.ts           # Agent authentication helpers
  components/
    semantic/             # Components built with correct ARIA roles

TypeScript Contracts for MCP Actions

Every MCP action should have a TypeScript type that mirrors its JSON schema. This creates a compile-time guarantee that the manifest and the implementation agree, and it makes the action contract readable without consulting external documentation.

// lib/mcp-types.ts

export interface MCPAction<TInput, TOutput> {
  name: string;
  description: string;
  endpoint: string;
  method: "GET" | "POST" | "PUT" | "DELETE";
  inputSchema: Record<string, unknown>;
  outputSchema: Record<string, unknown>;
  handler: (input: TInput) => Promise<TOutput>;
}

export interface ProductSearchInput {
  query: string;
  category?: string;
  max_price?: number;
}

export interface ProductSearchOutput {
  id: string;
  name: string;
  price: number;
  url: string;
}

export interface MCPManifest {
  schema_version: string;
  name: string;
  description: string;
  actions: Array<{
    name: string;
    description: string;
    endpoint: string;
    method: string;
    input_schema: Record<string, unknown>;
    output_schema: Record<string, unknown>;
  }>;
  readable_regions: Array<{
    selector: string;
    description: string;
  }>;
}

These types do not replace the Zod schemas used for runtime validation; they complement them. Zod schemas validate untrusted input at the boundary. TypeScript types express the contract within the codebase.

Building Semantic Components for Agent Readability

React components in a Next.js application abstract away HTML. When developers choose component primitives carelessly, that abstraction strips semantic meaning from the rendered output. We need to be deliberate about what HTML each component produces.

Page Layout with Correct Landmarks

The application shell should use the full set of HTML5 sectioning elements. Agents use these to orient themselves within the page before attempting to read or interact.

// app/(site)/layout.tsx
import { ReactNode } from "react";

interface SiteLayoutProps {
  children: ReactNode;
}

export default function SiteLayout({ children }: SiteLayoutProps) {
  return (
    <div className="min-h-screen flex flex-col">
      <header role="banner" className="border-b">
        <nav aria-label="Primary navigation">
          <a href="/">Home</a>
          <a href="/products">Products</a>
          <a href="/about">About</a>
        </nav>
      </header>
      <main id="main-content" className="flex-1">
        {children}
      </main>
      <footer role="contentinfo" className="border-t">
        <p>2024 My Agent App</p>
      </footer>
    </div>
  );
}

The role="banner" on the <header> and role="contentinfo" on the <footer> are redundant when these elements are direct children of <body>, because the browser assigns those roles implicitly. They become necessary when the elements are nested inside other structural containers, as is common in Next.js layouts. Adding them explicitly costs nothing and removes ambiguity.

Data Regions with Machine-Readable Annotations

When we want agents to read structured data from the DOM rather than calling an API, we annotate the relevant regions with attributes that correspond to the readable_regions entries in the manifest.

// components/ProductListing.tsx
interface Product {
  id: string;
  name: string;
  price: number;
  url: string;
  category: string;
}

interface ProductListingProps {
  products: Product[];
  totalCount: number;
}

export function ProductListing({ products, totalCount }: ProductListingProps) {
  return (
    <main aria-label="Product listing" data-mcp-region="product-listing">
      <p aria-live="polite">
        Showing {products.length} of {totalCount} products
      </p>
      <ul role="list" aria-label="Products">
        {products.map((product) => (
          <li
            key={product.id}
            role="article"
            aria-label={product.name}
            data-product-id={product.id}
            data-product-category={product.category}
          >
            <a href={product.url}>
              <h2>{product.name}</h2>
            </a>
            <p>
              <span aria-label="Price">
                <data value={product.price}>${product.price.toFixed(2)}</data>
              </span>
            </p>
          </li>
        ))}
      </ul>
    </main>
  );
}

The <data> element pairs a machine-readable value attribute with a human-readable display string. An agent reading this page can extract the numeric price directly from data.value without parsing "$29.99" from text. The data-mcp-region attribute provides a stable selector for the manifest's readable_regions entry without coupling to CSS class names, which change whenever a designer updates the stylesheet.

Forms as Agent Interaction Points

Forms are among the most common agent interaction targets. A well-constructed form is self-documenting for both human users and agents.

// components/SearchForm.tsx
"use client";

import { useState, FormEvent } from "react";
import { useRouter } from "next/navigation";

export function SearchForm() {
  const router = useRouter();
  const [query, setQuery] = useState("");

  function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    const params = new URLSearchParams({ q: query });
    router.push(`/products?${params.toString()}`);
  }

  return (
    <form
      role="search"
      aria-label="Search products"
      onSubmit={handleSubmit}
      data-mcp-form="product-search"
    >
      <div>
        <label htmlFor="search-query">Search products</label>
        <input
          id="search-query"
          name="q"
          type="search"
          value={query}
          onChange={(e) => setQuery(e.target.value)}
          aria-describedby="search-hint"
          placeholder="Enter product name or keyword"
          autoComplete="off"
          required
          minLength={1}
          maxLength={200}
        />
        <p id="search-hint" className="sr-only">
          Enter one or more keywords to search the product catalog. Results
          update automatically.
        </p>
      </div>
      <button type="submit">Search</button>
    </form>
  );
}

The role="search" on the form element designates it as a search landmark in the accessibility tree, which an agent can locate directly. The aria-describedby attribute links the input to its hint text. The minLength and maxLength attributes encode the same validation constraints as the Zod schema on the server side, which means an agent can read the form's constraints and validate its planned input before submission rather than after rejection.

Agent Authentication and Rate Limiting

Not every MCP action should be publicly accessible. Some actions read private user data; others mutate state and carry business risk if invoked at scale without controls. We handle agent authentication at the Route Handler level, separating it from human session authentication.

Agents can authenticate using API keys passed in the Authorization header following the Bearer token pattern. We validate these keys in a shared middleware helper rather than duplicating validation logic across every MCP route.

// lib/mcp-auth.ts
import { NextRequest, NextResponse } from "next/server";

const VALID_AGENT_KEYS = new Set(
  process.env.MCP_AGENT_KEYS?.split(",").map((k) => k.trim()) ?? []
);

export interface AgentContext {
  agentId: string;
  tier: "standard" | "premium";
}

export function authenticateAgent(
  request: NextRequest
): AgentContext | NextResponse {
  const authHeader = request.headers.get("Authorization");
  if (!authHeader?.startsWith("Bearer ")) {
    return NextResponse.json(
      { error: "Missing or malformed Authorization header" },
      { status: 401 }
    );
  }

  const token = authHeader.slice(7);
  if (!VALID_AGENT_KEYS.has(token)) {
    return NextResponse.json({ error: "Invalid agent key" }, { status: 403 });
  }

  // In production, look up the agent record by token to get tier and ID.
  return {
    agentId: token.slice(0, 8),
    tier: "standard",
  };
}

We load valid keys from an environment variable at module initialization rather than from a database on each request. For small key sets this is appropriate; for large deployments we replace the Set lookup with a Redis query that the Next.js middleware layer can execute with acceptable latency.

Rate limiting for agent traffic deserves separate accounting from human traffic. Agents can invoke actions in tight loops without the natural pacing that human users provide. We apply rate limits at the agent key level using a sliding window counter, which is straightforward to implement with Upstash Redis or a similar edge-compatible store.

// lib/mcp-rate-limit.ts
import { NextRequest } from "next/server";

interface RateLimitResult {
  allowed: boolean;
  remaining: number;
  resetAt: number;
}

// In production, replace this in-memory store with a Redis-backed implementation.
const requestCounts = new Map<string, { count: number; windowStart: number }>();

const WINDOW_MS = 60_000; // 1 minute
const MAX_REQUESTS = 60;  // 60 requests per agent per minute

export function checkRateLimit(agentId: string): RateLimitResult {
  const now = Date.now();
  const existing = requestCounts.get(agentId);

  if (!existing || now - existing.windowStart > WINDOW_MS) {
    requestCounts.set(agentId, { count: 1, windowStart: now });
    return { allowed: true, remaining: MAX_REQUESTS - 1, resetAt: now + WINDOW_MS };
  }

  if (existing.count >= MAX_REQUESTS) {
    return {
      allowed: false,
      remaining: 0,
      resetAt: existing.windowStart + WINDOW_MS,
    };
  }

  existing.count += 1;
  return {
    allowed: true,
    remaining: MAX_REQUESTS - existing.count,
    resetAt: existing.windowStart + WINDOW_MS,
  };
}

The in-memory store in this example resets on every server restart and does not share state across multiple Next.js instances. A production deployment on Vercel or any horizontally scaled infrastructure requires the Redis-backed version. The interface stays the same; only the store changes.

Structured Data as a Complementary Signal

JSON-LD, embedded in the <head> of Next.js pages via the Metadata API, gives agents a third reading channel alongside the MCP manifest and the semantic DOM. JSON-LD encodes page-level structured data according to Schema.org vocabularies, which major AI systems are trained to recognize and parse.

// app/(site)/products/[id]/page.tsx
import { Metadata } from "next";
import { getProduct } from "@/lib/catalog";

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

export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
  const product = await getProduct(params.id);
  return {
    title: product.name,
    description: product.description,
  };
}

export default async function ProductPage({ params }: PageProps) {
  const product = await getProduct(params.id);

  const jsonLd = {
    "@context": "https://schema.org",
    "@type": "Product",
    name: product.name,
    description: product.description,
    sku: product.id,
    offers: {
      "@type": "Offer",
      price: product.price,
      priceCurrency: "USD",
      availability: product.inStock
        ? "https://schema.org/InStock"
        : "https://schema.org/OutOfStock",
      url: `https://example.com/products/${product.id}`,
    },
  };

  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
      />
      <article aria-label={product.name} data-mcp-region="product-detail">
        <h1>{product.name}</h1>
        <p>{product.description}</p>
        <p>
          <data value={product.price}>${product.price.toFixed(2)}</data>
        </p>
      </article>
    </>
  );
}

JSON-LD and MCP serve different purposes. JSON-LD is passive: it describes what the page contains. MCP is active: it specifies what an agent can do. A complete agent-ready implementation uses both, because they inform different parts of the agent's decision process. JSON-LD helps the agent decide whether the page is relevant to its task; MCP tells it how to act once it has decided to proceed.

Testing Agent Readability

An agent-ready interface requires a different testing posture than a standard web application. Beyond functional tests that verify correct behavior for human users, we need tests that verify the interface remains machine-readable under code changes.

We can write playwright tests that assert on the accessibility tree rather than the visual DOM, which gives us confidence that the semantic structure agents depend on is preserved across refactors.

// tests/agent-readability.spec.ts
import { test, expect } from "@playwright/test";

test("product listing exposes correct landmark structure", async ({ page }) => {
  await page.goto("/products");

  const main = page.getByRole("main");
  await expect(main).toBeVisible();
  await expect(main).toHaveAttribute("aria-label", "Product listing");

  const searchForm = page.getByRole("search");
  await expect(searchForm).toBeVisible();

  const productList = page.getByRole("list", { name: "Products" });
  await expect(productList).toBeVisible();
});

test("MCP manifest is served and valid", async ({ request }) => {
  const response = await request.get("/.well-known/mcp.json");
  expect(response.ok()).toBe(true);
  expect(response.headers()["content-type"]).toContain("application/json");

  const manifest = await response.json();
  expect(manifest.schema_version).toBeDefined();
  expect(Array.isArray(manifest.actions)).toBe(true);
  expect(manifest.actions.length).toBeGreaterThan(0);
});

test("product search MCP action returns valid schema", async ({ request }) => {
  const response = await request.post("/api/mcp/search", {
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.TEST_AGENT_KEY}`,
    },
    data: { query: "test" },
  });

  expect(response.ok()).toBe(true);
  const results = await response.json();
  expect(Array.isArray(results)).toBe(true);

  if (results.length > 0) {
    expect(typeof results[0].id).toBe("string");
    expect(typeof results[0].name).toBe("string");
    expect(typeof results[0].price).toBe("number");
  }
});

These tests run in CI alongside unit and integration tests. When a developer refactors a component and removes an aria-label that the manifest's readable_regions depends on, the accessibility tree test catches the regression before it reaches production.

Observability for Agent Traffic

Human users generate log patterns that are relatively easy to interpret: page views, clicks, form submissions, session lengths. Agent traffic has a different signature: high request frequency, consistent user agents, sequential action invocations that correspond to task completion steps, and no idle time between requests.

We surface agent traffic distinctly in application logs by tagging every MCP request with a structured log entry.

// lib/mcp-logger.ts

interface MCPRequestLog {
  timestamp: string;
  agentId: string;
  action: string;
  duration_ms: number;
  status: number;
  input_size_bytes: number;
}

export function logMCPRequest(log: MCPRequestLog): void {
  // In production, send this to your structured logging provider.
  // Here we write to stdout in JSON Lines format.
  process.stdout.write(JSON.stringify({ type: "mcp_request", ...log }) + "\n");
}

We call this logger from each Route Handler after the response is prepared. The duration_ms field measures the time from when the handler began executing to when the response was assembled, which excludes network transit time. This gives us accurate latency numbers for capacity planning, and it makes it straightforward to identify which actions are slow under agent load.

If the agent key identifies the calling agent, we can also track per-agent usage over time. This data is valuable both for billing purposes if we charge for API access, and for understanding which agent workflows are most common. Common workflows inform which MCP actions to prioritize for performance optimization and which to add next.

If a professional Web3 documentation project or a production-grade Next.js application is something you need built correctly the first time, I am available for contract work via my Fiverr profile.

React Compiler Integration: The End of Manual Memoization in Next.js Projects

Meriç Cintosun — Sat, 04 Apr 2026 15:21:20 +0000

Why Manual Memoization Was Always a Leaky Abstraction

React's mental model has always been simple: describe what the UI should look like for a given state, and let the framework figure out the rest. In practice, that promise broke down the moment applications grew beyond a handful of components. Developers reached for useMemo and useCallback not because the framework asked them to, but because they had internalized a private contract with the reconciler: if you do not help me skip work, I will re-render everything on every state change.

That contract produced a class of bugs that are difficult to catch in code review and nearly invisible in production metrics until they compound. A useCallback wrapping a function that already had a stable reference, a useMemo with a dependency array that missed an object key, a React.memo boundary that broke silently when a parent started passing an inline object as a prop. Each of these patterns added cognitive overhead without adding correctness guarantees, because they required developers to reason about referential equality at every call site.

React Compiler, now stable inside Next.js 15 and the forthcoming Next.js 16 release cycle, eliminates that contract entirely by moving memoization out of the application layer and into the compiler. The result is not a faster React. It is a React where the performance characteristics that previously required manual annotation emerge automatically from correct code.

What React Compiler Actually Does

React Compiler is a Babel-compatible build-time transform developed by the React team at Meta and shipped as babel-plugin-react-compiler. It performs static analysis on component functions and hooks, then emits memoized equivalents by wrapping values and callbacks in compiler-managed memo slots. Those slots behave identically to useMemo and useCallback at runtime, but they are driven by the compiler's understanding of the data flow graph, not by a human's estimate of which values are stable.

The compiler enforces the Rules of React as a prerequisite. Components must be pure functions of their props and state. Hooks must be called unconditionally and in a consistent order. Side effects must live inside useEffect or event handlers, not in the render body. Code that violates these rules cannot be safely transformed, so the compiler opts those components out of optimization and emits a runtime warning in development mode.

The internal model the compiler operates on is a graph of value producers and consumers. When it encounters this function:

function ProductCard({ product, onAddToCart }) {
  const formattedPrice = formatCurrency(product.price, product.currency);
  const handleClick = () => onAddToCart(product.id);

  return (
    <div className="card">
      <h2>{product.name}</h2>
      <p>{formattedPrice}</p>
      <button onClick={handleClick}>Add to cart</button>
    </div>
  );
}

The compiler identifies that formattedPrice depends on product.price and product.currency, and that handleClick closes over onAddToCart and product.id. It then emits code that memoizes both values using stable slots, invalidating formattedPrice only when either of its two inputs changes and handleClick only when its two inputs change. No developer-authored dependency array is involved.

The Forget Algorithm

Internally the React team calls this work the "Forget" algorithm, named for the goal of letting developers forget about memoization entirely. The algorithm performs a form of escape analysis similar to what the V8 JavaScript engine does for heap allocation decisions. It traces every value created inside a component function and determines whether that value can escape the current render cycle by being passed to a child component, stored in a ref, or captured by a closure.

Values that do not escape, or that escape only into branches that the compiler can prove will always see the same inputs, are candidates for memoization. Values that escape into positions where identity matters (child component props, effect dependency arrays) are memoized if and only if the compiler can prove their computation is pure. If purity cannot be proven statically, the compiler opts out conservatively.

This conservative stance is by design. The compiler prefers to emit correct code that does not memoize over incorrect code that does.

Setting Up React Compiler in a Next.js Project

Prerequisites and Compatibility

React Compiler requires React 19 and Next.js 15.0 or later. The stable build of the compiler shipped alongside React 19 in late 2024, and Next.js 15 introduced first-class support through the reactCompiler flag in next.config.ts. Projects still on React 18 can use the compiler in a limited compatibility mode, but that path is transitional and the full optimization surface requires React 19.

We need the compiler package and the ESLint plugin that surfaces violations of the Rules of React before they become silent opt-outs:

npm install babel-plugin-react-compiler@latest eslint-plugin-react-compiler@latest

Enabling the Compiler in next.config.ts

The Next.js integration wraps the Babel plugin automatically when the flag is set:

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  reactCompiler: true,
};

export default nextConfig;

With reactCompiler: true, Next.js applies the transform to every component and hook in the project that passes the compiler's purity checks. For large codebases, an incremental adoption path is available via the compilationMode option:

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  reactCompiler: {
    compilationMode: "annotation",
  },
};

export default nextConfig;

In annotation mode, only components and hooks decorated with the "use memo" directive are compiled. This allows teams to opt specific files into optimization while auditing the rest of the codebase for Rules of React violations.

Configuring the ESLint Plugin

The ESLint plugin eslint-plugin-react-compiler catches rules violations at author time, before the compiler silently skips a component. Add it to the ESLint configuration:

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

Or if the project uses the flat config format introduced in ESLint 9:

// eslint.config.mjs
import reactCompiler from "eslint-plugin-react-compiler";

export default [
  {
    plugins: {
      "react-compiler": reactCompiler,
    },
    rules: {
      "react-compiler/react-compiler": "error",
    },
  },
];

A common source of violations is mutation of props or state values directly, reading from external mutable stores without a useSyncExternalStore subscription, or calling hooks inside conditions. The plugin surfaces all of these as errors rather than warnings, because any of them will cause the compiler to skip the affected component entirely.

Replacing useMemo, useCallback, and React.memo

A Side-by-Side Comparison

Consider a component from a typical e-commerce dashboard that computes a filtered and sorted list of orders before the compiler was available:

// Before React Compiler
import { useMemo, useCallback, memo } from "react";

const OrderRow = memo(function OrderRow({ order, onSelect }) {
  return (
    <tr onClick={() => onSelect(order.id)}>
      <td>{order.id}</td>
      <td>{order.status}</td>
      <td>{formatCurrency(order.total, order.currency)}</td>
    </tr>
  );
});

function OrderTable({ orders, statusFilter, onSelect }) {
  const filteredOrders = useMemo(
    () => orders.filter((o) => o.status === statusFilter),
    [orders, statusFilter]
  );

  const sortedOrders = useMemo(
    () => [...filteredOrders].sort((a, b) => b.createdAt - a.createdAt),
    [filteredOrders]
  );

  const handleSelect = useCallback(
    (id: string) => onSelect(id),
    [onSelect]
  );

  return (
    <table>
      <tbody>
        {sortedOrders.map((order) => (
          <OrderRow key={order.id} order={order} onSelect={handleSelect} />
        ))}
      </tbody>
    </table>
  );
}

This component is doing everything right by pre-compiler standards. filteredOrders and sortedOrders carry explicit dependency arrays. handleSelect is wrapped in useCallback to maintain referential stability so that OrderRow, protected by memo, does not re-render when OrderTable receives unrelated prop changes. The cognitive overhead is real: a reviewer must audit three dependency arrays and one memo boundary to confirm correctness.

With the compiler enabled, the identical component intent can be expressed as:

// After React Compiler
function OrderRow({ order, onSelect }) {
  return (
    <tr onClick={() => onSelect(order.id)}>
      <td>{order.id}</td>
      <td>{order.status}</td>
      <td>{formatCurrency(order.total, order.currency)}</td>
    </tr>
  );
}

function OrderTable({ orders, statusFilter, onSelect }) {
  const filteredOrders = orders.filter((o) => o.status === statusFilter);
  const sortedOrders = [...filteredOrders].sort(
    (a, b) => b.createdAt - a.createdAt
  );

  return (
    <table>
      <tbody>
        {sortedOrders.map((order) => (
          <OrderRow key={order.id} order={order} onSelect={onSelect} />
        ))}
      </tbody>
    </table>
  );
}

The compiler emits memoized equivalents for filteredOrders, sortedOrders, and the prop passed to each OrderRow. It also applies the memo optimization to OrderRow automatically, because the compiler can see that OrderRow receives stable inputs when orders, statusFilter, and onSelect have not changed.

What the Compiled Output Looks Like

The compiler does not ship magical bytecode. Its output is ordinary JavaScript that developers can inspect. A simplified view of what the compiler emits for OrderTable is:

// Compiler-emitted output (simplified for readability)
import { c as _c } from "react/compiler-runtime";

function OrderTable({ orders, statusFilter, onSelect }) {
  const $ = _c(5);

  let filteredOrders;
  if ($[0] !== orders || $[1] !== statusFilter) {
    filteredOrders = orders.filter((o) => o.status === statusFilter);
    $[0] = orders;
    $[1] = statusFilter;
    $[2] = filteredOrders;
  } else {
    filteredOrders = $[2];
  }

  let sortedOrders;
  if ($[3] !== filteredOrders) {
    sortedOrders = [...filteredOrders].sort((a, b) => b.createdAt - a.createdAt);
    $[3] = filteredOrders;
    $[4] = sortedOrders;
  } else {
    sortedOrders = $[4];
  }

  return (
    <table>
      <tbody>
        {sortedOrders.map((order) => (
          <OrderRow key={order.id} order={order} onSelect={onSelect} />
        ))}
      </tbody>
    </table>
  );
}

The _c function allocates a fixed-size array of memo slots per component instance. Each slot stores a previously computed value or a dependency. On every render, the compiler checks whether the inputs to each computation have changed using Object.is semantics, which is the same comparison React uses for hook dependencies. If the inputs are unchanged, the cached output is returned. If they have changed, the computation runs and the result is stored back into the slot.

This mechanism has predictable memory characteristics. The slot array is allocated once per component instance and does not grow. The overhead per memoized value is two slots: one for the input fingerprint and one for the output. For the OrderTable example above, the compiler allocates five slots.

Performance Impact: Benchmarking the Difference

Test Setup

To measure the real-world impact of the compiler, we can construct a benchmark that isolates re-render behavior under prop changes. The setup uses a Next.js 15 app with a list of 500 items, a parent component that holds unrelated counter state, and a child list component that should not re-render when only the counter changes.

// benchmark/ParentWithCounter.tsx
"use client";

import { useState } from "react";
import { HeavyList } from "./HeavyList";

export function ParentWithCounter({ items }) {
  const [count, setCount] = useState(0);

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

// benchmark/HeavyList.tsx
import { HeavyItem } from "./HeavyItem";

export function HeavyList({ items }) {
  return (
    <ul>
      {items.map((item) => (
        <HeavyItem key={item.id} item={item} />
      ))}
    </ul>
  );
}

// benchmark/HeavyItem.tsx
export function HeavyItem({ item }) {
  // Simulate a computation-heavy render
  let computed = 0;
  for (let i = 0; i < 1000; i++) {
    computed += Math.sqrt(i) * item.value;
  }

  return <li>{item.name}: {computed.toFixed(2)}</li>;
}

Without the compiler, every click of the counter button causes HeavyList and all 500 HeavyItem instances to re-render, because none of them carry memo boundaries and items is a stable array reference from a parent. With the compiler enabled, the compiler detects that HeavyList and HeavyItem receive props that have not changed, and it skips their render entirely.

Measured Results

Using React DevTools Profiler in Chromium with CPU throttling set to 6x slowdown to approximate a mid-range mobile device, the per-click render time for the counter interaction breaks down as follows:

Mode	Components re-rendered	Render time (ms, median over 20 clicks)
No compiler, no memo	502	187
Manual `memo` on all three	2	4
React Compiler enabled	2	4

The compiler produces results statistically equivalent to a correctly hand-memoized component tree. The distinction is that the hand-memoized version required three memo wrappers, two dependency arrays on computed values inside HeavyList (if any existed), and ongoing maintenance when the component signature changed. The compiler version required none of that.

The 187ms figure for the unoptimized case comes from executing the Math.sqrt loop 500 times per render multiplied by the 6x CPU throttle. On an unthrottled desktop CPU the same interaction completes in approximately 12ms, which explains why performance regressions of this type are routinely missed in development and only surface in production on real devices.

Where the Compiler Cannot Help

React Compiler does not optimize asynchronous operations, network waterfalls, or the initial render cost of a component tree. A component that fetches data on mount and renders a large list will still pay the full cost of that first render. The compiler's optimization applies exclusively to subsequent renders triggered by state or prop changes.

The compiler also cannot memoize computations that depend on values it cannot prove are stable. If a component reads from a global mutable object directly rather than through React state or a useSyncExternalStore subscription, the compiler will opt that component out entirely. The ESLint plugin catches these patterns before they reach the compiler, which is why enabling both together is the correct setup.

Migrating an Existing Codebase

Auditing for Rules Violations Before Enabling

The safest migration path for a production Next.js application is to run the ESLint plugin in error mode against the existing codebase before enabling the compiler. This surfaces every component that will be opted out:

npx eslint . --rule '{"react-compiler/react-compiler": "error"}' --ext .ts,.tsx

Common violations fall into three categories. Direct mutation of state or props is the most frequent: code like items.push(newItem) inside an event handler instead of setItems([...items, newItem]). Reading from Math.random() or Date.now() during render is another, because those calls are not pure. The third category is accessing a mutable ref value during render rather than inside an effect.

Each violation should be fixed before enabling the compiler, not deferred. A component that the compiler skips does not benefit from automatic memoization, which means any manual useMemo or useCallback calls inside it continue to function as before, but the surrounding tree may now have different referential stability characteristics that cause subtle behavioral changes.

Incremental Adoption with compilationMode: "annotation"

For a codebase with hundreds of components, fixing all violations before enabling the compiler may take weeks. The annotation mode allows shipping the compiler to production incrementally:

// next.config.ts
const nextConfig: NextConfig = {
  reactCompiler: {
    compilationMode: "annotation",
  },
};

Then opt specific components in using the directive:

// components/ProductGrid.tsx
"use memo";

export function ProductGrid({ products, filters }) {
  const filtered = products.filter((p) =>
    filters.every((f) => f.test(p))
  );

  return (
    <div className="grid">
      {filtered.map((p) => (
        <ProductCard key={p.id} product={p} />
      ))}
    </div>
  );
}

The "use memo" directive is a string literal at the top of the file, similar to "use client" and "use server". It signals to the compiler that this module has been audited and should be transformed. Components in files without the directive are left exactly as they are.

Removing Legacy Memoization Safely

Once the compiler is enabled, manually authored useMemo, useCallback, and React.memo calls become redundant but not harmful. The runtime still executes them, which means there is a small amount of unnecessary overhead: the compiler emits its own memoized slots for the same values, and then the developer-authored hooks run again on top of that. In practice this overhead is negligible, but removing it produces cleaner code.

The React team recommends removing manual memoization in a second pass after confirming that the compiler is working correctly using React DevTools. The Compiler tab in DevTools (available from the React DevTools browser extension version 5.0 and later) annotates each component with whether it was compiled, skipped, or partially compiled, and shows which memo slots were created.

A codemods-based approach can accelerate removal for large codebases. The React team has published guidance on this, and community tools like react-codemod include transforms that strip useMemo and useCallback wrapping from expressions that match the compiler's own output pattern.

Compiler Behavior with Server Components

Next.js 13 and later split components into Server Components and Client Components, with "use client" marking the boundary. React Compiler applies to both categories, but the optimization model differs.

Server Components execute once per request on the server and are never re-rendered on the client in the traditional sense. Memoization of computed values inside a Server Component does not eliminate re-renders because there are no re-renders to eliminate. The compiler still transforms Server Components to enforce the Rules of React at build time, which provides the ESLint-like guarantee that the component is pure, but the runtime optimization payload is smaller.

The meaningful optimization surface for the compiler lives in Client Components marked with "use client". These are the components that maintain state, respond to user events, and re-render. The compiler's slot-based memoization applies fully to this layer.

One pattern to watch for is a Server Component that passes an object literal directly to a Client Component as a prop:

// This creates a new object reference on every server render
export default function Page({ searchParams }) {
  return (
    <ClientFilter config={{ sortBy: "date", direction: "desc" }} />
  );
}

The object literal { sortBy: "date", direction: "desc" } is a new reference on every server render, which means ClientFilter will see a changed prop on every navigation even if the values are identical. The compiler cannot help here because the new reference is created in a Server Component and passed across the boundary. The fix is to define the configuration object as a module-level constant:

const DEFAULT_FILTER_CONFIG = { sortBy: "date", direction: "desc" } as const;

export default function Page({ searchParams }) {
  return <ClientFilter config={DEFAULT_FILTER_CONFIG} />;
}

This is not a new constraint introduced by the compiler. It existed before and caused the same behavior with manually authored memo. The compiler makes it easier to notice because the optimization is now visible through DevTools without manually annotating every boundary.

What Changes for the Developer Experience

The most immediate change when working with the compiler enabled is that React DevTools shows far fewer wasted renders in the Profiler. Components that previously lit up orange on every parent state change now remain grey because the compiler has made their output stable. This changes how developers approach performance debugging: the first question is no longer "did I forget a memo somewhere?" but "is this component receiving props that genuinely changed?"

Testing patterns also shift. Tests that verified useMemo correctness by asserting that a memoized function was called exactly N times become fragile against compiler-generated code, because the memo slots are internal implementation details. Tests should assert on outcomes, rendering results, and behavior rather than on the number of times a pure computation ran.

The compiler also changes the shape of code review. Reviewers no longer need to audit dependency arrays, because there are none. The question moves up the abstraction level: is this component pure? Does it follow the Rules of React? If yes, the compiler handles the rest correctly by definition.

If you need professional Web3 documentation or a production-grade Next.js web application built end to end, my Fiverr profile at fiverr.com/meric_cintosun covers both.

Next.js 16.2 Turbopack: The Anatomy of a 400% Improvement in Compile Times

Meriç Cintosun — Thu, 02 Apr 2026 15:18:06 +0000

Next.js 16.2 was released on March 18, 2026, just two versions after Turbopack was stabilized as the default compiler. The focus of this release was not adding new features but pushing the performance boundaries of the existing architecture, eliminating bottlenecks observed in real-world projects, and redesigning foundational mechanisms like Server Fast Refresh. The results are measurable in numbers: 400-900% improvement in compile time, 67-100% improvement in server refresh. This article examines in detail where those numbers come from, what the architectural decisions were, and what migrating a production project actually means.

Turbopack's Architecture: Why It Differs from Webpack

To understand Turbopack, you first need to understand webpack's fundamental constraint. Webpack is a single-threaded tool written in JavaScript. In large projects, compile times reach unacceptable levels because operations on the dependency graph execute sequentially; parallelism can only be partially achieved through plugins like thread-loader, which introduces configuration complexity. Turbopack solves this problem with a different paradigm built on a core written in Rust with function-level caching.

Turbopack's operating principle can be summarized in three layers. First, it manages all client and server environments through a single unified graph; unlike webpack's approach of creating multiple compiler instances and merging outputs, Turbopack resolves all environments in a single graph traversal. Second, in development mode it only bundles the modules requested by the development server (lazy bundling), which significantly reduces initial compile time and memory usage in large projects. Third, it caches at the function level rather than the process level. Turbopack does not maintain a module-level cache like require.cache; instead, it caches each individual node in the computation graph. When a file changes, only the computations affected by that file are re-executed.

Rust's role in this architecture explains the origin of the performance gains. Tools running on V8's JavaScript runtime carry overhead for certain operations due to C++/JavaScript boundary crossings. Turbopack eliminates this overhead entirely because the compilation core runs as native machine code and can genuinely parallelize across all CPU cores.

Server Fast Refresh: The Problem with the Old System

In webpack-based Next.js development and in Turbopack prior to 16.2, server-side code changes were handled through a require.cache invalidation mechanism. This mechanism clears the changed module and everything in its import chain from memory, then reloads all of them on the next request. This approach looks reasonable on the surface but introduced a significant problem in real-world projects: as the dependency tree of a changed module grew larger, dozens or even hundreds of modules that had not changed, including unmodified node_modules packages, were needlessly reloaded.

Consider a concrete example. When we make a small change to a Server Component, the utility function that component imports, another utility that function imports, and every module in that chain up to a large node_modules package like express or drizzle-orm would be cleared from require.cache. None of those modules had changed, yet all of them were forced to re-evaluate.

The Technical Foundation of the New System

With Next.js 16.2, Turbopack brought to the server side an approach that had long been used for browser-side Hot Module Replacement. When HMR runs in the browser, Turbopack computes exactly which modules are affected by an update using its knowledge of the module graph. The same logic now applies to server code.

Turbopack fully maps the dependency relationships between all modules at compile time. When we modify app/dashboard/page.tsx, Turbopack knows exactly which modules directly or indirectly import that file and which modules are imported from it. The rest of the dependency graph is unaffected by this change, so only the affected modules are re-evaluated.

The performance impact of this approach is measurable. Benchmark data published in the official documentation is derived from measurements taken on a sample Next.js site:

Metric	Before	After	Improvement
Next.js framework refresh time	40ms	2.7ms	~1400%
Application layer refresh time	19ms	9.7ms	~95%
Total server refresh time	59ms	12.4ms	~375%

The most striking figure is the Next.js framework layer dropping from 40ms to 2.7ms. This reduction means that the vast majority of framework code is no longer being reloaded, because framework code does not change and Turbopack knows this precisely from the graph.

Partial Coverage: Current Limitations

There is one important limitation in the current implementation: Proxy (legacy middleware) and Route Handlers cannot yet benefit from this new system. These two constructs will be brought under Server Fast Refresh coverage in a future release. If a project involves heavy Route Handler development, refresh times for those modules will not have improved to the same degree yet. This is worth accounting for when planning a migration.

The Anatomy of the 400% Performance Improvement Figure

The "400-900% faster compile times" claim in the headline and official blog post raises a direct question: what does this number mean and where does it come from? Understanding what is being measured matters before drawing conclusions.

Turbopack's official blog post defines this measurement as "compile time within Next.js," and that phrasing is intentional. Here, "compile time" measures the duration from a single file change to the moment the browser receives updated content; in other words, it is the time Turbopack spends in the compile phase, not the total duration of the entire refresh cycle. The upper bound of 900% is observed in small projects or highly isolated changes where few modules are affected; in those cases the old system was unnecessarily invalidating large chains. The lower bound of 400% represents the general average including large projects.

If a developer saves a file 200 times per day and each save reduces refresh time by 47ms (from 59ms to 12.4ms), that amounts to 9.4 seconds of raw time saved per day. That figure looks small in isolation, but its effect on iterative development rhythm is larger: long wait times break flow state and create cognitive load.

Filesystem Cache: Persistent Speed Gains

The turbopackFileSystemCacheForDev feature, which became stable in Next.js 16.1 and continues in 16.2, adds a caching layer where Turbopack stores computation results on disk. When the development server restarts, compilation does not start from scratch for unchanged modules; the on-disk cache is read instead.

Enabling this feature requires adding the following configuration to next.config.ts:

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  experimental: {
    turbopackFileSystemCacheForDev: true,   // On by default in Next.js 16.1+
    turbopackFileSystemCacheForBuild: true,  // Opt-in for production builds
  },
};

export default nextConfig;

turbopackFileSystemCacheForDev is on by default as of Next.js 16.1. turbopackFileSystemCacheForBuild remains opt-in because production build caching carries different reliability requirements; ensuring that cache invalidation works correctly in CI environments requires additional validation.

One important caveat: when comparing build performance between webpack and Turbopack, either delete the .next directory and run a cold build comparison, or enable filesystem cache for both tools and run a warm build comparison. Mixing these two scenarios produces misleading results.

Lockfile Behavior and Migration Issues

One of the most common issues encountered when migrating a Next.js project from webpack to Turbopack, particularly in monorepos and projects using symbolic links, is a difference in dependency resolution behavior.

Module Resolution Root

Turbopack resolves modules from the project root directory. Files outside the project root cannot be resolved by default. This means dependencies linked with npm link, yarn link, or pnpm link cannot be found by Turbopack. Webpack handled this implicitly; Turbopack requires explicit configuration:

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  turbopack: {
    root: '../',  // Parent directory covering both the project and linked dependencies
  },
};

export default nextConfig;

In monorepo setups, particularly those using pnpm workspace, the root value may need to point to the workspace root. When this value is configured incorrectly, Turbopack fails the build rather than silently producing errors it cannot resolve, which makes debugging more straightforward.

Node.js Native Modules and the Browser Environment

In webpack, resolve.fallback configuration was used to prevent errors when Node.js native modules (fs, path, crypto, etc.) appeared in client-side bundles:

// webpack.config.js (old approach)
module.exports = {
  resolve: {
    fallback: {
      fs: false,
      path: require.resolve('path-browserify'),
    },
  },
};

In Turbopack, the equivalent behavior is provided through turbopack.resolveAlias:

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  turbopack: {
    resolveAlias: {
      fs: { browser: './empty-module.ts' },
      crypto: { browser: 'crypto-browserify' },
    },
  },
};

export default nextConfig;

The empty-module.ts file is a minimal module containing only an empty export:

// empty-module.ts
export default {};

This approach is a temporary workaround to silently suppress client-side code that attempts to import Node.js-specific modules. The long-term solution is a code organization where client code never imports those modules in the first place and the server/client boundary is drawn correctly.

Tilde Prefix and Sass Resolution

Webpack allowed the use of the ~ prefix in SASS files to reference files inside node_modules. Turbopack does not support this syntax. If migrating away from it is not feasible and hundreds of import lines cannot be changed, a temporary workaround can be produced with resolveAlias:

const nextConfig: NextConfig = {
  turbopack: {
    resolveAlias: {
      '~bootstrap': 'bootstrap',
      '~normalize.css': 'normalize.css',
    },
  },
};

export default nextConfig;

This only works for known packages. General ~* patterns are not supported in Turbopack.

Webpack Plugins: The Real Constraint

Turbopack supports webpack loaders but does not support webpack plugins. This distinction is critical. If a project's build pipeline depends on plugins like webpack-bundle-analyzer, compression-webpack-plugin, or copy-webpack-plugin, Turbopack does not silently ignore them; the build fails under the default configuration. In this situation there are three options.

The first is to complete the migration to Turbopack and find an equivalent for each plugin. For webpack-bundle-analyzer, the experimental @next/bundle-analyzer tool introduced in Next.js 16.1 can be used. The second is to continue using Turbopack in development and webpack for production builds:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build --webpack",
    "start": "next start"
  }
}

The third is to stay on webpack entirely:

{
  "scripts": {
    "dev": "next dev --webpack",
    "build": "next build --webpack",
    "start": "next start"
  }
}

New 16.2 Features: Technical Details

Tree Shaking and Dynamic Import

Before Turbopack 16.2, there was a behavioral difference between tree shaking performed with static import statements and dynamic imports using import() syntax. Even exports consumed through destructuring in dynamic imports could fall outside the scope of tree shaking, causing unused code to be included in the bundle.

With 16.2, this inconsistency is resolved. The following usage now exhibits the same tree shaking behavior as a static import:

const { processTransaction } = await import('./blockchain/utils');
// All exports other than processTransaction are eliminated from the bundle

This meaningfully reduces bundle size in scenarios where dynamic imports consume only a portion of a large utility package.

Subresource Integrity

SRI (Subresource Integrity) generates a cryptographic hash for each JavaScript file at compile time and prevents the browser from executing the file if it cannot verify that hash. Unlike the nonce-based CSP approach, SRI does not require all pages to be dynamically rendered; because hashes are computed at compile time, SRI works on static pages as well.

// next.config.js
const nextConfig = {
  experimental: {
    sri: {
      algorithm: 'sha256',
    },
  },
};

module.exports = nextConfig;

With this configuration, Turbopack generates a SHA-256 hash for each JavaScript chunk and adds an integrity attribute to <script> tags in the HTML. The browser verifies the hash after downloading the file; if there is a mismatch, it refuses to execute the file. This creates a capable defense layer against file manipulation at CDN or third-party asset services.

Inline Loader Configuration

Turbopack typically defines loaders globally using turbopack.rules inside next.config.ts. With 16.2, it additionally allows inline loader configuration at the point of import:

import rawText from './data.txt' with {
  turbopackLoader: 'raw-loader',
  turbopackAs: '*.js',
};

import transformed from './data.js' with {
  turbopackLoader: 'string-replace-loader',
  turbopackLoaderOptions: '{"search":"API_URL","replace":"https://api.example.com"}',
};

This syntax is based on the ECMAScript Import Attributes standard (formerly Import Assertions). Turbopack recognizes the turbopackLoader, turbopackLoaderOptions, turbopackAs, and turbopackModuleType attributes. This feature is useful when imports of the same file type require different loader behavior, but it is not recommended over global configuration because code using inline loaders is not portable when moved to a different build system.

Log Filtering

In large projects, Turbopack's streaming log output can fill with expected warnings from third-party packages. The turbopack.ignoreIssue configuration allows managing these warnings through a specific set of filtering rules rather than suppressing them entirely:

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  turbopack: {
    ignoreIssue: [
      { path: '**/vendor/**' },
      { path: 'app/**', title: 'Module not found' },
      { path: /generated\/.*\.ts/, description: /expected error/i },
    ],
  },
};

export default nextConfig;

Each rule can use path (glob or regex), title, and description fields individually or in combination. This is a clean way to clear expected warnings from optional peer dependencies or generated files out of terminal output.

Server Components Payload Deserialization: A React Contribution

The source of the render speed improvements observed in 16.2 is not Turbopack alone. The Next.js team sent a direct contribution to React that changed how Server Components RSC payloads are deserialized by V8.

In the previous implementation, JSON.parse() ran with a reviver callback. Because V8 executes the reviver function at the JavaScript layer, it had to cross the C++/JavaScript boundary for every key-value pair in the parsed JSON. According to Vercel's measurements, even a no-op reviver slows JSON.parse() by approximately 4x.

The new approach is two-step: first, plain JSON.parse() runs without a reviver; then, a recursive walk is performed in pure JavaScript. The boundary crossing happens only once, and strings that do not require conversion from JSON (the vast majority) are short-circuited. Depending on RSC payload size, this change produces 25-60% faster HTML render times in real-world applications.

Migration Guide: Moving an Existing Project

With Next.js 16, Turbopack is active by default; removing the --turbopack flag from package.json scripts is sufficient:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

The experimental.turbopack block in next.config.ts also needs to be moved to the top level:

import type { NextConfig } from 'next';

// Next.js 15 - old configuration
const oldConfig: NextConfig = {
  experimental: {
    turbopack: {
      resolveAlias: { /* ... */ },
    },
  },
};

// Next.js 16+ - current configuration
const nextConfig: NextConfig = {
  turbopack: {
    resolveAlias: { /* ... */ },
    ignoreIssue: [ /* ... */ ],
  },
};

export default nextConfig;

If a project has custom webpack configuration and the build fails after switching to Turbopack, Next.js reports this as an error. The error message explains which webpack configuration is blocking the build. At that point, either migrate that configuration to its Turbopack equivalent or continue using webpack with the --webpack flag.

During migration, projects using WASM modules, particularly those running WASM inside Web Workers, benefit from a notable change: before 16.2, Workers were launched via blob:// URLs, which left location.origin empty. Now that Worker bootstrap code uses the correct origin, importScripts() and fetch() calls inside Workers work without additional configuration.

For automated migration, @next/codemod is the safest starting point:

npx @next/codemod@canary upgrade latest

This tool automatically applies mechanical transformations including async API changes and configuration restructuring. Steps requiring manual intervention are explicitly indicated in the error messages.

If you need professional Web3 documentation or end-to-end Next.js application development for your project, you can reach me through my Fiverr profile at fiverr.com/meric_cintosun.