Skip to main content

Visual Editor Setup

This guide turns on Live Editor so your team can click into slots and edit scheduled content inside the Visual Editor.

This does not render scheduled content on your production website

The Live Editor handshake powers editing inside the Visual Editor only — it does not display scheduled content to your site's visitors. Production-site rendering is done by the @bildit-platform/nextjs SDK. You set up both: the SDK (to render and to edit) as covered in the Next.js Integration Guide.

Framework support

Next.js uses BilditProvider (it includes BilditAdminBridge). Hydrogen uses BilditRoot (it includes its own BilditAdminBridge). HTML / SFCC sites use the CMS-generated host bridge snippet and may host a downloaded script.

Prerequisites​

  • A Next.js (App Router) or Shopify Hydrogen project. Next.js: Integration Guide. Hydrogen: example repo.
  • A web instance in the VXE with at least one published scheduled content item that has a Location assigned.

Step 1 — Install the SDK and wrap the app​

Do this before you click Verify. Verify looks for the SDK wrap on the live page — not a script tag in <head>.

Next.js​

yarn add @bildit-platform/nextjs
import { BilditProvider } from '@bildit-platform/nextjs'

<BilditProvider banners={banners}>
  {children}
</BilditProvider>

BilditProvider mounts the Live Editor bridge. There is nothing else to copy into app/layout.tsx.

Do not:

  • Add a beforeInteractive INJECT_SCRIPT listener
  • Put cms-client / cms-client-no-react in <head> (that races React hydration — minified #418 / #321)
  • Download and host bildit-cms-script.min.js for Next.js (the CMS sends the CDN URL)

The SDK waits for window.React, posts IFRAME_READY (with hasHostReact), and loads payload.hostReactScriptUrl (cms-client-no-react).

Optional public-site tag: pass storefrontScriptSrc / storefrontScriptKey to BilditProvider. That tag loads after host React and never inside the Live Editor iframe.

Hydrogen​

yarn add @bildit-platform/hydrogen
import { BilditRoot } from '@bildit-platform/hydrogen/client'

<BilditRoot banners={banners}>
  {children}
</BilditRoot>

BilditRoot mounts Hydrogen’s Live Editor bridge. Do not put a BILDIT script tag in <head> — that races React hydration.

Step 2 — Mark your slots​

Place a <SlotPlaceholder> wherever scheduled content should appear. slotId must match the web slot assigned to that scheduled content in the VXE — see Integration Guide → Place your slots.

// Next.js
import { SlotPlaceholder } from '@bildit-platform/nextjs'

// Hydrogen
import { SlotPlaceholder } from '@bildit-platform/hydrogen/client'

<SlotPlaceholder slotId="slot1" />

Step 3 — Verify the editor loads​

In the VXE, open your website's settings and click Verify. It drives the editor handshake against your live site and confirms the SDK bridge is present (data-bildit-admin-bridge). A green result means the VXE can open the Visual Editor on your page.

Verify fails if the tag is in <head>

A cms-client / cms-client-no-react tag or a beforeInteractive INJECT_SCRIPT script in <head> is the broken Next.js / Hydrogen config. Verify rejects that install — it does not green-light it. Remove the <head> tag, wrap the app in BilditProvider (Next.js) or BilditRoot (Hydrogen), then Verify again.

Then open your site from the VXE to start editing your slots.

Checklist​

  • App wrapped in BilditProvider (Next.js) or BilditRoot (Hydrogen)
  • No custom INJECT_SCRIPT script and no cms-client tag in <head>
  • Slots marked with <SlotPlaceholder>
  • Web instance configured, scheduled content created and assigned a Location
  • Editor load confirmed with the VXE Verify button

Next Steps​

Common Setup Issues​

See Troubleshooting if Verify fails or slots do not become editable.

The Live Editor bridge comes from BilditProvider (Next.js) or BilditRoot (Hydrogen). Confirm with the Verify button.