Contentful Personalization & Analytics

Web SDK React Adapter Reference Implementation

Reference implementation demonstrating @contentful/optimization-web usage in a React web application with a local adapter layer.

What this demonstrates

This implementation provides a thin React adapter layer over @contentful/optimization-web, demonstrating:

• OptimizationProvider context for SDK state management
• React hooks for SDK state subscriptions
• Optimization resolution and variant rendering
• Rich Text rendering via @contentful/rich-text-react-renderer
• Analytics event tracking
• Live updates behavior
• SPA navigation tracking with React Router v7
• Offline queue/recovery handling

The live updates section demonstrates the same parity scenarios directly in-page (default, forced on, and locked), while keeping the main entry rendering flow customer-oriented.

CDA locale handling

The adapter defines one APP_LOCALE, passes it as the Web SDK top-level locale, and passes it directly to Contentful CDA getEntry() calls. Do not use contentful.js withAllLocales or raw CDA locale=* for entries passed to the adapter resolver; SDK entry resolution expects direct single-locale fields such as fields.nt_experiences and fields.nt_variants. See Locale handling in the Optimization SDK Suite for the broader locale model and Entry personalization and variant resolution for the entry contract.

Prerequisites

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

Setup

From the repository root:

1. Install pnpm packages:

pnpm install
Copy

2. Build SDK packages, which is required for local development:

pnpm build:pkgs
Copy

3. Install implementation dependencies:

pnpm implementation:run -- web-sdk_react implementation:install
Copy

4. Create the local .env file if it does not already exist:

test -f implementations/web-sdk_react/.env || cp implementations/web-sdk_react/.env.example implementations/web-sdk_react/.env
Copy

Running locally

From the repository root:

1. Start the development server:

pnpm implementation:run -- web-sdk_react dev
Copy

2. Build for production:

pnpm implementation:run -- web-sdk_react build
Copy

3. Preview the production build:

pnpm implementation:run -- web-sdk_react preview
Copy

4. Run type checking:

pnpm implementation:run -- web-sdk_react typecheck
Copy

The equivalent implementation-directory commands are:

pnpm dev
pnpm build
pnpm preview
pnpm typecheck
Copy

Running E2E tests

1. Run the full E2E setup and test suite from the repository root:

pnpm setup:e2e:web-sdk_react
pnpm test:e2e:web-sdk_react
Copy

2. Or run the shared Playwright flow step by step:

pnpm implementation:run -- web-sdk_react serve
Copy

In another terminal:

IMPLEMENTATION=web-sdk_react pnpm --dir lib/e2e-web test
Copy

When finished:

pnpm implementation:run -- web-sdk_react serve:stop
Copy

This implementation uses the shared Playwright suite from lib/e2e-web. The implementation sets IMPLEMENTATION=web-sdk_react when invoking that suite.

3. Use Playwright UI or the report viewer when needed:

pnpm implementation:run -- web-sdk_react test:e2e:ui
pnpm implementation:run -- web-sdk_react test:e2e:report
Copy

Environment variables

The setup step creates the local .env file if needed:

test -f implementations/web-sdk_react/.env || cp implementations/web-sdk_react/.env.example implementations/web-sdk_react/.env
Copy

See .env.example for the Contentful and Optimization API values used by the local mock setup. The Optimization SDK client has mock-safe defaults for its client ID, environment, and API base URLs, but Contentful entry loading requires the Contentful env vars from .env.example. To use local mock Contentful endpoints, set PUBLIC_CONTENTFUL_CDA_HOST=localhost:8000 and PUBLIC_CONTENTFUL_BASE_PATH=contentful.

Preview panel attachment is controlled at build time by PUBLIC_OPTIMIZATION_ENABLE_PREVIEW_PANEL. Set it to true before starting or building the app for development demos that need preview panel behavior.

Project structure

web-sdk_react/
├── src/
│   ├── main.tsx              # Application entry point
│   ├── App.tsx               # Root component
│   ├── optimization/         # SDK React adapter
│   │   ├── OptimizationProvider.tsx
│   │   ├── hooks/
│   │   └── liveUpdates/
│   ├── components/           # Shared UI components
│   ├── pages/                # Route pages
│   ├── sections/             # Entry rendering sections
│   ├── services/             # Contentful client setup
│   └── types/                # Local Contentful and env types
├── index.html                # HTML template
├── rsbuild.config.ts         # Rsbuild configuration
├── tsconfig.json             # TypeScript configuration
└── package.json
Copy

Adapter touchpoints

This implementation demonstrates a local React adapter over @contentful/optimization-web. Use the @contentful/optimization-web package README for API-level Web SDK workflows, and compare against the React Web SDK reference implementation for the preferred official React package integration.

Implementation-specific touchpoints:

• src/optimization/OptimizationProvider.tsx owns Web SDK lifecycle and provider state.
• src/optimization/hooks/ exposes local hooks for SDK access, entry resolution, and analytics actions.
• src/optimization/liveUpdates/ owns preview-panel-aware live update context.
• src/sections/ renders optimized Contentful entries and wires entry tracking attributes.
• src/components/ contains shared UI components for rich text, controls, and tracking display.

Related

• React Web SDK reference implementation - Primary React implementation using the official React SDK package
• React Native reference implementation - React Native reference implementation
• Web SDK Vanilla JS reference implementation - Vanilla JavaScript reference implementation
• @contentful/optimization-web - Web SDK package