Content Manager Preview#

The Strapi v5 Content Manager Preview feature lets editors open a live preview of their content in a front-end application from within the admin panel. It is configured in config/admin.ts 1 under a preview key and surfaces as an "Open preview" button in the Content Manager edit view.

Key source locations:

Preview Configuration (preview-config.ts)#

The createPreviewConfigService exposes three methods critical to the preview lifecycle:

isConfigured()#

Returns true when preview is either explicitly disabled (enabled === false) or a handler function is present 2. A missing or null handler — e.g., after enabled: true is set but no handler has been defined — causes isConfigured() to return false, which the server service converts to a NotFoundError (see below).

validate()#

Called at startup. Throws a ValidationError if the handler is not a function 3. This enforces the contract early rather than at request time.

getPreviewHandler()#

Returns the configured handler, or a no-op emptyHandler when preview is disabled 4. Callers never need to null-check the handler.

Async handlers: Since PR #25396, the handler signature may return a Promise. The type definition in @strapi/types was broadened to (uid, params) => string | null | undefined | Promise<string | null | undefined> and the server service awaits the result 5.

NotFoundError Handling in getPreviewUrl()#

The server-side getPreviewUrl method 6 is the runtime entry point:

1. Calls config.isConfigured() 7.
2. If not configured → throws errors.NotFoundError('Preview config not found') 8. This signals "no config found" rather than a handler runtime failure.
3. If configured → awaits the user-defined handler 9. Any exception from the handler is caught and re-thrown as ApplicationError to avoid leaking implementation details 10.

The NotFoundError is intentionally distinct from the ApplicationError so the front end can branch on it.

Admin UI: PreviewSidePanel.tsx#

The panel uses RTK Query to pre-fetch the preview URL for the current document 11. The URL itself is not rendered here; it just primes the cache so the subsequent /preview route loads instantly.

NotFoundError → "Set up preview" CTA#

When the query returns a NotFoundError, the panel replaces the "Open preview" button with a tertiary "Set up preview" link pointing to docs.strapi.io/cms/features/preview 12. This was added in PR #23961 13 to improve feature discoverability.

Remount latch (PR #27043)#

Two separate mechanisms prevent the preview button from being silently lost during document state transitions (e.g., locale/status settling after load or save):

1. isPreviewEnabled latch — a boolean state that flips to true the first time a previewUrl is observed and never resets 14. The panel only returns null when !isPreviewEnabled && (!data?.data?.url || error) 15, so transient empty-data states don't hide the button mid-interaction.

2. ConditionalTooltip always-mounted — the Tooltip wrapper is always kept in the React tree; visibility is toggled via the controlled open prop (open={isShown ? undefined : false}) rather than conditional rendering 16. This prevents the child button from remounting when tooltip visibility changes, which would swallow clicks.

Configuration Reference#

The preview block lives in config/admin.ts 17:

preview: {
  enabled: true,
  config: {
    allowedOrigins: env('CLIENT_URL'), // Added to frame-src CSP
    async handler(uid, { documentId, locale, status }) {
      const document = await strapi.documents(uid).findOne({ documentId });
      // return a URL string, or null to disable preview for this content type
    },
  },
}

• allowedOrigins is automatically injected into the strapi::security CSP frame-src directive 18.
• The handler returning null disables the preview button for that specific content type without any error 19.
• The status parameter ('draft' | 'published') enables the handler to route to draft vs. published URLs 17.