A/B Tests and Personalization at the Edge

Pricing page, two layouts, 50/50 split. The naive implementation assigns the bucket in a Client Component with useState(() => Math.random() < 0.5). Three things go wrong: the server's first paint shows variant A and hydration snaps it to B (a visible flash plus a hydration warning), the bucket can change on every mount, and analytics logs two exposures for one user. An experiment bucket must be assigned once, on the server, before the first byte of HTML exists — which is exactly what middleware lets you do.

// proxy.ts (middleware.ts on Next.js ≤ 15)
import { NextResponse, type NextRequest } from 'next/server'

const COOKIE = 'ab-pricing-v1'
const PERCENT_B = 50

export function proxy(request: NextRequest) {
  const res = NextResponse.next()
  let variant = request.cookies.get(COOKIE)?.value

  if (variant !== 'a' && variant !== 'b') {
    const roll = crypto.getRandomValues(new Uint8Array(1))[0]   // 0–255, edge-safe Web Crypto
    variant = roll < Math.floor((PERCENT_B / 100) * 256) ? 'b' : 'a'
    res.cookies.set(COOKIE, variant, {
      path: '/',
      maxAge: 60 * 60 * 24 * 30,   // 30 days: long enough to survive the whole funnel
      sameSite: 'lax',
    })
  }
  return res
}

Why each choice matters:

• The cookie makes the bucket durable. Serverless instances are disposable — memory is wiped on every cold start, and a request in Frankfurt must agree with one in Virginia. A value in a Map or a module-level variable is not an assignment; a cookie on the request is. crypto.getRandomValues comes from Web Crypto, which the edge runtime provides (see Edge vs Node Runtimes), so no Node-only PRNG sneaks in.
• Version the cookie name. When you redesign the experiment, ab-pricing-v1 → ab-pricing-v2 resets every bucket cleanly instead of inheriting stale assignments.
• Weight with a threshold, not with repeated rolls. One roll per assignment; roll < 128 gives 50%, roll < 26 gives ~10%. Rolling until a condition is met biases nothing but wastes nothing either — the point is the bucket is written down, not recomputed.

The alternative is deterministic bucketing: hash a stable identifier instead of rolling. hash(userId) % 100 < 50 reproduces the same bucket on every device for a logged-in user and needs no cookie at all:

Production experiments usually combine them: hash for authenticated users, cookie for everyone else, with the cookie winning on the request so a pre-login assignment carries into the session.

