Preview Integration

Brease CMS includes a live preview feature that renders your Next.js site inside an iframe and sends real-time content updates as editors make changes. The brease-next package handles this automatically with no additional configuration required.

How It Works

When a content editor opens the page preview in the Brease CMS, the following happens:

1. The CMS loads your site in an iframe
2. The BreaseClientProvider (included inside BreaseContext) mounts a BreasePreviewListener component
3. The listener detects it is running inside an iframe (window.self !== window.top)
4. A PostMessage handshake establishes communication between the CMS and your site
5. The CMS sends live page updates as the editor modifies content
6. The page object in useBrease() updates automatically, causing components to re-render

No code changes are needed to enable preview mode. It activates automatically when your site is loaded in the CMS iframe.

PostMessage Protocol

Communication between the CMS (parent frame) and your site (child frame) uses the browser PostMessage API.

Messages from Your Site to CMS

Messages from CMS to Your Site

When the listener receives a brease:init-page message, it updates the page state in the context. This causes all components using useBrease().page or BreasePage to re-render with the new content.

Section Toolbar

When your site is running inside the CMS iframe, the BreasePage component automatically renders a SectionToolbar overlay on each section. The toolbar displays:

• The section name
• An edit button that, when clicked, sends a brease:edit-section message to the parent frame with the section's UUID and the current scroll position

This allows editors to click directly on a section in the preview to jump to that section's settings in the CMS editor.

Styles

To get the correct styling for the section toolbar and preview overlays, import the brease-next styles in your root layout:

// src/app/layout.tsx (or your slug layout)
import 'brease-next/styles'

This import adds a small CSS file with styles for the toolbar overlay. It does not affect your site's appearance outside of preview mode.

iframe Detection

The preview listener uses a simple check to determine if the site is running inside an iframe:

window.self !== window.top

When this condition is true, the listener:

• Sends the brease:ready message to the parent frame
• Starts listening for brease:init-page messages
• Enables the section toolbar overlays in BreasePage

When the site is loaded normally (not in an iframe), none of the preview functionality activates.

CORS and Content Security Policy

For the CMS to load your site in an iframe, your Next.js application may need to allow framing from the CMS domain. If your site has a strict Content Security Policy or X-Frame-Options header, you may need to update your next.config.ts:

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          {
            key: 'Content-Security-Policy',
            value: "frame-ancestors 'self' https://app.brease.io",
          },
        ],
      },
    ]
  },
}

export default nextConfig

Replace https://app.brease.io with your CMS instance domain if you are using a custom deployment.

If you are using a hosting platform that sets its own headers (e.g. Vercel), you may need to configure these headers in the platform's settings as well.

Summary

Next Steps

• Context & Hooks -- how BreaseContext provides data to preview
• Components -- BreasePage and section rendering
• Getting Started -- initial project setup