Nextjs Ssr

This skill builds on test-proxy-recorder/proxy-setup. Read it first for proxy CLI setup, playwright.config.ts, and fixtures before applying Next.js patterns.

test-proxy-recorder — Next.js SSR

The proxy correlates SSR fetches to the right test session via the x-test-rcrd-id header. Playwright sets it on every browser request (via playwrightProxy.before()), including the navigation that triggers SSR — so the id is already in the server render scope (next/headers). The one thing left to do is attach it to outgoing server-side fetches. A middleware (setNextProxyHeaders) only exposes the id; it does not tag fetches, so one of the helpers below is required (the middleware itself is optional — see the end of Setup).

All helpers from test-proxy-recorder/nextjs are no-ops in production (NODE_ENV=production) unless TEST_PROXY_RECORDER_ENABLED=true is set.

Record against a production build (next build && next start), not next dev. The dev server could reset a global fetch patch on subsequent requests (vercel/next.js#47596, fixed in newer versions); build+start has no such issue and is faster/less flaky.

Setup

Recommended — registerProxyFetch() in the root layout (any runtime)

One line tags every server-side fetch (Server Components, Route Handlers, Node and Edge runtimes). Call it at the top level of the root layout — not instrumentation.ts (see Common Mistakes).

// app/layout.tsx
import { registerProxyFetch } from 'test-proxy-recorder/nextjs';

registerProxyFetch(); // no-op in production unless TEST_PROXY_RECORDER_ENABLED=true

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

axios SSR calls — registerProxyAxios(instance)

For apps whose server-side requests go through axios, register each server-side instance once. It adds a request interceptor that stamps the id, and never touches global fetch, so it's immune to the dev-mode patch caveat.

import { registerProxyAxios } from 'test-proxy-recorder/nextjs';

registerProxyAxios(axiosForServer);
registerProxyAxios(axiosWithAuth);

Replaces the hand-rolled interceptor + React.cache() helper (still documented below for reference). No-op in production / in the browser; idempotent per instance; never overwrites a caller-set id.

Per-call alternative — createHeadersWithRecordingId()

Patch-free and works under next dev too (reads the id from headers() directly). Use it when you'd rather not patch global fetch, or for one fetch:

import { headers } from 'next/headers';
import { createHeadersWithRecordingId } from 'test-proxy-recorder/nextjs';

const res = await fetch('http://localhost:8100/api/data', {
  cache: 'no-store',
  headers: createHeadersWithRecordingId(await headers(), {
    'Content-Type': 'application/json',
  }),
});

Optional — middleware (setNextProxyHeaders)

A proxy.ts (Next.js 16+, exported proxy) / middleware.ts (15 and earlier, exported middleware) calling setNextProxyHeaders makes the id available via next/headers, but does not tag outgoing fetches — so it is not required when you use a helper above. Reach for it only if you already own a middleware for other reasons (auth, etc.); still pair it with a helper above to do the actual tagging.

// proxy.ts (Next.js 16+) — exported `proxy`; use middleware.ts / `middleware` on 15 and earlier
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { setNextProxyHeaders } from 'test-proxy-recorder/nextjs';

export function proxy(request: NextRequest) {
  const response = NextResponse.next();
  setNextProxyHeaders(request, response);
  return response;
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

Core Patterns

Inject recording ID into native fetch (Route Handler / Server Component)

// app/api/data/route.ts
import { headers } from 'next/headers';
import { createHeadersWithRecordingId } from 'test-proxy-recorder/nextjs';

export async function GET(request: Request) {
  const res = await fetch('http://localhost:8100/api/data', {
    cache: 'no-store',
    headers: createHeadersWithRecordingId(await headers(), {
      'Content-Type': 'application/json',
    }),
  });
  return Response.json(await res.json());
}

createHeadersWithRecordingId merges the session ID into your headers object. It is a no-op when the session ID is absent (browser-only tests, or production).

registerProxyFetch — detail

Set up in Setup above. It reads the id via next/headers, so it only acts inside a request scope and leaves build-time/non-request fetches untouched. It tags every server-side fetch (the id is inert anywhere but the proxy and never affects replay matching, and during tests everything you record routes through the proxy anyway). Works on Node and Edge runtimes. Call it from the root layout, not instrumentation.ts (see Common Mistakes). Source: apps/example-nextjs-edge/app/layout.tsx

Testing a cached / ISR route

Don't disable caching for tests — record/replay works with ISR, but only one design is deterministic. The rule: replaying an SSR fetch needs the page to run that fetch at request time, so cache it with fetch-level next.revalidate + next.tags (a hard purge on revalidateTag), not unstable_cache (which is stale-while-revalidate and flakes). Before the replay navigation, revalidateTag to drop the cache left from the record phase; one navigation is then enough — no polling. During tests the patched fetch reads headers(), so the page renders dynamically and runs the fetch; in production it's still static ISR. Gate the revalidate route behind a secret (privileged, DoS-able) supplied via Playwright extraHTTPHeaders.

Full rationale, the flaky approaches to avoid, and the auth pattern are in references/caching-and-isr.md. Source: apps/example-nextjs16/app/isr/page.tsx, app/api/revalidate/route.ts, e2e/isr.spec.ts

Memoize header lookup with React cache() (App Router)

Avoid calling headers() in every individual fetch helper. Wrap it once with React.cache() so it is called once per request and shared across all server-side imports.

// lib/recording-id.ts
import { cache } from 'react';
import { RECORDING_ID_HEADER } from 'test-proxy-recorder/nextjs';

export const getServerRecordingId = cache(async () => {
  try {
    const { headers } = await import('next/headers');
    const headersList = await headers();
    return headersList.get(RECORDING_ID_HEADER.toLowerCase()) || undefined;
  } catch {
    return undefined; // Not in a Server Component request context
  }
});

Axios interceptor for SSR requests (manual)

Prefer registerProxyAxios(instance) (Setup) — it does exactly this. Use the manual interceptor below only if you need custom logic around it. It also shows the React.cache() helper (above) in context.

// lib/axios-server.ts
import axios from 'axios';
import { RECORDING_ID_HEADER } from 'test-proxy-recorder/nextjs';
import { getServerRecordingId } from './recording-id';

const isTestMode = process.env.NODE_ENV !== 'production';

export const axiosForServer = axios.create();

axiosForServer.interceptors.request.use(async (config) => {
  if (typeof window === 'undefined' && isTestMode) {
    try {
      const recordingId = await getServerRecordingId();
      if (recordingId) {
        config.headers.set(RECORDING_ID_HEADER, recordingId);
      }
    } catch {
      // Not in a Server Component context — silently skip
    }
  }
  return config;
});

Extract recording ID manually

import { getRecordingId, RECORDING_ID_HEADER } from 'test-proxy-recorder/nextjs';
import { headers } from 'next/headers';
import type { NextRequest } from 'next/server';

// From headers() in a Server Component
const fromServerComponent = getRecordingId(await headers());

// From NextRequest in middleware, forwarded by hand
export function middleware(request: NextRequest) {
  const recordingId = getRecordingId(request.headers);
  const requestHeaders = new Headers(request.headers);
  if (recordingId) {
    requestHeaders.set(RECORDING_ID_HEADER, recordingId);
  }
}

Common Mistakes