Skip to content

Live Preview

Live preview shows an entry on your real site while it is being edited. The console loads your site in a frame on the Page Builder’s canvas, and your site renders the editor’s unsaved draft as they type, with your own components, CSS, and fonts. There is no separate preview build and no preview token: the draft travels from the console to your page over window.postMessage, and the PlenaryBridge component on your page renders it.

You need live preview for the Page Builder: the canvas is the preview. Set it up once per model, with one preview route on your site.

  1. The model has a Preview URL template, such as https://www.example.com/preview/{{slug}}. When an editor opens an entry, the console fills in the template from the saved entry and loads that URL in a frame.
  2. Your preview route renders the page wrapped in <PlenaryBridge>. Inside a frame, the bridge sends a hello message to the console origins you allowed.
  3. The console checks that the message came from the preview URL’s origin, then replies init. From then on the bridge is connected: the console shows Preview connected.
  4. The bridge sends the console your registered components and design tokens (the manifest), which fill the palette.
  5. On every edit, the console sends the whole draft (render). The bridge replaces the page’s published content with the draft’s blocks field and re-renders.
  6. Clicks, hovers, drops, keyboard shortcuts, and the page’s height flow back to the console, so editors can select and arrange blocks directly on the canvas.

Outside the console, the bridge does nothing: it renders its children, your normal page.

What is pushed is the draft held in the console, not what is saved. Editors see unsaved changes immediately, and nothing reaches your site’s public pages until the entry is saved and published.

A model with Show preview on but no blocks field also gets a preview frame, but the bridge has no region to render. The frame shows whatever your page fetches from the API, and the console reloads it after each save. To see saved-but-unpublished changes there, whether a draft entry or a published entry’s pending changes, the preview route must read with an API key that has Include draft content turned on. See API Keys.

  1. Go to Content Management → Content and open the model.
  2. On the Settings tab, in Metadata, turn on Show preview.
  3. Fill in Preview URL.
  4. Optionally turn on Open entries in Page Builder.
  5. Click Save model.

The preview URL is a template written like a computed field:

Template Resolves to
{{slug}} a property of the entry: id, site_key, slug, locale, status, path, folder_id, published_at, created_at, or updated_at
{{data.category}} the value of the entry’s category field
{{data.seo.path}} a sub-field of an object field

For example, https://www.example.com/preview/{{slug}} becomes https://www.example.com/preview/about for the entry with slug about. Values are inserted as is, without URL encoding.

