Publishing

​

What a publish carries

• A subset of pages. POST /publish takes slugs; the editor’s publish review sends the ticked pages. Every other page goes out exactly as it is live, so your code still receives the whole site. includeSiteConfig: false holds back header and nav changes.
• Shared blocks once. A block type declared shared: true is one piece of content under one block id. GET /publish/diff reports a change to it once, in sharedBlocks, with the pages it affects. A subset publish ships the ticked page’s version on every page that carries it, so the pages you receive agree. See shared blocks.
• What did not ship. onPublish may return unsupported (one sentence per change that could not be written, shown as “Not published: …”), notes (what shipping looked like) and written: false (deliberately wrote nothing). Library mode and the site contract read the same three fields — see saying what the publish did.

​

Publish targets (standalone server)

​

The three built-in targets

​

Selection order

1. If PUBLISH_TARGET=<name> env var is set and that target is registered → use it verbatim.
2. Otherwise iterate registered targets in registration order; pick the first whose canHandle(ctx) returns true.
3. Fall back to the legacy PUBLISH_MODE env: git (default) or deploy_hook → deploy-hook.

​

Site contract (the default)

​

The publish route is authenticated

# On the orchestrator. Sent as the `x-publish-token` header.
PUBLISH_TOKEN=<shared secret>

export const { GET, POST, OPTIONS } = createEditorApiHandler({
  getPages,
  onPublish,
  publishSecret: process.env.PUBLISH_TOKEN,
})

​

A publish may not remove every page

• A site that is already empty may still publish empty. That publish removes nothing, and refusing it would fail a brand-new integration on its very first publish, before it has any content to protect.
• A baseline read that throws does not open the gate. The handler reads your getPages to find out what is currently published, and does so best-effort: a CMS read that times out becomes “no baseline” rather than an error, because a publish is not the moment to fail on a read. But “no baseline” is not “the site was empty” — an empty publish with no baseline is still refused. Not knowing what is there is not a reason to overwrite it with nothing.

​

maxPagesRemoved

export const { GET, POST, OPTIONS } = createEditorApiHandler({
  getPages,
  onPublish,
  publishSecret: process.env.PUBLISH_TOKEN,
  maxPagesRemoved: 2,
})

• Only removals are counted, by comparing the incoming slugs against the baseline’s — so a publish that renames a slug spends one of the budget, even though the page is still there under its new slug. Added pages cost nothing.
• It is measured against getPages, so it is only enforceable when that read succeeds. An unreadable baseline means the bound cannot be applied at all.
• It never loosens the main rule. A publish removing every page is refused whatever maxPagesRemoved is set to.

​

Applying the rule to a hand-wired route

import { checkDestructivePublish } from "@avocadostudio-ai/site-sdk/routes"
// Outside Next:
// import { checkDestructivePublish } from "@avocadostudio-ai/site-sdk/routes/core"

const guard = checkDestructivePublish({
  next: body.pages,                       // what the publish would leave behind
  before: await getPages(),               // or undefined, if you cannot read it
  allowDelete: body.allowDelete === true,
  maxPagesRemoved: 2,                     // optional
})

if (guard.refused) {
  return Response.json(
    { ok: false, error: "refused", reason: guard.reason },
    { status: 409 }
  )
}

​

What the route answers

​

Git target

• Local development without a CMS
• “Git as your CMS” setups where content is checked into the repo
• Static sites where publishing means triggering a rebuild

PUBLISH_TARGET=git
PUBLISH_GIT_BRANCH=main               # branch to push to (default: main)
PUBLISH_GIT_STRICT=1                  # optional: abort if the working tree is dirty
PUBLISH_GIT_TOKEN=<token>             # or GITHUB_TOKEN, for the push
PUBLISH_GIT_AUTHOR_NAME="Avocado Studio"
PUBLISH_GIT_AUTHOR_EMAIL=publish@avocadostudio.ai

​

Deploy hook target

