> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://contentful.com/developers/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/developers/docs/_mcp/server. # Integrate the Optimization Next.js SDK in a Next.js App Router app > Use this guide to add Contentful personalization to a Next.js App Router site you already have. ## Overview Use this guide to add Contentful personalization to a Next.js App Router site you already have. By the end of the quick start, one piece of content will be personalized per visitor in the server-rendered HTML — no flash of default content, while your app keeps ownership of fetching and rendering. **New to personalization?** Here is the whole idea in four points: * In Contentful you author **variants** of an entry and attach them to an **experience** — a rule that decides which visitors see which variant. * When a page is requested, Contentful's **Experience API** looks at the current visitor and picks the variant for each experience. Swapping a fetched entry for its picked variant is called **resolving** the entry. * Your app hands a Contentful entry to the SDK at the point where that entry becomes output. The SDK gives back the selected variant, or the original entry when no variant applies—the **baseline fallback**. You can fetch the entry yourself or give the SDK your Contentful client and an entry ID; either way, the client stays yours. * You render the returned entry with the same application components you already use. That is enough to start. The guide introduces policy and optional capabilities at the point you need them. You will get there in two milestones: * **Milestone 1 — personalized first paint (the quick start below).** A visitor sees their variant in the server HTML. This is complete and shippable on its own. * **Milestone 2 — browser takeover (opt-in, later).** Content re-personalizes live when consent, identity, or profile changes, without a page reload. See [Browser takeover and live updates](#browser-takeover-and-live-updates). This guide uses `@contentful/optimization-nextjs`. The `/app-router` factory gives you app-local components that do the right thing in both Server and Client Components. Your app keeps ownership of Contentful fetching, consent policy, identity, routing, caching, and rendering. If your app uses the Pages Router, use the [Next.js Pages Router guide](/personalization/optimization-sdk/integrate-the-optimization-sdk-in-a-nextjs-pages-router-app/) instead. ## Quick start Most App Router + Contentful sites share one shape: you fetch a **page** entry and render its content through your own components. This quick start assumes that shape. In the snippets that change an existing file, lines prefixed with `+` are what you add and the rest is a typical app for context — match the additions to your own file rather than pasting the whole block. If your app is shaped differently, the change is the same wherever an entry becomes a component; see [Personalizing first paint on the server](#personalizing-first-paint-on-the-server). It proves one result: **one section renders its personalized variant in the server HTML.** It assumes your app may personalize on startup. If personalization must wait for consent, keep this structure and add the [Consent, identity, profile, and reset](#consent-identity-profile-and-reset) step before you ship. 1. Install the adapter package. **Copy this:** ```sh pnpm add @contentful/optimization-nextjs ``` 2. Add the browser-visible Optimization values to `.env.local`. Copy the client id and environment from your Contentful Optimization setup; `main` is the usual environment unless your setup uses another one. These values are not delivery tokens or secrets. **Adapt this to your use case:** ```dotenv NEXT_PUBLIC_OPTIMIZATION_CLIENT_ID=replace-with-your-client-id NEXT_PUBLIC_OPTIMIZATION_ENVIRONMENT=main ``` 3. Create one module that binds the SDK to your config. You do this once and import from it everywhere — the resulting components are *bound* because they carry your config. Use the same environment-variable convention your app already uses for Contentful. The snippets import it as `@/src/lib/optimization`, which assumes the file is at `src/lib/optimization.ts` and your `tsconfig` maps `@/*` to the project root — adjust the specifier to match your own `paths` (for example `@/lib/optimization` if your alias points at a top-level `lib/`). **Adapt this to your use case:** replace the placeholder values and the import path; the config keys are explained in [How the SDK fits your app](#how-the-sdk-fits-your-app). ```ts // src/lib/optimization.ts import { createNextjsAppRouterOptimization } from '@contentful/optimization-nextjs/app-router' export const APP_LOCALE = 'en-US' export const { proxy, NextAppAutoPageTracker, OptimizationRoot, OptimizedEntry } = createNextjsAppRouterOptimization({ clientId: process.env.NEXT_PUBLIC_OPTIMIZATION_CLIENT_ID ?? '', environment: process.env.NEXT_PUBLIC_OPTIMIZATION_ENVIRONMENT ?? 'main', locale: APP_LOCALE, // consent: allowed to personalize and send events for this visitor. // persistenceConsent: allowed to store a profile-id cookie so results stay consistent. defaults: { consent: true, persistenceConsent: true }, server: { enabled: true, // resolve variants on the server, for first paint consent: { events: true, persistence: true }, }, app: { name: 'my-next-app', version: '1.0.0' }, // contentful: { client }, // opt-in: enables the entryId managed-fetch path }) ``` 4. Add the request handler so the SDK runs before your pages render. Next.js executes this file on every matching request; the SDK's `proxy` reads the visitor's cookies, asks the Experience API who they are, and stores that identity (an anonymous **profile** id) in the `ctfl-opt-aid` cookie so the same visitor gets consistent variants next time. You are only mounting it — not writing that logic. Next.js is version-specific about both the filename and the export name: Next.js 16 loads a `proxy` export from **`proxy.ts`**; Next.js 15 loads a `middleware` export from **`middleware.ts`**. Get either wrong and the handler silently never runs — and because `server.enabled` is `true`, `OptimizationRoot` then throws instead of falling back to baseline. See [Request context and the profile cookie](#request-context-and-the-profile-cookie). **Copy this:** Next.js 16. ```ts // proxy.ts — at your Next.js app root export { proxy } from './src/lib/optimization' export const config = { matcher: ['/((?!_next/static|_next/image|favicon.ico|api).*)'], } ``` **Copy this:** Next.js 15 uses the same handler, aliased to the `middleware` export that Next.js 15 looks for. ```ts // middleware.ts — at your Next.js app root export { proxy as middleware } from './src/lib/optimization' export const config = { matcher: ['/((?!_next/static|_next/image|favicon.ico|api).*)'], } ``` 5. Wrap your layout in `OptimizationRoot`, and put the page tracker inside it. **Keep everything your layout already renders** — header, footer, providers, fonts, styles. You are adding a wrapper, not replacing the file. Put the root around everything inside `` (chrome included) so header, footer, or announcement content can be personalized later too. **Adapt this to your use case:** the `+` lines are the additions; the rest is a typical layout for context. ```tsx // app/layout.tsx +import { NextAppAutoPageTracker, OptimizationRoot } from '../../../../src/lib/optimization' +import { Suspense } from 'react' export default async function RootLayout({ children }: { children: React.ReactNode }) { const settings = await getSiteSettings() // your existing code stays return ( + + {/* Suspense is required: the tracker reads useSearchParams(), which Next.js + only allows inside a Suspense boundary. */} + + {/* "skip": the server already reported this page view — don't report it twice. */} + +
{children}