Rules worth knowing:

  • The template renders against the last-saved entry. A brand-new entry has no preview until it is saved once (“Save this entry to preview it.”), and changing the slug takes effect after saving.
  • If any reference resolves empty, the console shows no preview rather than a wrong URL: “The preview URL can’t be built yet — a field it references is empty.”
  • Use an absolute URL. Its origin (scheme, host, and port) is the only origin the console accepts messages from. If the URL redirects to another origin (for example http:// to https://, or the bare domain to www), the bridge never connects. Point the template at the final origin.

While you develop the site, you can load the preview from your own machine without changing the model. In the Page Builder toolbar, click the globe (Preview origin), enter an origin such as http://localhost:3000, and click Apply. The console keeps the preview URL’s path, query, and hash and swaps only the origin, and it trusts messages from the new origin instead.

The override applies to you alone, for the current site, in the current browser. Other editors keep seeing the model’s preview URL. While it is on, the globe is highlighted and its tooltip names the origin. Click Use the model’s URL to clear it.

Add the console’s origin to PLENARY_EDITOR_ORIGINS in your local environment too, or the bridge ignores the console.

The preview route renders the page inside PlenaryBridge. This setup uses the Next.js App Router with @plenary/client, @plenary/core, and @plenary/react 1.0.x.

.env.local
PLENARY_BASE_URL=https://your-instance.plenarycms.io
PLENARY_SITE_KEY=default
PLENARY_API_KEY=pln_pub_your_public_key
PLENARY_LOCALE=en-us
PLENARY_EDITOR_ORIGINS=https://your-instance.plenarycms.io

PLENARY_BASE_URL is your instance’s origin; the console is served from the same origin at /cms. PLENARY_API_KEY is a public API key for the site. PLENARY_EDITOR_ORIGINS lists the console origins allowed to drive the preview, comma-separated.

lib/plenary.ts
import { createClient } from "@plenary/client";
export const plenary = createClient({
baseUrl: process.env.PLENARY_BASE_URL!,
siteKey: process.env.PLENARY_SITE_KEY ?? "default",
apiKey: process.env.PLENARY_API_KEY!,
locale: process.env.PLENARY_LOCALE ?? "en-us",
});
/** The model whose entries are pages. */
export const PAGE_MODEL = "page";
/** The key of the page model's blocks field. */
export const PAGE_REGION = "body";
/** Console origins allowed to drive the live preview. Never "*". */
export const EDITOR_ORIGINS = (process.env.PLENARY_EDITOR_ORIGINS ?? "")
.split(",")
.map((origin) => origin.trim())
.filter(Boolean);

PlenaryBridge is a client component, and it renders your custom blocks in the browser. Import your block registrations here too, because Next.js gives client components their own copy of the registry:

components/PageBridge.tsx
"use client";
import type { ReactNode } from "react";
import { PlenaryBridge } from "@plenary/react/bridge";
// Registers the custom blocks in the client module graph, where the bridge renders.
import "@/lib/blocks";
export function PageBridge({
region,
editorOrigins,
children,
}: {
region: string;
editorOrigins: string[];
children: ReactNode;
}) {
return (
<PlenaryBridge region={region} editorOrigins={editorOrigins}>
{children}
</PlenaryBridge>
);
}

lib/blocks.ts is where you call register and registerTheme; see Custom components. If you have no custom blocks yet, leave the import out.

app/preview/[slug]/page.tsx
import type { Metadata } from "next";
import { PlenaryNotFoundError } from "@plenary/client";
import type { PlenaryDocument } from "@plenary/core";
import { PlenaryPage } from "@plenary/react";
import { PageBridge } from "@/components/PageBridge";
import { plenary, PAGE_MODEL, PAGE_REGION, EDITOR_ORIGINS } from "@/lib/plenary";
import "@/lib/blocks";
export const dynamic = "force-dynamic";
export const metadata: Metadata = { robots: { index: false, follow: false } };
type PageData = Record<string, PlenaryDocument | undefined>;
export default async function PreviewPage({ params }: { params: Promise<{ slug: string }> }) {
const { slug } = await params;
let published: PlenaryDocument | undefined;
try {
const entry = await plenary.getEntry<PageData>(PAGE_MODEL, slug);
published = entry.data[PAGE_REGION];
} catch (err) {
// A never-published page is not readable with a public key.
// The bridge still renders the draft once the console connects.
if (!(err instanceof PlenaryNotFoundError)) throw err;
}
return (
<PageBridge region={PAGE_REGION} editorOrigins={EDITOR_ORIGINS}>
{published ? <PlenaryPage document={published} client={plenary} /> : <p>Not published yet.</p>}
</PageBridge>
);
}

Then set the model’s Preview URL to https://www.example.com/preview/{{slug}}.

Notes on this route:

  • It does not need draft access. The draft arrives from the console. The fetch only supplies what to show before the console connects (and when someone opens the URL directly), so a 404 for an unpublished page is handled, not fatal.
  • It is dynamic and not indexed. It renders on every request and tells search engines to skip it.
  • Put site chrome outside the bridge. Your layout’s header and footer render normally around it, so editors see the page in context. The bridge replaces only its own children.
  • One bridge per region. region must be the key of the model’s first blocks field, the one the Page Builder edits.

You can also mount the bridge on your public page route instead of a separate preview route: outside a frame it only renders its children. The Page Builder Site example uses a separate route so public pages stay fully server-rendered.

editorOrigins is the allow-list of consoles that may drive your preview. The bridge ignores every message from any other origin. List the origin your editors open the console on: for an instance at https://your-instance.plenarycms.io/cms, that is https://your-instance.plenarycms.io.

Pattern Matches
https://cms.example.com exactly that origin
https://*.example.com any subdomain at any depth (a.example.com, a.b.example.com), never the bare example.com
http://localhost:* localhost on any port, useful when you run the console or the site locally
  • The scheme must match exactly; there is no wildcard for it.
  • A pattern without a port matches only the default port (443 for https, 80 for http).
  • A bare * is not supported, by design.

Only wildcard a domain you control. A hosted domain shared with other customers is not one: https://*.plenarycms.io would let any other instance on that domain drive your preview. List your own instance’s exact origin.

The full matching rules are in isAllowedEditorOrigin.

Origin checks run on both sides, and neither side needs a shared secret:

  • The bridge accepts a message only if its origin matches editorOrigins and it carries the plenary: true marker. After init, it sends everything only to that one console origin.
  • The console accepts a message only from the preview URL’s exact origin, and sends only to that origin.
  • The hello announcement is sent directly to each exact origin in editorOrigins. When the list contains a wildcard pattern, hello is also sent with target "*", because a pattern cannot be a postMessage target. That is safe: hello carries only the protocol and SDK versions, and nothing else is sent until a matching console replies.
  • No draft data is exposed to your server. The draft is rendered in the visitor’s browser (the editor’s), inside the frame. Your preview route never receives it.
  • Navigation is locked while connected. Link clicks and form submits inside the frame are cancelled, so editors cannot wander off the entry they are editing.

Your site must allow being framed by the console. If you send X-Frame-Options: DENY or a Content-Security-Policy frame-ancestors directive, allow the console’s origin on the preview route:

next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
async headers() {
return [
{
source: "/preview/:path*",
headers: [{ key: "Content-Security-Policy", value: "frame-ancestors 'self' https://your-instance.plenarycms.io" }],
},
];
},
};
export default nextConfig;

