Contentful Personalization & Analytics
Optimization Web Preview Panel
The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time.
This package implements the first-party browser preview panel for the
Optimization Web SDK. It loads into the DOM as a Lit-based Web Component
micro-frontend and talks to the Web SDK through the preview bridge exposed by
optimization.registerPreviewPanel(...).
Table of Contents
Getting started
Install using an NPM-compatible package manager, pnpm for example:
pnpm install @contentful/optimization-web-preview-panel
Import the attach function; both CJS and ESM module systems are supported, ESM preferred:
import attachOptimizationPreviewPanel from '@contentful/optimization-web-preview-panel'
Attach the preview panel with existing Contentful SDK and Optimization Web SDK instances:
attachOptimizationPreviewPanel({
contentful: contentfulClient,
optimization,
})
The attach function appends the panel to the DOM and adds the toggle button that opens it.
The preview panel is intentionally coupled to Optimization Web SDK internals. It uses the symbol-keyed preview bridge and state interceptors to read and mutate local preview state. This is a first-party preview surface, not a general extension API.
When to use this package
Use @contentful/optimization-web-preview-panel when a Web SDK or React Web SDK integration needs
the browser preview panel attached to an existing Contentful SDK client and Optimization Web SDK
instance. Application code must not use this package as a general state extension point.
Common configuration
| Option | Required? | Default | Description |
|---|---|---|---|
contentful |
Yes | N/A | Existing Contentful client used to read preview content |
optimization |
Yes | N/A | Existing Optimization Web SDK instance |
nonce |
No | undefined |
CSP nonce applied to Lit styles when strict CSP is enabled |
For the complete attach function signature, use the generated Preview Panel reference.
Content security policy support
In strict CSP environments, pass a nonce directly:
attachOptimizationPreviewPanel({ contentful: contentfulClient, optimization, nonce })
Alternatively, set window.litNonce before attaching the panel:
window.litNonce = nonce
attachOptimizationPreviewPanel({ contentful: contentfulClient, optimization })
Related
- Preview Panel generated reference - exported attach function reference
- Optimization Web SDK - browser SDK that provides the preview bridge
- Optimization React Web SDK - React layer commonly used with the preview panel
- React Web integration guide - preview setup in a React application