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 the Optimization Web SDK runtime.
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 an existing, unmodified Contentful Delivery API client. By default, the attach function uses the browser singleton created by the Optimization Web SDK:
attachOptimizationPreviewPanel({
contentful: contentfulClient,
})
The attach function appends the panel to the DOM and adds the toggle button that opens it. It is safe to call more than once; repeated calls reuse the in-flight or completed panel attachment.
Importing this package has no side effects. It does not attach the panel, define custom elements,
inject styles, touch storage, or mutate globals until attachOptimizationPreviewPanel(...) is
called.
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. Application code can pass
an explicit Optimization Web SDK instance, but the common browser flow uses
window.contentfulOptimization.
Common configuration
| Option | Required? | Default | Description |
|---|---|---|---|
contentful |
Yes | N/A | Existing Contentful client used to read preview content |
optimization |
No | window.contentfulOptimization |
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.
Production bundle control
The preview panel is intended for development and staging builds. Consumers own that build policy and can wrap the attachment call in an environment-backed conditional:
import attachOptimizationPreviewPanel from '@contentful/optimization-web-preview-panel'
if (import.meta.env.PUBLIC_OPTIMIZATION_ENABLE_PREVIEW_PANEL === 'true') {
void attachOptimizationPreviewPanel({ contentful: contentfulClient })
}
When the consumer bundler replaces that condition with a build-time false value and performs
dead-code elimination, the side-effect-free preview panel import graph can be removed from the
production output.
Content security policy support
In strict CSP environments, pass a nonce directly:
attachOptimizationPreviewPanel({ contentful: contentfulClient, nonce })
Alternatively, set window.litNonce before attaching the panel:
window.litNonce = nonce
attachOptimizationPreviewPanel({ contentful: contentfulClient })
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