You do not need to implement any of this when you use PlenaryBridge; it is here so you can debug a connection or build a bridge for another framework. Every message is { plenary: true, v: 1, type, payload }. Full payload types are in the @plenary/core protocol reference.

Step Direction Message
Announce site → console hello { protocolVersion, sdkVersion }
Activate console → site init { entryId, modelKey, editorOrigin }
Describe site → console manifest { components, theme }, then size { height }
Render console → site render { data, locale } on connect and after every edit
Select and outline both select and hover up; highlight { selectedId, hoverId } down
Drag from the palette both canvasDragOver / canvasDragLeave / canvasDragDrop down; canvasDrop { component, target } up
Canvas gestures site → console wheel (zoom), pan, key (shortcuts), edit (inline text)

Drag and drop works this way because browsers deliver no drag events over a frame from another origin. The console tracks the drag over its own canvas and sends the pointer position; the bridge works out which block is under it and answers with the drop target.

If the site and console speak different protocol versions, the console shows “The site is on a different preview protocol version; live editing is unavailable.” and falls back to reloading the frame after each save. Keep @plenary/react current to avoid this.

The console sizes the frame to your page’s full height so the whole page sits on the canvas without an inner scrollbar. That makes the frame’s height the page’s viewport height. Anything sized in viewport units inside the bridge, such as height: 100vh, min-height: 100svh or 100dvh, or Tailwind’s h-screen and min-h-screen, is then measured against a height the console chose. A 100vh hero above other content makes the page taller, the frame grows to fit, the hero grows with it, and the loop never ends.

Use fixed values in blocks and sections instead:

app/globals.css
/* Grows forever on the canvas: */
.hero { min-height: 100vh; }
/* Works everywhere: */
.hero { min-height: 640px; }

Content shorter than 100vh settles on its own; only pages that keep growing are affected. When the console detects the loop (six growth reports in a row with no settling), it stops resizing the frame and shows: “This page keeps growing. Content sized in viewport units (vh) can’t be measured on the artboard — the preview is held at {height}px.” The page then gets an inner scrollbar. Reloading, switching viewport, or an edit that lets the page settle clears it.

Media URLs from Plenary are paths on your instance, such as /media/{media_id}/original.png, and the console pushes those same paths into the preview. If your site is on a different origin from your instance, proxy /media/* to the instance so images load on your pages and in the preview:

next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
async rewrites() {
return [{ source: "/media/:path*", destination: `${process.env.PLENARY_BASE_URL}/media/:path*` }];
},
};
export default nextConfig;

The canvas always shows an Image block’s original image. Its resized variant is generated after saving and is used on the published page.

Symptom Likely cause
“This model has no preview URL.” Preview URL is empty. Set it on the model’s Settings tab.
“Save this entry to preview it.” The entry is new. Save it once.
“The preview URL can’t be built yet — a field it references is empty.” A {{...}} reference in the template has no value on the saved entry.
Stays on Waiting for preview The page does not render PlenaryBridge; the console’s origin is missing from editorOrigins; or the preview URL redirects to a different origin.
The frame is blank or refuses to load Your site sends X-Frame-Options or frame-ancestors that exclude the console’s origin, or the page errors. Open the URL with Open in new tab.
Custom blocks show “Unknown component” in the preview but render on the live site The registrations are not imported in the client component that renders the bridge.
Custom blocks are missing from the palette Same as above, or the preview is not connected and the stored manifest is from another build.
Images are broken in the preview /media/* is not proxied to your instance.
The page keeps growing Viewport units inside the bridge.