Site Editor and the v7 admin protocol

The Site Editor is the storefront editing app hosted by Deco Studio. It uses the site's metadata and preview endpoints alongside repository-backed content editing. The 7.x runtime also exposes a small set of HTTP endpoints, called the admin protocol, for compatible clients to read schemas and content, render previews, invoke loaders and reload content. This page lists those endpoints, shows how each binding mounts them, and covers the settings that affect what editors see.

Site Editor

The storefront editing app in Studio. It combines site metadata and previews with repository-backed content edits and a GitHub publish workflow. See the glossary.

Admin protocol

The v7 site's HTTP contract for compatible editor and delivery clients. See the glossary.

Render shell

The HTML document previews render inside: your stylesheet, fonts and theme.

The v7 runtime contract

Editor clients can load the site in an iframe and call these endpoints from a browser, so the handlers include CORS headers. Current Studio content saving and publishing follow the repository workflow described above; mounting these handlers does not connect a repository or configure deployment. All the handlers come from @decocms/blocks-admin; the bindings mount them for you.

The endpoints

Page previews evaluate matchers against the path and device Studio is previewing (?path=, ?deviceHint=mobile), and run section loaders, so the preview shows real data. Each previewed section is wrapped in a <section data-manifest-key="…"> so Studio can map clicks back to blocks. Errors render inline in the preview rather than failing the request.

Publishing

An authorized runtime client can reload content with POST /.decofile. This endpoint does not commit content to Git or run Studio's Publish workflow. Its body is one of two shapes:

• A delta: an object whose only key is blocks, holding the changed blocks. A null value deletes that block.

  { "blocks": { "Header": { "__resolveType": "site/sections/Header/Header.tsx", "logo": "https://www.example.com/logo-v2.svg" }, "pages-old-sale": null } }

• A full decofile: any other object replaces all content.

The site applies it with setBlocks, clears its loader cache, invalidates the schema ETag, and, with Fast Deploy, writes the snapshot to KV. It answers:

Outside development, this runtime reload endpoint requires a token. Set DECO_RELEASE_RELOAD_TOKEN in the site's environment, and the request's Authorization header must equal it exactly. Without the variable, every runtime reload request is refused with 401. In development (NODE_ENV=development) no token is needed, which is how the TanStack dev server applies your local block edits.

In TanStack Start

The endpoints are split between the Worker entry and three file routes.

createDecoWorkerEntry handles /live/_meta, /.decofile, /live/previews and /live/previews/*, and /deco/_liveness, when you pass the handlers as its admin option. These responses are never cached.

import {
  corsHeaders,
  handleDecofileRead,
  handleDecofileReload,
  handleMeta,
  handleRender,
} from "@decocms/blocks-admin";
 
export default createDecoWorkerEntry(serverEntry, {
  admin: { handleMeta, handleDecofileRead, handleDecofileReload, handleRender, corsHeaders },
});

The file routes src/routes/deco/meta.ts, src/routes/deco/invoke.$.ts and src/routes/deco/render.ts serve the rest, using decoMetaRouteConfig(), decoInvokeRouteConfig() and decoRenderRouteConfig(). Call each factory in its own route file. The quickstart has all three.

In Next.js

One catch-all route, app/deco/[[...deco]]/route.ts with createDecoRouteHandlers({ setup }), serves every endpoint. withDeco in next.config rewrites the public paths onto it, because Next.js route folders can't start with a dot:

Preview GETs redirect to the fixed page /deco/preview, rendered by createDecoPreviewPage, so Client Components work in previews; see Previews and draft preview. On Next.js, /deco/meta accepts only GET and /deco/invoke only POST. The Next.js quickstart shows both files.

What previews look like

Previews render your sections outside your app's normal layout, so you tell the admin side what the surrounding document needs. On TanStack, createAdminSetup from @decocms/blocks-admin/setup takes:

On Next.js, the same settings are createNextSetup's meta, renderShell: { css, fonts } and previewWrapper.

For anything else about the shell, call setRenderShell from @decocms/blocks-admin in setup. It takes css, fonts, theme (the data-theme attribute), bodyClass and lang. If your styles use DaisyUI color variables, set the theme, or previews render without colors:

import { setRenderShell } from "@decocms/blocks-admin";
 
setRenderShell({ theme: "light" });

The Next.js preview page already defaults the theme to light.

Live controls

DecoRootLayout (in both bindings) renders LiveControls, a small script that lets Studio and the page talk while the page is in Studio's frame: it reports which page is open and responds to editor messages. Outside Studio it also adds a shortcut: press . on your site to open it in Studio (Ctrl/⌘ + . for a new tab).

CORS and framing

Studio calls the admin endpoints from the browser, so they answer with CORS headers that allow GET, POST and OPTIONS and the Content-Type, Authorization and If-None-Match headers. On Next.js, OPTIONS preflights are answered without running setup.

Studio also shows your pages in a frame. On TanStack, HTML responses carry a frame-ancestors policy that lets Deco's Studio frame your pages; see TanStack Start on Cloudflare Workers to change the security headers.

Next steps

• Schema generation: what /live/_meta contains.
• Previews and draft preview: previews in depth, and drafts on the real site.
• Deploying and Fast Deploy: making publishes durable in production.

Current editor implementation reference: Studio publish flow. Reviewed 2026-10-05.