This page is the human path. You’ll wire your site into Avocado Studio yourself by following our existing integration guides in order. There’s no automation involved — you read, you copy, you adapt. End state: a site registered with the orchestrator, your existing pages serving from your existing routes, the editor able to apply AI-generated edits via Draft Mode. Time: ~30 minutes for a vanilla Next.js 15 project. Add 30–60 minutes per non-trivial customization (custom block types, non-default content store, custom auth).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.
Prerequisites
- Node 20+ and pnpm
- A Next.js 15 project (App Router) — or any framework where you’re willing to wire up the editor API contract by hand using the SDK’s
/coreprimitives (Non-Next.js Integration) - The Avocado orchestrator running locally or remotely (
pnpm dev:orchestrator) - One of:
ANTHROPIC_API_KEYorOPENAI_API_KEY
Steps
Read the concepts
Start with Core concepts so the rest of the docs make sense. Pages, blocks, operations, draft mode — five minutes, save yourself an hour later.
Run the editor quickstart
Follow Content Studio Quickstart to get the editor talking to your local orchestrator. Confirm you can open the editor at
http://localhost:4100 and see a session.Wire the SDK into your Next.js site
Follow Next.js Integration. This is the meat — two SDK helpers do almost all the work:
createEditorApiHandler mounts the /api/editor/* catch-all (blocks, pages, draft, draft/disable, publish) and createSitePage provides a drop-in app/[[...slug]]/page.tsx with draft mode, navigation, and the editor overlay already wired up.At the end of this step you should be able to load your site inside the editor’s iframe and see Draft Mode toggle.Register your blocks
If you’re using the built-in block library, you’re done — skip this step. If you have custom React components you want the editor to manage, follow Custom Blocks to register them with the SDK so the AI knows about their props and the editor can render them.
(Optional) Enable Puck mode
For visual drag-and-drop editing, follow Puck mode. This is opt-in per site.
Register the site with the orchestrator
From your project directory, run:This bin script (shipped with
@ai-site-editor/site-sdk) generates a DRAFT_MODE_SECRET if one isn’t already set, fills in the rest of the env vars, and POSTs the site config to the orchestrator’s /sites/register endpoint. After it succeeds, the site appears in the editor’s dashboard automatically.See npx avocado-register --help for all available flags (--id, --port, --orchestrator, --secret, --session, --purpose, --preview-url).Verify it works
From the editor’s chat panel, send a simple edit like “change the hero headline to ‘Hello world’”. You should see the AI generate an operation, the preview update, and an undo entry appear in the history. If anything’s broken, see Chat troubleshooting.
What you skipped vs the agent path
The Onboarding agent does a few extras that the manual path doesn’t:| Step | Agent does it | Manual |
|---|---|---|
| Register the site with the orchestrator | Yes (register_site MCP tool, automatic) | Run npx avocado-register --name "..." from your project directory |
| Bootstrap initial pages from a URL or description | Yes | You start with whatever pages your project already has |
| Extract and apply a theme automatically | Yes | You configure your own theme tokens |
| Download remote images into your project | Yes | Bring your own assets |
When to escape to AI
You should drop into the Onboarding agent or hand off to your own coding agent if:- The integration takes longer than an hour and you’re stuck
- Your project has unusual conventions and the docs assume vanilla Next.js
- You’re migrating content from a CMS or live URL and don’t want to hand-author 50 pages