Preview requirements and concepts

TL;DR

• Preview is an architecture concern, not a UI feature -- it requires separate delivery planes, tokens, hosts, and caching strategies for draft vs. published content.
• Every preview request needs deterministic context propagation: environment, locale, branch, live-preview hash, and optional timestamp.
• SSR preview must be request-scoped to avoid cross-request state leakage, and caching must be explicitly disabled for preview traffic.
• Treat preview correctness as a release criterion, not an afterthought.

Prerequisites

This module assumes familiarity with React (hooks, useEffect, useState), Next.js App Router (server components, draftMode, router.refresh), and the difference between SSR and CSR rendering. The code examples use TypeScript throughout.

Preview is not a UI accessory. It is a correctness system.

When editors ask “is this page ready?”, they are asking a systems question: Can I trust what I see before publish? If preview is unreliable, teams either publish too cautiously or publish too optimistically.

The core mental model: two delivery planes

A useful way to reason about preview is to split content delivery into two planes:

• Published plane: optimized for live user traffic and stable runtime delivery
• Preview plane: optimized for draft validation and editorial feedback loops

If your app treats preview as “published plus a flag,” you usually get inconsistent results. Preview has different host routing, request context, and caching expectations.

For Contentstack, published traffic typically goes through delivery endpoints, while preview flows use preview-oriented endpoints and context (including live preview metadata).

Requirement 1: runtime supports preview context propagation

Preview is context-sensitive. To retrieve the right draft state, request context must be propagated end to end:

• environment
• locale and fallback behavior
• branch (if branch-aware workflows are used)
• live preview hash/session data
• optionally preview timestamp for timeline-style future-state validation

The important concept is not any single header or query parameter. The concept is deterministic context propagation. If context is partially dropped by middleware, router layers, SSR adapters, or API wrappers, preview becomes non-deterministic.

Common pitfall:

If preview state is stored globally in a long-lived server process, one editor's draft context can leak into another editor's request, producing non-deterministic preview results.

Requirement 2: your frontend can participate in preview transport

For Live Preview and Visual Builder workflows, the frontend experience must support in-context integration (typically iframe-based interaction patterns and edit-tag mapping).

In practice this means:

• the rendering application can be loaded in an editorial preview context
• client and/or server layers can read preview context from request/query
• rendered output can map content fields to UI regions for in-context editing workflows

Contentstack docs also note boundaries: some channels (for example native apps or third-party page builders) are not primary Live Preview targets.

Requirement 3: request-scoped behavior for SSR

SSR introduces one of the most common preview defects: cross-request leakage. If preview state is stored globally in a long-lived process object, one editor’s context can affect another request. Reliable SSR preview requires request-scoped initialization and context handling.

Design rules:

• initialize preview-specific state per request
• avoid singleton mutable preview clients in SSR paths
• make preview mode explicit in logs and tracing

This is less about framework syntax and more about process isolation discipline.

Requirement 4: preview and production caching strategies diverge

Preview traffic values freshness over cache efficiency. Production traffic usually values cache efficiency over per-request freshness. If you apply production CDN/app cache policy to preview endpoints, editors see stale data and lose trust immediately.

A robust strategy separates cache behavior by mode:

• production mode: optimize for hit rate and latency
• preview mode: no-cache or tightly controlled short-lived cache, with explicit invalidation semantics

Treat this as an architectural invariant, not a runtime tweak.

Requirement 5: observable preview pipeline

Teams often discover preview defects only through manual complaints (“I changed text but preview didn’t update”). Reliable systems expose preview telemetry:

• mode (published vs preview)
• locale
• branch/alias
• preview hash presence
• timestamp context presence
• selected host (published vs preview)

With these signals, troubleshooting becomes deterministic. Without them, preview debugging devolves into guesswork.

Light implementation example

The following example shows the architectural shape of preview-aware retrieval. Focus on explicit mode and context, not framework details:

export function buildContentstackRequest(mode: "published" | "preview", ctx: {
  branch?: string;
  locale?: string;
  livePreviewHash?: string;
  previewTimestamp?: string;
}) {
  const host =
    mode === "preview"
      ? "https://rest-preview.contentstack.com"
      : "https://cdn.contentstack.io";

  const headers: Record = {
    api_key: process.env.NEXT_PUBLIC_CONTENTSTACK_API_KEY!,
    branch: ctx.branch || "main",
  };

  if (mode === "preview") {
    headers.preview_token = process.env.NEXT_PUBLIC_CONTENTSTACK_PREVIEW_TOKEN!;
    if (ctx.livePreviewHash) headers.live_preview = ctx.livePreviewHash;
    if (ctx.previewTimestamp) headers.preview_timestamp = ctx.previewTimestamp;
  } else {
    headers.access_token = process.env.NEXT_PUBLIC_CONTENTSTACK_DELIVERY_TOKEN!;
  }

  return { host, headers, locale: ctx.locale || "en-us" };
}

This pattern creates explicit separation between delivery and preview planes and prevents “accidental preview” behavior from hidden defaults.

Conceptual integration with Timeline and Visual Builder

Preview requirements become stricter when Timeline or Visual Builder enters the stack.

Timeline implication

Timeline adds time as a query dimension. That means preview is no longer only “draft vs published,” but potentially “state at time T.”

Architectural effect:

• timestamp context must travel through request layers
• preview correctness now depends on both content state and temporal state

Visual Builder implication

Visual editing requires field-to-DOM traceability. If your component tree cannot map rendered UI back to content fields, editors can see content but cannot reliably edit in place.

Architectural effect:

• edit tags become part of delivery contract quality
• component abstractions must preserve content lineage, not erase it

Common failure modes

Failure mode 1: preview works locally but fails in shared environments

Root cause: environment/branch context differences are not explicitly encoded.

Prevention: treat environment + branch + locale as required preview inputs in integration contracts.

Failure mode 2: stale preview after content save

Root cause: cache policy copied from production path.

Prevention: explicit no-cache behavior (or strict short cache with controlled invalidation) for preview mode.

Failure mode 3: inconsistent SSR preview behavior

Root cause: shared mutable preview client state.

Prevention: request-scoped preview client/context initialization.

Failure mode 4: editors cannot edit what they can see

Root cause: missing or inconsistent edit-tag strategy.

Prevention: define edit-tag coverage as a functional requirement, not optional enhancement.

Implementation checklist for production readiness

Before calling preview “done,” verify:

1. Delivery and preview hosts are separated by explicit mode logic.
2. Preview context values are captured, propagated, and logged.
3. SSR path is request-scoped and free of shared preview state.
4. Preview cache behavior is intentionally different from production behavior.
5. Visual editing and timeline behavior are validated for critical scenarios.

If any of these are missing, you have partial preview, not reliable preview.

Summary

Reliable preview in Contentstack implementations is an architecture outcome. It requires explicit separation between published and preview delivery planes, deterministic context propagation, request-scoped SSR behavior, preview-aware caching, and observability.

When these requirements are met, preview becomes a high-trust collaboration surface between editors and developers. When they are skipped, preview becomes a source of ambiguity and release risk.