The integration contract

​

Prerequisites

• Node 22+ and your usual package manager.
• A Next.js 15 or 16 project on the App Router. On Astro 5+, @avocadostudio-ai/astro satisfies this contract for you — the seams below still describe what it is doing, but you do not implement them. Any other framework can satisfy the same contract through the SDK’s framework-agnostic /core primitives — see Non-Next.js integration — but you would be a first mover.
• An Avocado orchestrator running, locally or hosted. It defaults to http://localhost:4200.
• An ANTHROPIC_API_KEY, OPENAI_API_KEY or GOOGLE_GENAI_API_KEY on the orchestrator. Avocado runs on your keys and never resells tokens.

​

Before you write anything: the survey

​

The six seams

​

1. The editor API — one catch-all route

• The secret is not optional in production. publishSecret is usually process.env.PUBLISH_TOKEN, and the orchestrator sends the same value as x-publish-token. With no secret configured, the route answers 401 under NODE_ENV=production and names the variable in the response; on your own machine it stays open, because publishing to it is the point, and warns once. An optional guard on an endpoint that overwrites a site’s content is not a guard.
• A publish may not remove every page. The only validation this route used to do was Array.isArray(body.pages), and [] is an array — so a client that failed to load its own state could replace the whole site with nothing and get {"ok":true} back. Emptying the site now needs "allowDelete": true in the body and is otherwise a 409 that says how many pages it protected. Removing one page of three is still an ordinary edit; set maxPagesRemoved if you want a tighter bound than “not all of them”. A site that is already empty may still publish empty, so a new integration’s first publish is not refused.

​

2. The page factory

• default Page — the route component.
• generateStaticParams — your slugs.
• generateMetadata — not optional in practice. Without it every page inherits the root layout’s <title>, with no description and no social card. The SDK derives all three from the page, but Next only reads them if the route file exports the function.

​

3. Block registration — the boundary itself

import { registerBlock, z } from "@avocadostudio-ai/site-sdk/blocks"

registerBlock("PricingTier", {
  schema: z.object({ name: z.string(), price: z.string(), blurb: z.string() }),
  meta: {
    displayName: "Pricing Tier",
    fields: { blurb: { kind: "richtext" }, price: { kind: "text" } },
  },
})

• fixed: true on a block type hides move, delete and add, and the ops engine refuses them. Use it for a section the template draws in a fixed place.
• readOnly: true, with a readOnlyReason, on a field the site shows but cannot store — shared asset alt text, a slug, a date. The panel shows it disabled with the reason, and writes are refused.
• shared: true on a block type makes every instance with the same block id one piece of content — a header or footer injected into every page. An edit on one page reaches every page’s draft.

​

4. Markers — which element is which field

<h2 {...editableProps("headline", { kind: "text" })}>{props.headline}</h2>

{props.items.map((item, i) => (
  <div key={item.id} {...editableScopeProps(`items[${i}]`, { display: "contents" })}>
    <FaqRow item={item} />
  </div>
))}

• A missing scope is wrong, not absent. The child marks a bare question, the overlay resolves it against the enclosing block, and an edit to a headline inside a column patches a prop the section does not have.
• display: "contents" is the answer to the layout problem. A wrapper added only to carry a scope otherwise becomes the flex or grid item, and the layout the rows had becomes the layout of a column of wrappers. With display: contents the rows go on being their parent’s children. Leave it off when the wrapper is one you were rendering anyway.

​

5. The content adapter

• Files or JSON — nearly nothing. @avocadostudio-ai/site-sdk/publish-handlers/json-file ships a working handler. See examples/sample-site/.
• A mainstream CMS — working examples ship for Contentful, Sanity and Strapi under examples/contentful-site/, examples/sanity-site/ and examples/strapi-site/. Rich text converts through a shared pivot; the converters for Storyblok, Contentful, Sanity Portable Text and Strapi are re-exported from @avocadostudio-ai/site-sdk/lens, so you need no direct dependency on @avocadostudio-ai/richtext.
• Field-level localisation, or list rows stored as their own documents — this is where the real work is. Use a field table: one declaration derives the Zod schema, the panel metadata, the projection out of the CMS and the merge back into it, instead of four hand-written things that disagree within a week. Lens packs ship for Storyblok, Sanity and Contentful (@avocadostudio-ai/site-sdk/lens/storyblok, /lens/sanity, /lens/contentful).

1. merge takes the live CMS document as its source, never a snapshot Avocado holds. Every field the table never declared survives by construction.
2. Publishing is a field-level diff, not a snapshot overwrite, so a page nobody touched writes nothing.

​

6. Registration

npx avocado-register --name "My Site" --orchestrator http://localhost:3000/api/avocado

​

One more seam, if your layout mounts third-party scripts

import { isEditorRender } from "@avocadostudio-ai/site-sdk/draft"

const inEditor = await isEditorRender()
// {!inEditor && <CookieConsent />}

​

Doing it in order

​

How you know it is finished

• editableCoverage compares the fields the manifest declares against the data-editable-target markers a rendered page actually carries, and reports marked/expected. A field that lost its marker in a refactor fails this instead of silently losing inline editing.
• panelCoverage asks whether the property panel is intelligible: rowsLabelled/rowsExamined plus findings for list rows nobody can tell apart, polymorphic branches that never narrow, props in your content described by nothing, and block type names colliding with the built-ins.

​

The last gate: avocado qa

npx avocado qa

• Clicking each visible section selects a block with a sensible name and only its fields
• Fields that cannot be written (asset alt text, slugs, dates) are not offered as editable
• A chat edit and a panel edit both update the preview within a few seconds
• Rich text in the panel looks like rich text on the page (lists, headings, links)
• Asking for a language the site does not have produces a question, not an overwrite
• Publishing one page changes only that page in the CMS, and the public site shows it after reload

​

Then send one edit

​

If you get stuck

• Hand the remainder to your own coding agent with the skills on that page, which encode everything above.
• Use the onboarding agent if what you actually need is content bootstrapped from a live URL rather than a codebase wired up.
• If the contract itself is the problem — a seam that does not fit your site’s shape — get in touch. Several of the helpers on this page exist because an integration hit exactly that and told us.