Skip to content

README.md

Latest commit

 

History

History
243 lines (176 loc) · 6.13 KB

README.md

File metadata and controls

243 lines (176 loc) · 6.13 KB

Contentful Logo

Contentful Personalization & Analytics

Web SDK React Adapter Reference Implementation

Warning

The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time.

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

Note

For customer React applications that use the official React framework package, start with the React Web SDK reference implementation. This implementation remains useful when you need to understand how a React adapter can be built directly on top of the Web SDK.

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 work the same way.

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
  1. Install implementation dependencies:
pnpm implementation:run -- web-sdk_react implementation:install

Running locally

From the repository root:

  1. Start the development server:
pnpm implementation:run -- web-sdk_react dev
  1. Build for production:
pnpm implementation:run -- web-sdk_react build
  1. Preview the production build:
pnpm implementation:run -- web-sdk_react preview
  1. Run type checking:
pnpm implementation:run -- web-sdk_react typecheck

The equivalent implementation-directory commands are:

pnpm dev
pnpm build
pnpm preview
pnpm typecheck

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
  1. Or run the Playwright flow step by step:
pnpm implementation:run -- web-sdk_react serve

In another terminal:

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

When finished:

pnpm implementation:run -- web-sdk_react serve:stop
  1. 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

Environment variables

Copy .env.example to .env and configure:

cp .env.example .env

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

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>
  )
}

Using hooks

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

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

  // ...
}

Analytics tracking

import { useAnalytics } from './optimization'

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

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

  // ...
}

Related