Adding a Visual Editor in Next.js

Use this page when your Next.js route already renders Dyrected content and you want editors to preview changes against the real frontend instead of guessing from raw form fields alone.

By the end, you should understand the minimum preview contract, the recommended first preview mode, and how Dyrected's click-to-edit helpers fit into a Next.js page that already knows how to render its own content.

In the quick-start flow, this page turns a working content route into an editor-friendly preview route. The next page then uses that previewable route as the foundation for a controlled landing-page workflow.

Start with the right mental model

In Dyrected, a visual editor is not a second website builder. It is your real frontend opened in a preview context while the admin keeps track of which document and field the editor is changing.

That means a working visual editor depends on three things:

the collection knows which frontend URL to open
the frontend can receive draft data
rendered fields expose stable paths when you want click-to-edit behavior

What this page does and does not do

This page is the preview integration step.

It does:

connect a real route to previewUrl
swap server-fetched content for draft content in the browser
add the field-path support needed for click-to-edit

It does not yet:

define a library of reusable landing-page sections
let editors assemble new page layouts from approved blocks
complete the full editorial page-building workflow on its own

Set `previewUrl` on the collection

For routable content, set admin.previewUrl on the collection so Dyrected knows which frontend route to open:

admin: {
  useAsTitle: "title",
  previewUrl: "slug == 'home' ? '/' : '/' + slug",
}

If the collection has no reliable frontend route yet, this page is not the right next step. Finish the normal render path first.

Start with the default preview mode

The safest first quick-start path is the default postMessage flow. It works well when your frontend already fetches a document and can replace that document with draft data in the browser.

Use previewMode: "token" later when you need a token-based preview handoff instead of a live postMessage channel.

Add a client preview component

The @dyrected/next package re-exports the live preview hook, so a client component can swap server-fetched data for draft data while the editor is typing:

"use client";

import { useLivePreview, DyrectedRichText } from "@dyrected/next";

export function PreviewPageClient({
  initialPage,
}: {
  initialPage: {
    title?: string;
    content?: string;
  };
}) {
  const { data: page } = useLivePreview({
    initialData: initialPage,
  });

  return (
    <article className="prose mx-auto">
      <h1>{page.title}</h1>
      {page.content ? <DyrectedRichText content={page.content} /> : null}
    </article>
  );
}

This keeps the first preview integration small: fetch the document normally on the server, then let the client component receive draft updates when the preview pane is open.

Add click-to-edit where it matters

Click-to-edit only works reliably when the frontend renders fields through the path-aware helpers Dyrected already exposes.

For block content, that usually means rendering through Blocks and passing the real field path:

<Blocks items={page.layout} path="layout" components={{ hero: HeroBlock }} />

That path is what lets the preview surface map a click in the frontend back to the matching field in the editor.

Test one real preview route

Open the document from the admin, launch preview, and make one visible change while the page is open.

The success signal is simple:

the correct frontend route opens
draft edits appear there while you type
clicking a supported element takes you back to the right field

When to use token mode

Reach for previewMode: "token" when:

the preview route should resolve data from a short-lived preview token
you want the frontend to re-fetch draft data instead of receiving it over postMessage
your preview setup is easier to secure or reason about as a URL-based token flow

Dyrected exposes token preview routes for that mode, and the SDK exposes getPreviewData for consuming it.

Recommended path

Do the visual editor work in this order:

make the normal page render work
set previewUrl
wire the first route to useLivePreview
add path-aware block rendering only where editors need click-to-edit

That order prevents the preview system from becoming the first place a page ever works.

Escape hatches

If you need broader background on preview semantics, keep this page as the quick-start integration step and use Collections for previewUrl and previewMode, plus Displaying Content Overview for the shared rendering helpers.

What this unlocks next

Once preview works on one real route, you are ready to turn that route into a controlled page builder. The next guide adds:

a layout blocks field with approved section types
matching frontend components for those sections
one real workflow where editors create and arrange a landing page in preview

Continue to Let Editors Build Custom Pages in Next.js with Dyrected.

Success check

You are ready for the next step when:

a collection opens the correct frontend route from the admin
draft changes show up in that route during editing
block-based areas keep their field paths stable enough for click-to-edit where needed

Once that is true, the preview integration is working. Continue to Let Editors Build Custom Pages in Next.js with Dyrected.