Optimization Next.js App Router · Contentful Personalization · contentful/skills · Skills Docs

Optimization Next.js App Router · Contentful Personalization · contentful/skills · Skills Docs

pnpm add @contentful/optimization-nextjs

Import	Use
`@contentful/optimization-nextjs/app-router`	Create the bound root, entry component, page tracker, and request handler
`@contentful/optimization-nextjs/client`	Browser hooks and the client `OptimizedEntry` with per-entry live-update controls
`@contentful/optimization-nextjs/server`	Advanced manual server composition only
`@contentful/optimization-nextjs/api-schemas`	Contentful Optimization type guards

// lib/optimization.ts
import { createNextjsAppRouterOptimization } from '@contentful/optimization-nextjs/app-router';

export const CONSENT_COOKIE = 'app-personalization-consent';

export const { proxy, NextAppAutoPageTracker, OptimizationRoot, OptimizedEntry } = createNextjsAppRouterOptimization({
  clientId: process.env.NEXT_PUBLIC_OPTIMIZATION_CLIENT_ID ?? '',
  environment: process.env.NEXT_PUBLIC_OPTIMIZATION_ENVIRONMENT ?? 'main',
  locale: 'en-US',
  defaults: { consent: false, persistenceConsent: false },
  server: {
    enabled: true,
    consent: ({ cookies }) =>
      cookies.get(CONSENT_COOKIE)?.value === 'granted' ? { events: true, persistence: true } : false,
  },
  app: { name: 'my-next-app', version: '1.0.0' },
});

// app/layout.tsx
import { CONSENT_COOKIE, NextAppAutoPageTracker, OptimizationRoot } from '@/lib/optimization';
import { cookies } from 'next/headers';
import { Suspense, type ReactNode } from 'react';

export default async function RootLayout({ children }: { children: ReactNode }) {
  const cookieStore = await cookies();
  const serverOwnsInitialPageEvent = cookieStore.get(CONSENT_COOKIE)?.value === 'granted';

  return (
    <html lang="en">
      <body>
        <OptimizationRoot>
          <Suspense>
            <NextAppAutoPageTracker initialPageEvent={serverOwnsInitialPageEvent ? 'skip' : 'emit'} />
          </Suspense>
          {children}
        </OptimizationRoot>
      </body>
    </html>
  );
}

<NextAppAutoPageTracker
  initialPageEvent="skip"
  getPagePayload={({ context: { pathname } }) => ({
    properties: { routeGroup: pathname.startsWith('/account') ? 'account' : 'public' },
  })}
/>

import { OptimizedEntry } from '@/lib/optimization';

export function EntryRenderer({ entry }: { entry: ContentEntry }) {
  return (
    <OptimizedEntry baselineEntry={entry}>
      {(resolved, { getMergeTagValue }) => (
        <EntryComponent entry={resolved as ContentEntry} getMergeTagValue={getMergeTagValue} />
      )}
    </OptimizedEntry>
  );
}

'use client';

import { OptimizedEntry } from '@contentful/optimization-nextjs/client';

export function LiveHero({ entry }: { entry: HeroEntry }) {
  return (
    <OptimizedEntry baselineEntry={entry} liveUpdates>
      {(resolved) => <Hero entry={resolved as HeroEntry} />}
    </OptimizedEntry>
  );
}

Symptom	Check
Bound root throws about the handler	Use `proxy.ts` + `proxy` on Next.js 16 or `middleware.ts` + `middleware` on Next.js 15; verify the matcher
Entry remains baseline	Check consent, audience match, one concrete CDA locale, include depth, and published optimization links
Variant flashes back after hydration	Render the same baseline/component path in both runtimes; hand managed entries to the browser
Live entry does not change after identity or reset	Enable factory or per-entry live updates
Duplicate or missing initial page event	Align `initialPageEvent` with the actual server event owner
Personalized HTML is stale across visitors	Remove shared output caching or vary it on the complete personalization context