component is a static renderer - no SDK, no subscriptions.
This works because the API route doesn't care who's calling it. The preview component calls it with a hash and gets draft content. The server component calls it without a hash and gets published content. Same route, same logic, different results.
### Why This Pattern
- Tokens never reach the browser - preview tokens and delivery tokens stay in server-side environment variables
- Single place for endpoint switching - one if (live_preview) check instead of scattered logic
- Works with any rendering strategy - CSR, SSR, or both through the same API route
- Easy to extend - add logging, rate limiting, or response transformation in one place
## Backend-for-Frontend (BFF) Architecture
The proxy pattern above generalizes to any BFF architecture. The frontend calls your BFF, the BFF fetches from Contentstack, and the BFF returns processed content. The BFF must know about preview context:
Frontend forwards preview parameters:
```typescript
async function fetchPage(slug) {
const params = new URLSearchParams(window.location.search);
const livePreviewHash = params.get('live_preview');
const url = new URL(`/api/page/${slug}`, window.location.origin);
if (livePreviewHash) {
url.searchParams.set('live_preview', livePreviewHash); // BFF must echo this to Contentstack
}
const response = await fetch(url);
return response.json();
}
```
BFF detects preview and switches API:
```typescript
app.get('/api/page/:slug', async (req, res) => {
const livePreviewHash = req.query.live_preview;
const client = createContentstackClient(livePreviewHash); // Must be request-scoped (see Chapter 3 for why)
const data = await client.getPageBySlug(req.params.slug);
if (livePreviewHash) {
res.set('Cache-Control', 'no-store');
} else {
res.set('Cache-Control', 'public, max-age=300');
}
res.json(data);
});
```
## Edge Middleware
Edge middleware (Vercel Edge, Cloudflare Workers, Lambda@Edge) runs between the CDN and your origin. Three common pitfalls:
### Pitfall 1: Stripping Query Parameters
```typescript
// DANGEROUS: This breaks Live Preview
export function middleware(request) {
const url = new URL(request.url);
url.search = ''; // Removes live_preview!return NextResponse.rewrite(url);
}
// FIX: Preserve preview parameters
export function middleware(request) {
const url = new URL(request.url);
const previewParams = ['live_preview', 'content_type_uid', 'entry_uid', 'locale'];
const preserved = new URLSearchParams();
previewParams.forEach(param => {
const value = url.searchParams.get(param);
if (value) preserved.set(param, value);
});
url.search = preserved.toString();
return NextResponse.rewrite(url);
}
```
### Pitfall 2: URL Normalization
```typescript
// DANGEROUS: Redirect may lose query params
export function middleware(request) {
const url = new URL(request.url);
if (!url.pathname.endsWith('/')) {
url.pathname += '/';
return NextResponse.redirect(url); // Relative redirects can drop search string depending on runtime
}
}
// FIX: Use URL constructor (preserves search params by default)
export function middleware(request) {
const url = new URL(request.url);
if (!url.pathname.endsWith('/')) {
const newUrl = new URL(url);
newUrl.pathname += '/';
return NextResponse.redirect(newUrl);
}
}
```
### Pitfall 3: Authentication Redirects
```typescript
// DANGEROUS: Redirect loses preview context
export function middleware(request) {
if (!isAuthenticated(request)) {
return NextResponse.redirect('/login'); // Preview params lost!
}
}
// FIX: Forward preview params
export function middleware(request) {
if (!isAuthenticated(request)) {
const loginUrl = new URL('/login', request.url);
const previewHash = request.nextUrl.searchParams.get('live_preview');
if (previewHash) {
loginUrl.searchParams.set('return_preview', previewHash);
}
return NextResponse.redirect(loginUrl);
}
}
```
## Database-Backed Content Caching
Some architectures sync Contentstack content to a local database for performance. Preview content must never be written to the database:
```typescript
async function getContent(slug, livePreviewHash) {
if (livePreviewHash) {
// ALWAYS fetch directly from Contentstack for preview
// Never read from or write to database
return fetchFromContentstackPreview(slug, livePreviewHash);
}
// Production: Read from database
const cached = await database.findBySlug(slug);
if (cached) return cached;
const fresh = await fetchFromContentstackDelivery(slug);
await database.upsert(slug, fresh);
return fresh;
}
```
Preview content is session-scoped. Writing it to shared storage means other users might see drafts, content might outlive the editing session, and different editors' drafts might overwrite each other.
### Bypassing the Cache Layer
```typescript
class ContentService {
async getPage(slug, options = {}) {
const { livePreviewHash } = options;
if (livePreviewHash) {
// Bypass all caches for preview
return this.fetchFromPreviewAPI(slug, livePreviewHash);
}
return this.fetchWithCaching(slug);
}
async fetchFromPreviewAPI(slug, hash) {
const response = await fetch(
`https://rest-preview.contentstack.com/...`,
{
headers: {
'preview_token': process.env.PREVIEW_TOKEN,
'live_preview': hash
}
}
);
return response.json();
// No caching, no database write
}
async fetchWithCaching(slug) {
const memCached = this.memoryCache.get(slug);
if (memCached) return memCached;
const dbCached = await this.database.findBySlug(slug);
if (dbCached) {
this.memoryCache.set(slug, dbCached);
return dbCached;
}
const fresh = await this.fetchFromDeliveryAPI(slug);
await this.database.upsert(slug, fresh);
this.memoryCache.set(slug, fresh);
return fresh;
}
}
```
## Server-Side Data Aggregation
When pages combine content from multiple sources, only Contentstack content uses the preview hash:
```typescript
async function getPageData(slug, livePreviewHash) {
const [content, products, user] = await Promise.all([
livePreviewHash
? fetchContentstackPreview(slug, livePreviewHash)
: fetchContentstackDelivery(slug),
fetchProducts(), // Commerce/CMS-agnostic sources: keep on delivery paths
fetchCurrentUser()
]);
return { content, products, user, isPreview: !!livePreviewHash };
}
```
## Debugging Context Propagation
When Live Preview isn't working in a complex architecture, trace the hash through each layer:
- Is the hash in the initial URL? Check browser devtools
- Does the frontend forward the hash to the BFF? Log BFF requests
- Does the BFF use preview API? Log API calls
- Does middleware preserve the hash? Log before/after middleware
- Is the database being bypassed? Check data source for preview requests
## Key Takeaways
- Preview context must travel end to end. Every layer must forward the hash.
- A BFF/API proxy centralizes token management and endpoint switching in one place.
- Edge middleware is a common source of silent hash loss (URL normalization, parameter stripping, auth redirects).
- Never write preview content to a shared database or persistent cache.
## Check Your Understanding
- Your BFF returns cached content for performance. An editor activates Live Preview, but their changes don't appear. What's the most likely cause, and how would you fix the BFF to handle both preview and production correctly?
- Why should preview content never be written to a shared database, even temporarily? What would happen if two editors previewed the same page simultaneously and your database stored both drafts?
- Your edge middleware normalizes URLs by adding a trailing slash with a redirect. Why might this break Live Preview, and how would you fix it?
## Exercise: Trace the Hash
Map the path the live preview hash takes through your own architecture, from the CMS iframe URL to the final Contentstack API call. For each layer, answer:
- Does this layer receive the hash? How? (query parameter, header, cookie)
- Does this layer forward the hash? To where?
- Could this layer silently drop the hash? (redirects, URL rewrites, parameter stripping)
- Does this layer cache responses? Is caching bypassed when the hash is present?
If you find a gap - a layer that doesn't forward the hash or doesn't bypass caching - that's where your preview will break.
---
## Edit Tags and Visual Builder
Prerequisites: This chapter builds on How Live Preview Works. You should have a working Live Preview implementation (via any rendering strategy) before adding edit tags. Edit tags add interactivity on top of Live Preview's real-time updates.
What you'll be able to do after this chapter:
- Add data-cslp edit tags to your components so editors can click any element to jump to its CMS field
- Construct correct field paths for flat fields, nested modular blocks, repeated items, and referenced entries
- Enable Visual Builder mode and understand how it scans the DOM to create an interactive editing surface
- Make informed decisions about which elements to tag and which to skip
## Why this matters
Edit tags let editors click on any rendered element to jump directly to its CMS field. Visual Builder takes this further, adding controls for reordering, adding, and deleting blocks directly in the preview.
Live Preview updates content in real time. Edit tags add the next layer: they let editors click directly on rendered elements to jump to the corresponding CMS field. Visual Builder uses these tags to transform your preview into an interactive editing surface.
## What Edit Tags Do
From the CMS's perspective, your rendered page is just HTML - it has no idea which entry produced the content or which fields map to which elements. Edit tags supply the missing context:
```xml
Welcome to Our Company
We help businesses grow through innovative solutions.
Welcome to Our Company
We help businesses grow...
```
Edit tags are metadata for editing, not content. Your site renders correctly without them - they add interactivity on top of Live Preview's real-time updates.
## Anatomy of an Edit Tag
Edit tags use the data-cslp attribute with a structured value:
```
data-cslp="{content_type_uid}.{entry_uid}.{locale}.{field_path}"
```
Component
Description
Example
content_type_uid
Content type identifier
page, blog_post
entry_uid
Entry identifier
blt80654132ff521260
locale
Language/locale code
en-us, de-de
field_path
Path to the specific field
title, body.0.text
For a simple field:
`data-cslp="page.blt123.en-us.title"`For a nested field in a modular block:
```
data-cslp="page.blt123.en-us.page_components.0.hero.headline"
```
The field path must exactly match the path in your content model.
## Using addEditableTags
addEditableTags from @contentstack/utils is the recommended way to add edit tags to your entries. It walks the entry's field structure, builds the correct data-cslp paths for every field (including nested modular blocks and repeated items), and attaches them to a $ property on the entry object. You don't need to construct paths manually - the utility handles content type UID, entry UID, locale, and field hierarchy for you.
This is the approach used in the kickstart projects and should be the default in any Live Preview implementation. Call it once in your data layer, immediately after fetching, and every component downstream gets correct edit tags for free.
### The Data Layer Pattern
Centralize addEditableTags in the function that fetches content. This way every component that receives the entry already has $ populated:
```javascript
import contentstack from "@contentstack/delivery-sdk";
import { addEditableTags } from "@contentstack/utils";
export async function getPage(url) {
const result = await stack
.contentType("page")
.entry()
.query()
.where("url", QueryOperation.EQUALS, url)
.find();
const entry = result.entries?.[0];
if (entry) {
// One call generates edit tags for every field in the entry
addEditableTags(entry, "page", true, "en-us");
// Also tag any referenced entries with their own content type
if (entry.author) {
addEditableTags(entry.author, "author", true, "en-us");
}
}
return entry;
}
// entry.$.title → { 'data-cslp': 'page.blt123.en-us.title' }
// entry.$.page_components__0 → { 'data-cslp': 'page.blt123.en-us.page_components__0' }
// entry.author.$.name → { 'data-cslp': 'author.blt456.en-us.name' }
```
Parameter
Type
Description
entry
object
The entry data from Contentstack
content_type_uid
string
The content type identifier
tagsAsObject
boolean
true returns { 'data-cslp': '...' }, false returns a string
locale
string
The locale code
### Using $ in Components
Once addEditableTags has been called in the data layer, components simply spread from entry.$:
```
// React (tagsAsObject: true) - just spread the $ property
{entry.title}
{entry.description}
```
```
{{ entry.title }}
```
Every example in this chapter assumes addEditableTags was already called in the data layer. Components never call it themselves.
## Field Paths in Practice
For flat content models, paths are straightforward: "title", "body". For complex nested structures, paths must navigate the hierarchy:
```javascript
// Content model with modular blocks
{
page_components: [
{ hero: { headline: "Welcome", subheading: "Your journey starts here" } },
{ features: { items: [{ title: "Fast" }, { title: "Secure" }] } },
];
}
// Field paths:
// "page_components.0.hero.headline"
// "page_components.0.hero.subheading"
// "page_components.1.features.items.0.title"
// "page_components.1.features.items.1.title"
```
Accuracy matters more than coverage. An incorrect path opens the wrong field and confuses editors. This is why addEditableTags is so valuable - it generates correct paths for the entire entry structure, including modular blocks and nested arrays, so you don't have to build them by hand.
### Modular Blocks
Each block has a type, an index in the array, and type-specific fields. When you call addEditableTags on the entry, it generates $ properties for every level of nesting, including indexed keys like page_components__0 for each block:
```typescript
// addEditableTags was already called in the data layer (see "Using addEditableTags" above)
// entry.$ now contains paths for all blocks and their fields
function PageComponents({ entry }) {
return entry.page_components?.map((block, index) => {
// addEditableTags generates `page_components__{index}` keys on entry.$
const blockTag = entry.$?.[`page_components__${index}`];
switch (block._content_type_uid) {
case "hero_block":
return (
);
case "features_block":
return (
);
default:
return null;
}
});
}
function HeroBlock({ block, tag }) {
return (
{/* block.$ contains edit tags for fields within this block */}
{block.headline}
{block.description}
);
}
```
flowchart LR
subgraph model["Content Model"]
cm1["page_components[0].hero.headline"]
cm2["page_components[1].features.items[0].title"]
cm3["page_components[1].features.items[1].title"]
end
subgraph tags["Edit Tags"]
et1["page.{uid}.en-us.page_components.0.hero.headline"]
et2["page.{uid}.en-us.page_components.1.features.items.0.title"]
et3["page.{uid}.en-us.page_components.1.features.items.1.title"]
end
cm1 --> et1
cm2 --> et2
cm3 --> et3
### Repeated Items Within Blocks
When blocks contain arrays, addEditableTags generates $ properties on each array item too:
```typescript
function FeaturesBlock({ block, tag }) {
return (
{block.section_title}
{block.items?.map((item, itemIndex) => (
-
{/* addEditableTags generates $ on each array item with the correct index */}
{item.title}
))}
);
}
```
### Referenced Entries
Referenced entries have their own UIDs. The data layer pattern above already shows how to tag them separately with their own content type UID. In components, use $ the same way as any other entry:
```typescript
function AuthorCard({ author }) {
// author.$ was generated by addEditableTags with content type "author" in the data layer
// Clicking opens the author entry directly, not the referencing field on the page
return (
{author.name}
{author.bio}
);
}
```
## Centralized Tag Helpers
If you fetch multiple content types, a helper can standardize how addEditableTags is called in your data layer:
```typescript
import { addEditableTags } from "@contentstack/utils";
// Call in your data layer after fetching - not in components
export function tagEntry(entry, contentTypeUid, locale = "en-us") {
if (!entry) return entry;
addEditableTags(entry, contentTypeUid, true, locale);
return entry;
}
// Usage in data layer functions:
export async function getPage(url) {
const result = await stack
.contentType("page")
.entry()
.query()
.where("url", QueryOperation.EQUALS, url)
.find();
return tagEntry(result.entries?.[0], "page");
}
export async function getHeader() {
const result = await stack.contentType("header").entry().query().find();
return tagEntry(result.entries?.[0], "header");
}
```
Components then use entry.$?.fieldName as usual - they don't know or care about the tagging:
```typescript
function HeroComponent({ entry }) {
return (
{entry.title}
{entry.subtitle}
);
}
```
## Granularity Trade-offs
Tag these: Primary content (headlines, body text, images), repeated items (list items, cards), CTAs and links, editable metadata.
Skip these: Structural elements (containers, wrappers), derived content (computed values, formatted dates - tag the source field), decorative elements.
Over-tagging clutters Visual Builder with too many clickable regions. Under-tagging forces editors to hunt through the entry form. Tag the content editors frequently modify.
## Visual Builder
Visual Builder transforms Live Preview from a passive display into an interactive editing surface. It's built entirely on top of Live Preview and edit tags - no new data flow, just an interaction layer.
flowchart TB
builder["Visual Builder Layer
Scans DOM for edit tags, builds click targets"]
preview["Live Preview Layer
Session, events, preview content updates"]
website["Your Website
Renders content with data-cslp attributes"]
builder --> preview --> website
### Enabling Visual Builder
Requires Live Preview Utils SDK v3.0+ and Delivery SDK v3.20.3+. Set mode to "builder":
```typescript
ContentstackLivePreview.init({
mode: "builder", // Enables DOM scanning + click-to-field on top of Live Preview
stackDetails: {
apiKey: "your-stack-api-key",
environment: "your-environment",
},
editInVisualBuilderButton: {
enable: true,
position: "bottom-right", // Floating control to jump back into Visual Builder
},
});
```
### How It Works
- DOM scanning: Scans your page for elements with data-cslp attributes
- Region detection: Calculates position and bounds for each tagged element
- Field mapping: Parses the data-cslp value to extract content type, entry UID, locale, and field path
- Interaction binding: Attaches event handlers to the regions
- Continuous monitoring: Re-scans the DOM as the page updates
### What Makes It Work Well
- Stable DOM structure: If your DOM changes after scanning, the region map becomes stale
- Consistent element-to-field mapping: Each tag should consistently map to the same element
- Predictable rendering: Avoid rendering critical content only after client-side effects
### Common Failures
- Missing edit tags: Elements aren't clickable
- Incorrect edit tags: Clicking opens the wrong field
- Dynamic DOM changes: Elements work initially but stop after re-renders
- Stale regions: Visual Builder's map is out of sync after content updates
### Visual Builder and SSR
Server-rendered HTML must include data-cslp attributes. Client-side hydration must preserve them. After iframe reloads (SSR updates), Visual Builder re-scans automatically.
### Live Preview vs Visual Builder
Feature
Live Preview
Visual Builder
Real-time content updates
Yes
Yes
Click to navigate to field
No
Yes
Visual editing controls
No
Yes
Requires edit tags
No
Yes
DOM scanning
No
Yes
## Visual Builder-Specific Features
### Multiple Field Actions
To let editors add, delete, and reorder blocks through Visual Builder, attach the edit tag to the parent wrapper using the $ object:
```typescript
{entry.page_components?.map((component, index) => (
// addEditableTags generates `page_components__{index}` keys on entry.$
))}
{/* block components */}
```
Values: vertical, horizontal, none (hides the button).
### Empty Block Placeholders
When a Modular Blocks field is empty, show a clickable placeholder:
```javascript
import { VB_EmptyBlockParentClass } from "@contentstack/live-preview-utils";
```
```javascript
{
/* VB_EmptyBlockParentClass: drop zone when modular blocks field is empty */
}
{entry.page_components?.map((component, index) => (
))}
wrapper in the component tree for maximum coverage. What's the practical downside?
---
## Debugging, Pitfalls, and Best Practices
What you'll be able to do after this chapter:
- Systematically isolate Live Preview failures using the 6-step debugging sequence instead of guessing
- Identify the five common failure modes by their symptoms and trace each to its root cause
- Apply the preview checklist to any new page or component to catch issues before they reach production
## Why this matters
Live Preview symptoms (stale content, no updates, wrong entry) rarely point directly to the cause. This chapter gives you a repeatable diagnostic process that isolates the problem layer by layer.
Most Live Preview problems fall into a small number of categories. A systematic approach isolates them faster than guessing.
## The Five Common Failure Modes
### 1. Missing or Dropped Hash
Symptoms: Preview shows published content instead of draft. First page works, navigation shows published content. "Preview randomly stops working."
Causes: Hash not extracted from URL. Hash not passed to content fetching. Navigation loses hash. Middleware strips query parameters. Redirects drop the hash.
Investigation: Check the URL in the preview iframe - is live_preview=... present? Check network requests - are they going to preview or delivery endpoints?
### 2. Cached Preview Responses
Symptoms: Changes don't appear even though preview seems connected. Old content persists. Different editors see each other's drafts.
Causes: CDN caching preview responses. Application-level caching not bypassed. Database persisting preview content.
Investigation: Check response headers for Cache-Control. Check your caching logic - does it check for the hash before caching?
### 3. Shared SDK Instances in SSR
Symptoms: One editor's changes appear in another's preview. Preview shows wrong entry's content. Inconsistent behavior under load.
Causes: Global Contentstack SDK instance mutated per request. Preview state stored in module-level variables.
Investigation: Is the SDK instantiated once globally, or per request? Do you call livePreviewQuery() on a shared instance?
### 4. Incorrect SDK Configuration
Symptoms: Live Preview panel loads but doesn't update. Changes trigger no response.
Causes: ssr: true set for CSR site (or vice versa). SDK not initialized in browser context. Wrong clientUrlParams.host for your region. SDK initialized too late.
Investigation: Check your ContentstackLivePreview.init() call. Is ssr correct? Is the host correct?
### 5. Wrong API Endpoint
Symptoms: Preview shows published content. API calls succeed but return old data.
Causes: Using delivery endpoint when preview needed. Preview token not included. Hash not included.
Investigation: Check network requests - what hostname is being called? What headers are included?
## Systematic Debugging
When Live Preview isn't working, walk through these steps in order:
flowchart LR
hash{"Hash in URL?"}
sdk{"SDK initialized?"}
events{"Events firing?"}
api{"Preview API?"}
caching{"Caching disabled?"}
rerender{"UI re-render?"}
hash --> sdk --> events
hash --> api --> caching --> rerender
### Step 1: Is the Hash in the URL?
Open devtools, find the preview iframe, check its src for live_preview=.... If missing, check Stack Settings > Live Preview and Environment Base URL configuration. Enable "Display Setup Status" for real-time feedback.
### Step 1b: Can the Iframe Load Your Site?
If the preview panel is blank, check for X-Frame-Options: DENY or strict CSP frame-ancestors. Either allow https://*.contentstack.com or use "Always Open in New Tab" (SDK v4.0.0+).
### Step 2: Is the SDK Initializing?
```typescript
// Empty string / undefined → not inside an active preview session (or init not run yet)console.log('SDK hash:', ContentstackLivePreview.hash);
console.log('SDK config:', ContentstackLivePreview.config);
```
If not initializing: verify init() is called, runs in browser context, and executes early in the lifecycle.
### Step 3: Are Change Events Firing?
```typescript
ContentstackLivePreview.onEntryChange(() => {
console.log('Entry change event received'); // Should log once per save/edit when handshake is healthy
});
```
Make an edit. If no log appears: check the handshake completed, verify the ssr setting matches your architecture.
### Step 4: Is the Correct API Being Used?
Log your fetch calls - verify the endpoint is rest-preview.contentstack.com (or regional equivalent) and headers include preview_token and live_preview.
### Step 5: Is Caching Disabled?
Check response headers for Cache-Control: no-store. Check your code - does any caching logic run when the hash is present?
### Step 6: Is the New Data Being Rendered?
If fetches return correct data but the UI doesn't update: check state updates, verify re-renders, look for framework-level caching.
## Common Pitfalls by Architecture
### CSR
- Initializing SDK after first fetch
- Not subscribing to changes (onEntryChange never registered)
- Stale closures capturing old state/props
- Memory leaks from missing cleanup
### SSR
- Global SDK instance instead of request-scoped
- Hash not extracted per request
- Hash lost on navigation
- Caching preview responses
### SSG
- No preview mode enabled
- Client-side patching causing hydration mismatches
- Preview mode cookie/session not set correctly
- Draft mode detection not checking live_preview param
## Best Practices
### Be Deliberately Conservative
- Treat preview as runtime state, not environment config
- Isolate preview logic so it's easy to reason about
- Prefer determinism over optimization - refetch everything rather than selectively
- Document your preview architecture for future maintainers
### Preview Checklist
For every page or component that supports Live Preview:
- SDK initializes before content fetch
- Hash is extracted from current request (SSR) or SDK (CSR)
- Content is fetched from Preview API when hash present
- Caching is bypassed when hash present
- Navigation preserves preview parameters
- Edit tags are applied (if using Visual Builder)
## Quick Reference
Symptom
First Check
Likely Cause
Published content in preview
URL has hash?
Hash missing/dropped
Old content persists
Cache-Control header?
Caching preview responses
Wrong entry's content
SDK per-request?
Shared SDK instance
No updates after edit
Event callback fires?
SDK not initialized/configured
Preview works then stops
Hash in navigation URLs?
Hash lost on navigation
Iframe blank / connection error
X-Frame-Options or CSP?
Site blocks iframe embedding
"SDK not initialized" in setup UI
SDK init code present?
SDK missing or server-only
"Outdated SDK" warning
SDK version?
Update to v4.0.0+
"Preview Service not enabled"
Using preview endpoints?
Migrate to Preview Service
## Contentstack's Built-in Setup Status
Contentstack includes a troubleshooting UI that surfaces configuration errors in real time. Enable it at Settings > Live Preview > "Display Setup Status" toggle.
It checks for:
- Could not connect to website: CORS, X-Frame-Options, or incorrect Base URL
- Live Preview SDK not initialized: SDK init postMessage not received
- Outdated Live Preview SDK version: Update to v4.0.0+
- Preview Service not enabled: Follow the [Migrate to Preview Service](https://www.contentstack.com/docs/developers/set-up-live-preview/migrate-to-preview-service) guide
- Default environment not set: Set one in Settings > Live Preview
## Key Takeaways
- Five failure categories: missing hash, cached responses, shared SDK instances, wrong SDK config, wrong API endpoint.
- Debug in order: hash in URL, SDK init, events firing, correct API, caching disabled, data rendered.
- Treat preview as runtime state, not environment config.
- Use the checklist for every new page. Six checks upfront beats debugging after deployment.
## Wrap-Up: Where You Are Now
You've worked through the full Live Preview guide. Here's what you now have:
- A mental model of how the CMS, your site, and the Preview API coordinate to show draft content in real time (Chapter 1)
- Implementation patterns for your specific rendering strategy - CSR, SSR, or SSG - and the configuration each requires (Chapters 2-4)
- Architectural patterns for routing preview context through middleware, BFFs, and database caches without losing the hash (Chapter 5)
- Edit tag and Visual Builder knowledge to transform your preview from a passive display into an interactive editing surface (Chapter 6)
- A diagnostic process for when things break, plus a checklist for every new implementation (this chapter)
The concepts are consistent across the guide because the architecture is consistent: the CMS signals, your site refetches, the Preview API serves drafts, and the hash scopes everything to a session. Every chapter is a different angle on the same system.
If you're implementing Live Preview for the first time, start with the simplest rendering strategy that matches your architecture and get a single page working end to end. Expand from there. If you're debugging an existing implementation, the 6-step sequence in this chapter will isolate the issue faster than anything else.
---
## AI Agent Playbook for Live Preview and Visual Builder
If you are reading this chapter as an agent, do not treat it as background reading. Treat it as procedure.
Your job is to identify where preview context is lost, why draft content is not reaching the renderer, or why Visual Builder cannot map rendered elements back to fields. Do not guess from symptoms alone.
## Core Truths
Anchor on these facts before you inspect code:
- Live Preview is a session, not just an endpoint switch. Contentstack creates a session-scoped live_preview hash and loads the site with it.
- Change events contain no content payload. The CMS signals that something changed. The site must refetch.
- Preview and Delivery APIs share shapes, but not intent. Delivery API serves published content and is cacheable. Preview API serves draft content and is never cacheable.
- The ssr setting controls preview behavior, not the entire app architecture. ssr: false means refetch in place in the browser. ssr: true means reload the iframe so the server renders again.
- Preview context is runtime state. The hash can rotate. It must not be persisted, cached, or shared across requests.
- Visual Builder depends on edit tags. Live Preview can work while Visual Builder still fails.
- Most failures are transport failures. The hash is missing, dropped, cached away, or ignored before the fetch happens.
If you remember only one rule, remember this: trace one edit through the whole system.
## Your Workflow
Work in this order every time:
- Classify the symptom.
- Classify the rendering strategy on the affected route.
- Interview the developer only enough to unblock inspection.
- Inspect the codebase for the preview contract.
- Name the most likely broken contract before editing.
- Patch the smallest correct layer.
- Give the developer a short verification checklist.
Do not ask for secrets. Ask only for code, redacted URLs, screenshots, stack settings, logs, or devtools evidence.
## Step 1: Classify the Symptom
Map the issue into one of these buckets immediately:
Symptom bucket
Usually means
Blank preview or setup status errors
connection, iframe policy, base URL, or SDK init
Published content in preview
missing hash or wrong API path
Edits do not update
wrong ssr mode, no event loop, or no reload path
Preview breaks after navigation
hash propagation failure
Wrong entry, wrong locale, or another editor's content
shared SSR state or caching
Visual Builder controls fail but preview updates work
edit tags or builder mode problem
Do not branch into multiple buckets at once unless the evidence forces you to.
## Step 2: Classify the Rendering Strategy
You must know which rendering rules apply before debugging.
Ask only the minimum needed:
- What framework and route are affected?
- Does this page fetch content in the browser, on the server per request, or from static output with a preview mode?
- Is there a middleware, BFF, API route, or proxy between the page and Contentstack?
Map the result:
- CSR: browser fetch, in-place rerender, ssr: false
- SSR: server fetch per request, iframe reloads, ssr: true
- SSG preview: static in production, dynamic in preview mode
- Middleware/BFF: preview state must survive an extra hop
If the route mixes strategies, isolate the exact path the affected page uses before proceeding.
## Step 3: Interview the Developer
Ask for evidence, not opinions.
Request only what helps you prove or eliminate a failure family:
- A redacted preview URL or screenshot showing whether live_preview is present
- The code path for ContentstackLivePreview.init()
- The code path where preview vs delivery is chosen
- One failing network request showing hostname and cache headers
- A screenshot of Contentstack's "Display Setup Status" panel if the page is blank or disconnected
- The data-layer function where addEditableTags() should run if Visual Builder is involved
Never ask for:
- API keys
- preview tokens
- cookies
- raw auth headers
- entire .env files
## Step 4: Audit the Repo
Start with targeted searches:
```bash
rg -n "ContentstackLivePreview|onEntryChange|onLiveEdit|live_preview|preview_token|rest-preview|addEditableTags|data-cslp|VB_EmptyBlockParentClass|draftMode|setPreviewData|Cache-Control|no-store|frame-ancestors|X-Frame-Options"
```
Then answer these questions from the code:
- Where is ContentstackLivePreview.init() called?
- Is ssr correct for the affected route?
- Where does the app switch between Preview API and Delivery API?
- Where is the hash read from?
- Can navigation, middleware, redirects, or rewrites drop query params?
- Is caching bypassed whenever preview is active?
- If Visual Builder is involved, where are edit tags generated and spread into the DOM?
## Step 5: Identify the Broken Contract
Use the following diagnosis tree.
### A. Blank Preview or Setup Status Errors
Check:
- Is the preview URL reachable directly in a browser tab?
- Does the site block embedding with X-Frame-Options or frame-ancestors?
- Is the stack's Live Preview Base URL correct for the environment and locale?
- Does browser-executed code on the affected route call ContentstackLivePreview.init()?
- If clientUrlParams.host is set, does it match the stack region?
Likely broken contract:
- the CMS can load the URL, but the page cannot initialize a valid preview session
Likely fixes:
- loosen iframe policy or use "Always Open in New Tab"
- correct base URL configuration
- move SDK init into browser code that actually runs on the previewed route
### B. Published Content in Preview
Check:
- Does the URL include live_preview=...?
- Do requests hit the preview host instead of the delivery host?
- Is a preview token configured when preview is active?
- Is the hash forwarded into the layer that actually fetches content?
- If a proxy or middleware exists, does it receive and forward the hash too?
Likely broken contract:
- preview context exists in the browser but never reaches the content fetch
Likely fixes:
- forward live_preview from URL or SDK into the fetch layer
- switch to Preview API when the hash is present
- configure preview host and preview token correctly
### C. Edits Do Not Update
Separate CSR behavior from SSR behavior first.
For CSR, check:
- Is ssr: false configured?
- Is onEntryChange() or onLiveEdit() registered?
- Does the callback refetch content?
- Does state get replaced instead of partially merged?
- Is the subscription missing, duplicated, or mounted too late?
For SSR, check:
- Is ssr: true configured?
- Does the iframe reload after an edit?
- Does the server receive live_preview on the next request?
- Is the server-side client request-scoped and preview-aware?
Likely broken contract:
- the CMS can signal change, but the route does not execute the correct refresh path
Likely fixes:
- correct the ssr setting
- initialize the SDK earlier
- register the change callback once
- make the CSR refetch deterministic
- preserve preview params on SSR reload requests
### D. Preview Breaks After Navigation
Treat this as a hash propagation bug until you prove otherwise.
Check:
- Do internal links preserve live_preview, content_type_uid, entry_uid, and locale where needed?
- Do redirects, rewrites, auth guards, or middleware strip query params?
- Does client-side routing rebuild URLs without preview context?
Likely broken contract:
- preview context exists on the initial load but is lost during route changes
Likely fixes:
- append preview params during navigation in preview sessions
- preserve search params in redirects and rewrites
- clone full URLs instead of overwriting search
### E. Wrong Entry, Wrong Locale, or Another Editor's Draft
Treat this as shared state or caching.
Check:
- Is the Contentstack client instantiated globally and mutated per request in SSR?
- Is livePreviewQuery() called on a shared SDK instance?
- Are preview responses cached at CDN, framework, proxy, memory, or database layers?
- Is any persistent storage holding preview responses?
Likely broken contract:
- preview state that should be request-scoped is being shared or cached
Likely fixes:
- create request-scoped clients for SSR and BFF layers
- disable caching whenever live_preview is present
- keep preview data out of long-lived caches and persistence layers
### F. Visual Builder Fails but Preview Updates Work
This is not a transport problem. It is a tagging problem until proven otherwise.
Check:
- Is the SDK in mode: "builder" where builder UX is required?
- Does the fetched entry pass through addEditableTags() in the data layer?
- Are $ props spread into real DOM nodes?
- Are referenced entries tagged with their own content type UID?
- Are modular block containers tagged correctly?
- Does an empty modular blocks parent use VB_EmptyBlockParentClass when needed?
Likely broken contract:
- the page renders content, but the builder cannot map DOM nodes back to entry fields
Likely fixes:
- call addEditableTags(entry, contentTypeUid, true, locale) immediately after fetching
- spread entry.$?.fieldName onto rendered elements
- tag referenced entries separately
- add VB_EmptyBlockParentClass to empty modular block parents
## Condensed Knowledge
Use this as a quick reference while you work.
### Session and Hash
- live_preview is the session-scoped hash
- it is runtime state, not environment config
- it can rotate
- it must not be stored in a database or long-lived cookie
- it must be present anywhere preview content is fetched
### Preview vs Delivery
- Delivery API: published, cacheable, safe for production
- Preview API: draft, requires preview token plus hash, never cacheable
- mixing them on one page creates inconsistent published/draft output
### Rendering Rules
- CSR: browser init, ssr: false, subscribe, refetch in place
- SSR: browser init, ssr: true, reload iframe, fetch draft content per request
- SSG: escape static output with preview mode or draft mode
- Middleware/BFF: decide preview vs delivery where the Contentstack fetch actually happens
### Visual Builder Rules
- Live Preview can work without edit tags
- Visual Builder cannot work without edit tags
- addEditableTags() is the safest way to generate data-cslp
- the generated $ props must be spread onto actual DOM nodes
- empty modular-block containers often need VB_EmptyBlockParentClass
### Setup Status Clues
If the developer can access Contentstack's setup status panel, use it early.
It can quickly reveal:
- website unreachable
- iframe blocked
- SDK not initialized
- outdated SDK
- Preview Service not enabled
- default environment not configured
## Editing Rules
When you patch the repo:
- fix the smallest layer that restores the preview contract
- do not refactor unrelated code while debugging preview
- do not move secrets into the client
- do not cache preview data to "make it faster"
- do not persist the hash
- do not keep a shared mutable preview client in SSR
If multiple fixes are possible, prefer the one that makes preview flow more explicit and request-scoped.
## Verification Checklist to Hand Back
After your fix, tell the developer to verify these exact behaviors in Contentstack:
- open the same entry again in Live Preview
- confirm the URL contains live_preview
- make a small text edit and confirm the page updates
- navigate to a second previewed page and confirm draft context remains intact
- if Visual Builder is involved, click a tagged field and confirm the correct field opens
- if modular blocks are involved, test add, reorder, and delete actions
## When to Escalate
Pause and explain the tradeoff before continuing if:
- the affected route mixes CSR and SSR in a way that obscures the preview contract
- the developer wants preview responses cached
- middleware or a custom router rewrites most URLs and you cannot yet prove hash preservation
- the issue appears to be in Contentstack stack configuration rather than repo code
- the failure is browser-only and you need screenshots, network traces, or setup status evidence
When escalating, summarize:
- what you proved
- what remains uncertain
- the smallest next piece of evidence needed
## Final Instruction
Do not diagnose Live Preview from symptoms alone.
Reduce the problem to a contract:
- the CMS must load the page with preview context
- the SDK must initialize in the correct mode
- the fetch layer must use preview services when preview is active
- caches must be bypassed
- the renderer must apply the new data
- Visual Builder must see correct edit tags
Find the broken link. Fix only that link first.