Readme · Guides · Reference · Contributing
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.
This implementation provides a thin React adapter layer over @contentful/optimization-web,
demonstrating:
OptimizationProvidercontext 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.
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.
- Node.js >= 20.19.0 (24.15.0 recommended to match
.nvmrc) - pnpm
From the repository root:
- Install pnpm packages:
pnpm install- Build SDK packages, which is required for local development:
pnpm build:pkgs- Install implementation dependencies:
pnpm implementation:run -- web-sdk_react implementation:install- Create the local
.envfile if it does not already exist:
test -f implementations/web-sdk_react/.env || cp implementations/web-sdk_react/.env.example implementations/web-sdk_react/.envFrom the repository root:
- Start the development server:
pnpm implementation:run -- web-sdk_react dev- Build for production:
pnpm implementation:run -- web-sdk_react build- Preview the production build:
pnpm implementation:run -- web-sdk_react preview- Run type checking:
pnpm implementation:run -- web-sdk_react typecheckThe equivalent implementation-directory commands are:
pnpm dev
pnpm build
pnpm preview
pnpm typecheck- Run the full E2E setup and test suite from the repository root:
pnpm setup:e2e:web-sdk_react
pnpm test:e2e:web-sdk_react- Or run the shared Playwright flow step by step:
pnpm implementation:run -- web-sdk_react serveIn another terminal:
IMPLEMENTATION=web-sdk_react pnpm --dir lib/e2e-web testWhen finished:
pnpm implementation:run -- web-sdk_react serve:stopThis implementation uses the shared Playwright suite from
lib/e2e-web. The implementation sets IMPLEMENTATION=web-sdk_react
when invoking that suite.
- 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:reportThe 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/.envSee .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.
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
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.tsxowns 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.
- 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