Contentful Personalization & Analytics

Web SDK React Reference Implementation

Reference implementation demonstrating @contentful/optimization-web usage in a React web application.

Note: This implementation uses Rsbuild for consistency with the SDK build tooling. If you're creating your own React application, you can use any build tool you prefer (Vite, Create React App, Next.js, etc.) — the SDK integration patterns demonstrated here will work the same way.

Overview

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:

# Build SDK packages (required for local development)
pnpm build:pkgs

# Install implementation dependencies
pnpm run implementation:run -- web-sdk_react implementation:install
Copy

Development

From the repository root:

# Start development server
pnpm run implementation:web-sdk_react dev

# Build for production
pnpm run implementation:web-sdk_react build

# Preview production build
pnpm run implementation:web-sdk_react preview

# Type checking
pnpm run implementation:web-sdk_react typecheck
Copy

Or from the implementation directory (implementations/web-sdk_react):

pnpm dev
pnpm build
pnpm preview
pnpm typecheck
Copy

Testing

E2E Tests

# In terminal 1: start mocks + app preview
pnpm run implementation:web-sdk_react serve

# In terminal 2: run Playwright tests
pnpm run implementation:web-sdk_react test:e2e

# Interactive Playwright UI
pnpm run implementation:web-sdk_react test:e2e:ui

# Generate tests with Playwright codegen
pnpm run implementation: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 Native Implementation - Reference implementation for React Native
• Web Vanilla Implementation - Reference implementation for vanilla JavaScript
• @contentful/optimization-web - Web SDK package