Two details finish the job. Validate what you read back: a tampered or stale cookie ('c', an empty string, an old experiment's value) must fall through to a fresh roll rather than be trusted — display-only experiments can tolerate a user editing document.cookie, but anything that drives a discount or an entitlement must be re-derived on the server from a verified identity, never from a cookie the client owns. sameSite: 'lax' keeps the cookie off cross-site POSTs without breaking top-level navigation, and unless a client-side script must read the bucket, leave httpOnly on and log exposures server-side instead — a bucket readable by any injected script is a bucket an attacker can corrupt. And the assignment is only half the mechanism: something downstream must render from that value. That handoff happens through headers, which is the next chapter.

The bucket exists in middleware. The page that renders it is a Server Component in app/pricing/page.tsx. They run in different phases of the same request, so you need a channel between them — and the single most common mistake is using the wrong direction of headers.

NextResponse.next({ request: { headers } }) sets request headers that flow upstream into your render. response.headers.set(...) sets headers that flow downstream to the browser. They are not interchangeable, and using the second when you meant the first silently produces a page that reads null.

// proxy.ts — forward the decision into the render
const requestHeaders = new Headers(request.headers)
requestHeaders.set('x-ab-variant', variant)
requestHeaders.set('x-ab-exp', 'pricing-v1')

const res = NextResponse.next({ request: { headers: requestHeaders } })
res.headers.set('x-ab-variant', variant)   // response header: visible to the browser and to CDN logs
return res

The Server Component then reads it with headers() from next/headers:

// app/pricing/page.tsx
import { headers } from 'next/headers'
import { AnnualTable } from './annual-table'
import { MonthlyTable } from './monthly-table'

export default async function PricingPage() {
  const variant = (await headers()).get('x-ab-variant')   // async: sync access was removed in Next.js 16
  return variant === 'b' ? <AnnualTable /> : <MonthlyTable />
}

Three properties of this mechanism are worth internalizing:

1. Reading headers() opts the route into request-time rendering. The page can no longer be served from a purely static render — the value differs per request. That is inherent to personalization; just do not accidentally read headers on a route that must stay static, or you have traded cache hits for a variant nobody varies.
2. Client Components cannot call headers(). The server parent reads the value and passes it as a prop, or the client reads the cookie you already set. Server is the source of truth; the cookie is the durable copy.
3. NextRequest and NextResponse do different jobs. NextRequest.headers is what the client sent (plus what you added on the previous hop); NextResponse is what you are about to send — res.cookies.set() writes Set-Cookie for the browser, while the request option writes into the headers the router and your pages will see.

One question that settles interviewers: does the RSC payload request get the same variant as the document request? It does, because middleware runs for both — the document load and every subsequent <Link> navigation re-enter your function, read the cookie written on the first response, and forward the identical header. The HTML, the RSC payload, and the client cache therefore agree without any coordination code.

Known sharp edges, all documented:

• Do not stuff payloads into headers. Oversized headers earn 431 Request Header Fields Too Large from the proxy or CDN — hash or reference the value, never inline JSON blobs.
• Internal RSC headers are stripped. During RSC requests Next.js removes rsc, next-router-state-tree, and next-router-prefetch from request.headers so the HTML request and the RSC request cannot be handled differently by accident — do not branch on them. NextResponse.rewrite() re-propagates what it needs automatically.
• Set an observability header. x-ab-variant as a response header means a curl -I, a support screenshot, or a CDN log line shows which variant served — the cheapest way to debug "user X saw the wrong pricing".

For diagnostics beyond headers, event.waitUntil(fetch('/api/exposures', ...)) records the exposure without delaying the response, and it keeps the count on the same request that rendered the variant — so an exposure log and a page view can never disagree.

The decision now reaches the render on every matched request. What remains is what this does to everything around the render: caches, crawlers, and prefetch traffic.

Varying a response before it renders is powerful in three directions — geography, request headers, and cookies — and each one quietly changes who can cache the result.

export function proxy(request: NextRequest) {
  const country =
    request.headers.get('x-vercel-ip-country') ??      // Vercel
    request.headers.get('cf-ipcountry') ??             // Cloudflare
    'US'
  const lang = request.headers.get('accept-language')?.slice(0, 2) ?? 'en'

  const requestHeaders = new Headers(request.headers)
  requestHeaders.set('x-country', country)
  requestHeaders.set('x-lang', lang)
  return NextResponse.next({ request: { headers: requestHeaders } })
}

(Platform-agnostic note: on Vercel the value also arrives as request.geo.country. Reading platform headers keeps the same code portable — one more reason shared middleware sticks to Web APIs.)

Decide what varies before deciding how, because geography usually wants one of two shapes. Same URL, different content — currency symbols, legal copy, availability — is a header decision: forward x-country and let the render pick, keeping one canonical URL and one cache entry per bounded variant. Different URL per locale — /de/preise — is a routing decision, and the redirect belongs in next.config.js for a static mapping or in middleware when the target depends on accept-language negotiation (Redirects and Rewrites covers why a 307/308 versus a rewrite changes what search engines index). Mixing the two — rewriting internally while also redirecting — is how teams end up with two indexed URLs for one page.

Before you vary everything, understand the cost model:

1. Cache fragmentation is the real bill. A CDN caches by URL plus the headers a response declares in Vary. Set Vary: Cookie and effectively every distinct cookie value becomes its own cache entry — hit rate collapses toward zero. The discipline: bound the number of variants. Two to five experiment buckets are cacheable; a per-user variant is not. If a response must vary per user, it belongs in dynamic rendering behind middleware, not in a shared cache — and you should say so out loud rather than discovering it in the CDN bill.

2. Prefetch traffic doubles your work. <Link> prefetches fire requests with next-router-prefetch and purpose: prefetch headers. Personalizing them assigns buckets nobody will see and multiplies cache keys. The documented matcher shape skips them:

export const config = {
  matcher: [{
    source: '/((?!api|_next/static|_next/image|favicon.ico).*)',
    missing: [
      { type: 'header', key: 'next-router-prefetch' },
      { type: 'header', key: 'purpose', value: 'prefetch' },
    ],
  }],
}

3. Crawlers are just another client — with consequences. A bot with no cookie gets a random bucket, so Googlebot may index variant A while your users see B. For experiments that change pricing tables or headings, that is a cloaking risk and an SEO headache; keep experiments cosmetic, or make the assignment deterministic for known crawlers, and always keep canonical/OG metadata identical across variants.

4. One exposure, logged once, on the request that rendered it. Client-side analytics re-fire on hydration, SPA navigation, and double-mounted effects. Logging experiment, variant, country server-side via event.waitUntil ties the number to the render you actually served — the same principle as forwarding the variant header: the server knows, so make the server say it.

Verification is three commands, not a dashboard. curl -I twice without a cookie and confirm both responses carry Set-Cookie with the same bucket on the second request; replay with -H 'Cookie: ab-pricing-v1=b' and confirm the markup matches variant B; and use unstable_doesProxyMatch({ config, nextConfig, url }) from next/experimental/testing/server to assert the matcher keeps static assets and prefetches out of the experiment.

The same file that personalizes a page can also decide whether a request deserves an answer at all — counting requests per client before any work happens, in Throttling Abuse at the Edge.