Contentful Personalization & Analytics

Next.js SDK Pages Router Reference Implementation

Reference implementation demonstrating @contentful/optimization-nextjs in a Next.js Pages Router application. Pages call getServerSideOptimizationProps() from getServerSideProps, pass the returned Optimization state through pageProps, and mount the bound Pages Router root and route tracker once in pages/_app.tsx.

The implementation binds OptimizationRoot, OptimizedEntry, and NextPagesAutoPageTracker once in @/lib/optimization with createNextjsPagesRouterOptimization(). Browser runtime imports use Next.js SDK package subpaths. The package root is not imported:

• @contentful/optimization-nextjs/pages-router in @/lib/optimization for the bound component factory and route tracker
• @contentful/optimization-nextjs/pages-router/server in @/lib/optimization-server for getServerSideProps state handoff
• @contentful/optimization-nextjs/client for browser hooks and providers
• @contentful/optimization-nextjs/api-schemas in components that need SDK schema guards

What this demonstrates

Use this implementation when you need a Pages Router example where getServerSideProps fetches Contentful entries, prepares Optimization state, and lets the browser SDK continue from that state after hydration. It demonstrates:

• App-local bound components from createNextjsPagesRouterOptimization()
• Server state handoff from getServerSideOptimizationProps() through pageProps
• Pages Router route tracking with NextPagesAutoPageTracker
• Browser-side entry resolution with the app-local OptimizedEntry
• Live re-resolution after consent, identify, reset, and client-side route changes
• Preview panel attachment behind PUBLIC_OPTIMIZATION_ENABLE_PREVIEW_PANEL

CDA locale handling

The implementation defines one locale at appConfig.locale, passes it to the Next.js SDK server helper, uses it for event context, and passes it directly to Contentful CDA fetches. Do not use contentful.js withAllLocales or raw CDA locale=*; SDK entry resolution expects direct single-locale fields such as fields.nt_experiences and fields.nt_variants.

Route strategy

Use getServerSideProps for pages that need server-personalized first paint. It fetches entries, calls the Pages Router Optimization helper, and returns both through props. pages/_app.tsx passes pageProps.contentfulOptimization.clientDefaults and serverOptimizationState to the bound OptimizationRoot and uses initialPageEvent from the same object to avoid duplicate consented initial page events.

Prerequisites

• Node.js >= 20.19.0 (24.15.0 recommended to match .nvmrc)
• pnpm

Setup

Run these commands from the monorepo root:

pnpm install
pnpm build:pkgs
pnpm implementation:run -- nextjs-sdk_pages-router implementation:install
test -f implementations/nextjs-sdk_pages-router/.env || cp implementations/nextjs-sdk_pages-router/.env.example implementations/nextjs-sdk_pages-router/.env
Copy

The .env.example values are mock-safe defaults for the shared local mock API. Provide live Contentful and Optimization values only when testing against real services.

Running locally

Run these commands from the monorepo root:

pnpm implementation:run -- nextjs-sdk_pages-router dev
pnpm implementation:run -- nextjs-sdk_pages-router build
pnpm implementation:run -- nextjs-sdk_pages-router typecheck
pnpm implementation:run -- nextjs-sdk_pages-router lint
Copy

The development server runs on http://localhost:3001.

For production-style local serving with PM2-managed mock and app processes:

pnpm implementation:run -- nextjs-sdk_pages-router serve
pnpm implementation:run -- nextjs-sdk_pages-router serve:stop
Copy

Running E2E tests

Run the full E2E setup and test suite from the monorepo root:

pnpm setup:e2e:nextjs-sdk_pages-router
pnpm test:e2e:nextjs-sdk_pages-router
Copy

The E2E suite reuses the shared lib/e2e-web browser scenarios for CSR, hydration, and SSR first-paint behavior under the Pages Router configuration.

Use Playwright UI or codegen when needed:

pnpm implementation:run -- nextjs-sdk_pages-router test:e2e:ui
pnpm implementation:run -- nextjs-sdk_pages-router test:e2e:codegen
Copy

Related

• Next.js SDK App Router - App Router reference implementation using bound Server and Client Component exports
• React Web SDK reference implementation - Browser-side React integration using the React Web SDK
• @contentful/optimization-nextjs - Next.js SDK package
• Mocks package - Shared mock API server and fixtures