Skip to main content

Documentation Index

Fetch the complete documentation index at: https://avocadostudioai.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

This page is the short reference for how the editor connects to a Next.js site — env vars, the iframe bootstrap URL pattern, and the smoke checks. For the full integration walkthrough (mounting routes, wiring page components, registering the site), see Next.js Integration.

​
Expose your components via the Block Manifest

The editor needs to know which components on your site are editable and what props they accept. You do this by exposing a block manifest at GET /api/editor/blocks. Using the built-in blocks (quickest start): 
// app/api/editor/[...path]/route.ts
import { createEditorApiHandler } from "@ai-site-editor/site-sdk/routes"

export const { GET, POST, OPTIONS } = createEditorApiHandler({
  getPages: () => fetchYourPages(),
})
createEditorApiHandler() automatically builds the manifest from the 20 built-in block types and mounts the draft / pages / publish routes alongside it under /api/editor/*. The editor and AI planner read this manifest to understand what blocks exist, what fields they have, and what values are valid. Using your own custom components: If your site has its own component library, you define a custom manifest describing your block types and their props schemas. See Custom Blocks for the full guide, including:
  • How to define a BlockManifest with JSON Schema-based propsSchema for each component
  • How to wire it into the editor API route via getManifest()
  • How to mix your custom blocks with the built-in ones
  • How field types (image, text, list, enum) are inferred from your schema
Without a manifest, the editor runs in degraded mode (read-only preview or text-only edits). For the full Next.js integration walkthrough, see Next.js Integration.

​
Required env vars

  • Site:
    • DRAFT_MODE_SECRET
  • Editor:
    • VITE_SITE_ORIGIN
    • VITE_SITE_DRAFT_SECRET (same value as site DRAFT_MODE_SECRET)

​
Iframe bootstrap URL (enter draft mode)

Pattern: 
${VITE_SITE_ORIGIN}/api/editor/draft?secret=${VITE_SITE_DRAFT_SECRET}&redirect=${encodeURIComponent(pathWithQuery)}
Where pathWithQuery is your target site path plus context query params, for example: 
/pricing?session=dev&siteId=avocado-stories
Full example: 
http://localhost:3000/api/editor/draft?secret=top-secret&redirect=%2Fpricing%3Fsession%3Ddev%26siteId%3Davocado-stories

​
Exit draft mode (view live page)

Pattern: 
${VITE_SITE_ORIGIN}/api/editor/draft/disable?redirect=${encodeURIComponent(path)}
Example: 
http://localhost:3000/api/editor/draft/disable?redirect=%2Fpricing

​
Minimal behavior checks

  1. GET /api/editor/blocks returns valid block manifest JSON.
  2. GET /api/editor/pages returns { pages: [...] } with published pages.
  3. Wrong secret returns 401 from /api/editor/draft.
  4. Valid secret redirects and sets draft cookie.
  5. /api/editor/draft/disable clears draft cookie and redirects.
  6. Same page renders published content when draft cookie is absent.
Run these in the site project: 
pnpm typecheck
pnpm test
curl -s http://localhost:3000/api/editor/blocks | jq '.version, (.blocks | length)'
Expected:
  • manifest route returns version and non-zero block count
  • Content Studio header shows Manifest (not Degraded)