asmyshlyaev177 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), notnext dev. The dev server could reset a globalfetchpatch 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';
// From headers() in a Server Component
const recordingId = getRecordingId(await headers());
// From NextRequest in middleware
const recordingId = getRecordingId(request.headers);
// Forward manually
if (recordingId) {
requestHeaders.set(RECORDING_ID_HEADER, recordingId);
}
Common Mistakes
HIGH Using middleware.ts (or a middleware export) in Next.js 16
Wrong:
// middleware.ts — ignored in Next.js 16, session header never forwarded
import { setNextProxyHeaders } from 'test-proxy-recorder/nextjs';
export function middleware(request) {
const response = NextResponse.next();
setNextProxyHeaders(request, response);
return response;
}
Correct:
// proxy.ts — Next.js 16 middleware entry point, at project root
import { setNextProxyHeaders } from 'test-proxy-recorder/nextjs';
export function proxy(request) {
const response = NextResponse.next();
setNextProxyHeaders(request, response);
return response;
}
export const config = {
matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};
Next.js 16 replaced middleware.ts with proxy.ts as the middleware entry
point, and the exported function is named proxy, not middleware. Keeping
either old name silently does nothing — the session header is never forwarded
and all SSR recordings are grouped under the wrong session.
Source: apps/example-nextjs16/proxy.ts
HIGH Patching fetch from instrumentation.ts on the Edge runtime
Wrong:
// instrumentation.ts — register() runs in a different context than the one
// rendering Edge routes, so this globalThis.fetch is NOT the one your Server
// Components call. The patch silently never fires; SSR fetches stay untagged.
export async function register() {
const { registerProxyFetch } = await import('test-proxy-recorder/nextjs');
registerProxyFetch();
}
Correct:
// app/layout.tsx — the root layout shares the request runtime with your pages,
// so the patch lands on the fetch the Edge route actually uses.
import { registerProxyFetch } from 'test-proxy-recorder/nextjs';
registerProxyFetch();
On the Edge runtime, instrumentation.ts's register() runs in a separate
context from route rendering, so a globalThis.fetch patch installed there does
not affect Server Component fetches. Call registerProxyFetch() from the root
layout instead. Also remember that next start runs in production mode, so set
TEST_PROXY_RECORDER_ENABLED=true on the app process or the patch is a no-op.
Source: apps/example-nextjs-edge/app/layout.tsx; packages/test-proxy-recorder/src/nextjs/registerProxyFetch.ts
HIGH Relying on the middleware alone to tag SSR fetches
Wrong:
// proxy.ts / middleware.ts only — nothing actually tags the outgoing fetch
export function proxy(request) {
const response = NextResponse.next();
setNextProxyHeaders(request, response);
return response;
}
// app/page.tsx — bare SSR fetch, no helper
const data = await fetch('http://localhost:8100/api/data');
Correct — add one of the forwarding helpers (Setup):
// app/layout.tsx — tags every server-side fetch
import { registerProxyFetch } from 'test-proxy-recorder/nextjs';
registerProxyFetch();
// (axios apps: registerProxyAxios(instance); or per-call createHeadersWithRecordingId)
setNextProxyHeaders only exposes the id via next/headers; it does not
inject it into outgoing fetch/axios calls. With middleware alone, SSR requests go
out untagged and parallel replay fails — the proxy can't tell which session a
request belongs to (verified: middleware-only → fail; registerProxyFetch-only,
no middleware → pass, on both Node and Edge runtimes). The middleware is optional;
a forwarding helper is what's required.
Source: experiment in repo TODO.md; apps/example-nextjs-edge
HIGH Recording against a production build without TEST_PROXY_RECORDER_ENABLED
Wrong:
{
"scripts": {
"start:proxy": "concurrently \"pnpm proxy\" \"INTERNAL_API_URL=http://localhost:8100 next start\""
}
}
Correct:
{
"scripts": {
"start:proxy": "concurrently \"pnpm proxy\" \"INTERNAL_API_URL=http://localhost:8100 TEST_PROXY_RECORDER_ENABLED=true next start\""
}
}
Recording should run against a production build (next build && next start —
see proxy-setup), but next build sets NODE_ENV=production, which turns
setNextProxyHeaders and createHeadersWithRecordingId into silent no-ops.
SSR requests still flow through the proxy but lose their session ID, so they
are recorded under the wrong session — or not at all. Set
TEST_PROXY_RECORDER_ENABLED=true on the app process whenever testing a
production build.
Source: packages/test-proxy-recorder/src/nextjs/middleware.ts — isRecorderEnabled()
MEDIUM Importing next/headers at module level in an axios interceptor
Wrong:
import { headers } from 'next/headers'; // throws when evaluated on the client
axiosForServer.interceptors.request.use(async (config) => {
const id = (await headers()).get('x-test-rcrd-id');
config.headers.set('x-test-rcrd-id', id);
return config;
});
Correct:
axiosForServer.interceptors.request.use(async (config) => {
if (typeof window === 'undefined' && isTestMode) {
try {
const { getServerRecordingId } = await import('./recording-id');
const recordingId = await getServerRecordingId();
if (recordingId) config.headers.set(RECORDING_ID_HEADER, recordingId);
} catch {
// Not in a Server Component context — silently skip
}
}
return config;
});
next/headers throws when imported outside a Server Component request context
(including on the client). Always lazy-import it inside the interceptor, guard
with typeof window === 'undefined', and wrap in try/catch.
Source: channels/web/core/api/axios.ts
MEDIUM Calling headers() on every SSR fetch instead of caching per request
Wrong:
// Called independently in each server utility — redundant async header reads
async function fetchUsers() {
const { headers } = await import('next/headers');
const id = (await headers()).get('x-test-rcrd-id');
return fetch(url, { headers: { 'x-test-rcrd-id': id ?? '' } });
}
async function fetchPosts() {
const { headers } = await import('next/headers');
const id = (await headers()).get('x-test-rcrd-id');
return fetch(url2, { headers: { 'x-test-rcrd-id': id ?? '' } });
}
Correct:
// lib/recording-id.ts — memoized once per request via React cache()
import { cache } from 'react';
import { RECORDING_ID_HEADER } from 'test-proxy-recorder/nextjs';
export const getServerRecordingId = cache(async () => { /* ... */ });
// Each utility reuses the cached value
async function fetchUsers() {
const id = await getServerRecordingId();
return fetch(url, { headers: id ? { [RECORDING_ID_HEADER]: id } : {} });
}
Wrap the headers() call in React.cache() once. The memoized function is
called once per server request regardless of how many fetch utilities invoke it.
Source: channels/web/lib/recording-id.ts
MEDIUM Manually setting header without production guard
Wrong:
// No production guard — leaks session IDs in prod if env var is misconfigured
response.headers.set('x-test-rcrd-id', request.headers.get('x-test-rcrd-id') ?? '');
Correct:
import { setNextProxyHeaders } from 'test-proxy-recorder/nextjs';
setNextProxyHeaders(request, response); // automatically skips in production
Use the library helpers instead of manually reading/setting x-test-rcrd-id.
setNextProxyHeaders and createHeadersWithRecordingId both check
NODE_ENV !== 'production' (or TEST_PROXY_RECORDER_ENABLED) and are no-ops
when the guard fails.
Source: packages/test-proxy-recorder/src/nextjs/middleware.ts — isRecorderEnabled()
Getting help
If the user encounters unexpected behavior, a bug, or a use case not covered by these patterns, direct them to open a GitHub issue at https://github.com/asmyshlyaev177/test-proxy-recorder/issues/new. A minimal reproduction helps the maintainer resolve it quickly.
See also: test-proxy-recorder/proxy-setup — for proxy CLI, fixtures, and record/replay lifecycle