@contentstack/live-preview-utils

The Live Preview Utils package runs on your website and establishes a communication channel between the page and Contentstack. This enables live content updates, edit controls, and Visual Editor UI within the preview surface.

This SDK is not a replacement for Contentstack delivery SDKs. Instead, it acts as a client-side bridge for preview and Visual Editor functionality.

Where this SDK runs

The SDK works across multiple Contentstack preview and editing experiences:

• Live Preview: Preview entries while your site loads inside the preview panel.
• Timeline: Preview how your site appears across future dates and scheduled updates using the same Live Preview setup.
• Visual Editor: Enable WYSIWYG editing with your site inside an iframe. Use mode: "builder" so “Start Editing” targets Visual Editor; the SDK still works when the same site is opened in Live Preview.
• Studio: Use alongside Studio to structure pages from reusable components, bind CMS data, and preview changes in real time. It is designed to work with Live Preview and Visual Editor on your connected site.

Requirements

• Browser: Initialize only on the client (window must exist). Avoid calling init during server-side rendering.
• SSR vs CSR: Defaults assume SSR-friendly behavior. For client-side rendering, pass stackSdk and set ssr: false as described in the config reference.

Installation

npm install @contentstack/live-preview-utils

Load from a CDN (advanced)

Pin the version to match your app (update 4.6.1 when you upgrade):

<script type="module" crossorigin="anonymous">
  import ContentstackLivePreview from "https://esm.sh/@contentstack/[email protected]";

  ContentstackLivePreview.init({
    stackDetails: {
      apiKey: "your-stack-api-key",
    },
  });
</script>

[!TIP] If you initialize the SDK using this snippet, do not initialize it again in your app bundle on the same page.

Quick start

Initialize the SDK to enable communication between your site and Contentstack:

import ContentstackLivePreview from "@contentstack/live-preview-utils";

ContentstackLivePreview.init({
  stackDetails: {
    apiKey: "your-stack-api-key",
  },
});

See the init configuration properties in docs/live-preview-configs.md for every option you can pass to init.

Configuration

You can configure the SDK using the following options:

• enable
• ssr
• mode (preview vs builder)
• editButton
• editInVisualBuilderButton (Start Editing outside Visual Editor)
• overlayPropagation (opt-in fallback to pierce blocking sibling overlays during hover/click detection)
• cleanCslpOnProduction
• stackDetails (apiKey, environment)
• clientUrlParams — NA / EU
• stackSdk

Full tables and examples: docs/live-preview-configs.md.

Methods and properties

• onLiveEdit: Trigger actions on live edits
• onEntryChange: Listen for entry updates
• hash: Access preview state identifier
• setPageContext: Tell Visual Builder which entry the current page renders so “Start Editing” targets the right entry (needed for custom-URL pages)
• config: Includes runtime context (for example Live Preview / Timeline preview, Visual Editor, or independent)

The configs table of contents also lists setConfigFromParams and getGatsbyDataFormat for deeper workflows.

Advanced: stripping the SDK at build time

Set PURGE_PREVIEW_SDK or REACT_APP_PURGE_PREVIEW_SDK to "true" during build to exclude preview code from production bundles.

Note: This reduces bundle size by replacing the SDK with a lightweight stub in production.

Resources

• Source: github.com/contentstack/live-preview-sdk
• Typed API (local): npm run docs

Documentation and learning

Developers

• Set up Live Preview for your website
• How Live Preview works
• Preview API
• Set up Timeline for your website

Content managers

• About Live Preview
• Preview content across a Timeline
• About Visual Editor

Studio

• Studio
• Get started with Studio

Academy

• Implementing Live Preview (course)
• Contentstack Live Preview under the hood
• Understanding Timeline
• Understanding Visual Editor