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.

Prerequisites

• Node.js >= 20.19.0 (24.13.0 recommended to match .nvmrc)
• pnpm 10.x

Setup

From the repository root:

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

pnpm build:pkgs
Copy

2. Install implementation dependencies:

pnpm implementation:run -- web-sdk_react implementation:install
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 Playwright flow step by step:

pnpm implementation:run -- web-sdk_react serve
Copy

In another terminal:

pnpm --dir implementations/web-sdk_react --ignore-workspace exec playwright test
Copy

When finished:

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

3. Use Playwright UI or codegen when needed:

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

Environment variables

Copy .env.example to .env and configure:

cp .env.example .env
Copy

See .env.example for available configuration options. The implementation reads from import.meta.env directly and falls back to local mock-safe defaults, so it can run without extra env wiring. To use local mock Contentful endpoints, set PUBLIC_CONTENTFUL_CDA_HOST=localhost:8000 and PUBLIC_CONTENTFUL_BASE_PATH=contentful.

Preview panel attachment is gated behind PUBLIC_OPTIMIZATION_ENABLE_PREVIEW_PANEL. Set it to true 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/
│   │   └── components/
│   ├── pages/                # Route pages
│   └── components/           # UI components
├── e2e/                      # Playwright E2E tests
├── public/                   # Static assets
├── index.html                # HTML template
├── rsbuild.config.ts         # Rsbuild configuration
├── tsconfig.json             # TypeScript configuration
└── package.json
Copy

SDK integration patterns

This implementation demonstrates how to build a React adapter for @contentful/optimization-web. Key patterns include:

Provider setup

import { OptimizationProvider } from './optimization'

function App() {
  return (
    <OptimizationProvider>
      <YourApp />
    </OptimizationProvider>
  )
}
Copy

Using hooks

import { useOptimizationResolver, useOptimization } from './optimization'

function MyComponent() {
  const { sdk, isReady } = useOptimization()
  const { resolveEntry } = useOptimizationResolver()
  const resolved = resolveEntry(baseEntry)

  // ...
}
Copy

Analytics tracking

import { useAnalytics } from './optimization'

function TrackedComponent() {
  const { trackView } = useAnalytics()

  useEffect(() => {
    void trackView({ componentId: 'component-id' })
  }, [])

  // ...
}
Copy

Related

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