PUBLISH_TARGET=deploy-hook
VERCEL_DEPLOY_HOOK_URL=https://api.vercel.com/v1/integrations/deploy/...

​

Building a custom target

import type { PublishContext, PublishOutcome, PublishTarget } from "@avocadostudio-ai/orchestrator-core"

export class S3PublishTarget implements PublishTarget {
  readonly name = "s3"

  canHandle(ctx: PublishContext): boolean {
    return process.env.PUBLISH_TARGET === "s3"
  }

  async publish(ctx: PublishContext): Promise<PublishOutcome> {
    const now = new Date().toISOString()
    const key = `sites/${ctx.siteId}/content.json`
    await s3.putObject({ Bucket: BUCKET, Key: key, Body: JSON.stringify(ctx.pages) })
    return {
      ok: true,
      httpStatus: 200,
      tracker: {
        session: ctx.session,
        status: "triggered",
        startedAt: now,
        updatedAt: now,
        slugs: ctx.slugs,
      },
      response: { ok: true, slugs: ctx.slugs, bucket: BUCKET, key },
    }
  }
}

import { registerPublishTarget } from "@avocadostudio-ai/orchestrator-core"
registerPublishTarget(new S3PublishTarget())

​

A target that talks to a publish route must surface reason

reason: siteResult.reason ?? siteResult.error ?? "site publish failed"

​

Publishing a field-level diff

import { diffPage, groupPatches, describeUnsupported, sanityPaths } from "@avocadostudio-ai/site-sdk/publish"

const diff = diffPage({
  page,
  ctx: { lang: "fr" },
  paths: sanityPaths,                 // or indexPaths, or your own PathSyntax
  locate: (block) => {
    const source = sourceBlocks.get(block.id)
    if (!source) return null          // reported as unsupported, never skipped silently
    return {
      documentId: page.id,
      prefix: `pageBuilder[_key=="${block.id}"].`,
      specs: SPECS[block.type],       // per field: rehydrate(props, before, ctx), optional write
      source,
    }
  },
})

for (const { documentId, set } of groupPatches(diff.patches)) {
  await client.patch(documentId).set(set).commit()
}
return { ok: true, unsupported: describeUnsupported(diff.unsupported) }

• paths is required. sanityPaths addresses list rows by _key; indexPaths by position, which is correct only when the publish is the only writer. It used to default to Sanity’s form, which emitted _key patches against stores that have no _key.
• locate decides where a block writes. A block placed by a shared section can write to the section’s document rather than the page’s; return an array to split one block across several documents. Return null for a block with no upstream document — usually one the editor added — and it is reported as unsupported rather than dropped.
• Each field spec’s rehydrate undoes your projection, given the edited props and the value the CMS holds, so it can replace one key of a stored object and keep the rest. A write function can reject a change it cannot express.
• Compare against the right baseline. In library mode context.baseline is what the adapter last returned, recovered after a restart; see which baseline to diff against. The site contract’s onPublish gets no baseline, so read the source from the CMS.
• Strip Avocado’s row ids before any whole-object comparison. withoutGeneratedItemIds is exported from the same subpath. diffFields never sees them, because no spec declares id.

​

Publish status

{
  "status": "triggered" | "failed",
  "deploymentId": "dpl_abc123",
  "deployState": "BUILDING",
  "vercelState": "BUILDING",
  "inspectUrl": "https://vercel.com/...",
  "lastCheckError": null
}

​

Snapshots and rollback

• avocado-list-snapshots — list published snapshots with commit shas + timestamps
• avocado-restore-snapshot — rewind the draft to a specific snapshot (doesn’t trigger a republish; you publish again to push the rolled-back version live)
• avocado-compute-publish-diff — diff the current draft against the last published snapshot before publishing

​

See also

• CMS adapters — the site-side hooks the site-contract target calls into
• Architecture — where publishing fits in the orchestrator pipeline
• MCP server — Publishing tools — drive publishes from Claude Desktop