A-2 — The Full Request Lifecycle and Edge Infrastructure

---

Streaming Response Anatomy

When a Next.js page uses Suspense and has async Server Components, the response is streamed using HTTP chunked transfer encoding. This is worth understanding mechanically because it's what makes Next.js pages feel fast even when data is slow.

The server sends the HTTP headers immediately (including Transfer-Encoding: chunked). Then it sends HTML in chunks as content becomes available:

--- Initial flush (immediate) ---
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: text/html
 
<!DOCTYPE html>
<html>
<head>...</head>
<body>
  <nav>...</nav>              ← layout renders immediately
  <h1>Product Title</h1>     ← static product data renders immediately
  <!--$?--><template id="B:0"></template><!--/$-->  ← Suspense placeholder
</body>

--- Second chunk (when ProductReviews resolves, ~300ms later) ---
<div hidden id="S:0">
  <ul class="reviews">...</ul>   ← real reviews content
</div>
<script>
  $RC("B:0", "S:0")   ← React's built-in function swaps placeholder with content
</script>

The browser renders the first chunk immediately — the user sees the page layout and product title while reviews are still loading. When the second chunk arrives, React's $RC function (from the streaming runtime) moves the content into the Suspense placeholder without a full re-render.

This is fundamentally different from a client-side skeleton loader. The skeleton loader delivers an empty page, then makes a separate fetch for data, then renders. Streaming delivers real server-rendered content progressively — the first paint already has meaningful content.

---

ISR Revalidation Internals

ISR (Incremental Static Regeneration) uses a stale-while-revalidate model. Understanding exactly how the timing works prevents a common mistake: thinking revalidation happens on a schedule.

ISR does not run on a schedule. It runs on request, with a cooldown.

Timeline for a page with revalidate: 60:

t=0    First request: page renders, result cached. Timestamp recorded.
t=30   Request: cache age = 30s < 60s. Serve cached version. No revalidation.
t=61   Request: cache age = 61s > 60s. Serve cached version (stale). Background revalidation starts.
t=61   Background: page re-renders, new result stored, timestamp updated.
t=62   Request: new cache hit. Fresh content served.

The user at t=61 gets the stale page — there is no way around this in ISR. The stale serve is intentional: users get a response immediately without waiting for revalidation. The background rerender only affects the next user.

Tag-based ISR changes the trigger: instead of time-based, the revalidation fires when you call revalidateTag(). The next request after the tag invalidation re-renders and re-caches. Same stale-first model, but the staleness is bounded by your mutation cadence rather than a fixed TTL.

---

The instrumentation.ts Hook

instrumentation.ts (at the project root) exports a register() function that Next.js calls once when the server starts — before the first request is handled. It's the correct place for:

• OpenTelemetry provider setup
• Sentry initialisation
• Database connection pool warm-up
• Custom APM agent registration

// instrumentation.ts
 
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    // Only runs in Node.js runtime, not edge runtime
    const { NodeSDK } = await import('@opentelemetry/sdk-node');
    const { getNodeAutoInstrumentations } = await import('@opentelemetry/auto-instrumentations-node');
 
    const sdk = new NodeSDK({
      traceExporter: /* your exporter */,
      instrumentations: [getNodeAutoInstrumentations()],
    });
 
    sdk.start();
  }
 
  if (process.env.NEXT_RUNTIME === 'edge') {
    // Edge-specific initialisation
  }
}

The NEXT_RUNTIME environment variable tells you which runtime is executing: 'nodejs' for the main server, 'edge' for Middleware and edge Route Handlers. Use it to guard runtime-specific code.

instrumentation.ts is not Middleware. Middleware runs on every request. register() runs once at startup. Don't confuse them.

Enable it (required in Next.js 14, automatic in 15):

// next.config.ts
const config: NextConfig = {
  experimental: {
    instrumentationHook: true, // Required in Next.js 14, automatic in 15
  },
};

---

instrumentation-client.js — The Browser Mirror

instrumentation-client.js (or .ts) is the client-side equivalent: it runs once in the browser when the Next.js application boots, before any page component mounts.

// instrumentation-client.ts
 
export function register() {
  // Analytics initialisation — runs once on browser boot
  if (typeof window !== 'undefined') {
    import('@segment/analytics-next').then(({ AnalyticsBrowser }) => {
      const analytics = AnalyticsBrowser.load({ writeKey: process.env.NEXT_PUBLIC_SEGMENT_KEY! });
      window.__analytics = analytics;
    });
  }
}
 
// Runs on every client-side navigation (the SPA page view)
export function onRouteChange(url: string, { previousUrl }: { previousUrl: string }) {
  window.__analytics?.page({ path: url, referrer: previousUrl });
}

onRouteChange fires on every App Router client-side navigation — this is how you track page views in a Next.js SPA without useEffect-based tracking in every page component.

The two exports together replace the previous pattern of putting analytics initialisation in _app.tsx (Pages Router) or in a Client Component that wraps the root layout.

---

Edge vs Node.js Runtime for Route Handlers

Route Handlers run in the Node.js runtime by default. You can opt individual handlers into the edge runtime:

// app/api/fast-check/route.ts
export const runtime = 'edge';
 
export async function GET(request: Request) {
  // Runs in a V8 isolate — no Node.js APIs, near-zero cold start
  const country = request.headers.get('x-vercel-ip-country') ?? 'unknown';
  return Response.json({ country });
}

Edge runtime advantages:

• Near-zero cold start (V8 isolate, not a full Node.js process)
• Runs at CDN edge globally — geographically close to users
• Ideal for simple, fast responses: geo-detection, auth checks, feature flag evaluations

Edge runtime limitations:

• No Node.js APIs (fs, crypto, native modules)
• No Prisma (uses Node.js internals)
• No bcrypt, no most Node.js-based libraries
• 1MB bundle size limit
• Neon's HTTP driver and Upstash Redis work at the edge; most other databases don't

The decision: default to Node.js runtime. Move to edge only when the handler is simple enough to work without Node.js APIs and you need the latency benefit.

---

Where We Go From Here

A-3 goes deep into the caching architecture internals — the mechanics of the tag registry, cache stampede and how to prevent it, the use cache directive's static analysis, custom cache handlers for distributed deployments. With A-1's understanding of Flight and A-2's understanding of the infrastructure, A-3 explains how data moves through the system and stays fresh.

---