Skip to content
decodecodeveloper docs
Storefront → Blocks → Built on Blocks

Site editor

Your merchandising team wants to swap the home page hero image for the weekend and fix a typo in the footer, and none of them opens a code editor. The site editor is Deco CMS's content editor: it shows the form deco schema built from each block's types, next to a preview of your running dev app, and saves each change back to the block's JSON file.

This page describes the proposed Next integration contract: generated schemas and saved blocks are read through the content protocol. For a released 7.x website, use the current Site Editor connection guide and its Git pull-request publishing workflow. The local workflow and CLI examples below describe the Next design, rather than a replacement setup for a current 7.x site.

What the site editor is

The site editor is part of Deco Studio: a web app with a form for each block. The forms come from your schema, .deco/schema.gen.json (see Forms from types), so they only accept values your functions can take. Every save writes a saved block, a JSON file in .deco/blocks: the same file you could edit by hand or ask an AI agent to edit.

The site editor never runs your code. It needs only two things, both files in your repository: the saved blocks and the schema, which your predev script writes (see Run it before dev and build). It reads and writes them through the content protocol.

Edit on your machine

The site editor runs at /site-editor in Deco Studio. It needs no account and works whether you're signed in or not. It opens in Studio's app layout, with the same Preview and Content tabs as the site editor inside a project: Preview shows your running dev app, Content holds the forms. Signed in, the sidebar lists your organizations; signed out, it's the same layout without them. Hosted features, such as publishing, releases and the GitHub backend, aren't there. If you're signed in, you can also pick "localhost" in a project's draft environment selector, which previews the same app.

The proposed local editing workflow for a Next app is:

  1. Start your app's dev server.

  2. Run npx @decocms/blocks serve. It finds the nearest .deco/ (or takes --root) and prints a link to the site editor:

    Deco server          http://localhost:4545/rpc
Root                 apps/storefront   (.deco/schema.gen.json, 214 blocks)
Assets               apps/storefront/public/assets   (PUT /assets/<name>)
Preview              http://localhost:5173
Site editor          https://studio.decocms.com/site-editor#endpoint=http%3A%2F%2Flocalhost%3A4545%2Frpc

  3. Open the link. The Preview tab loads the address printed as Preview: the port from your Vite config, else http://localhost:5173. If your app runs elsewhere, pass it, such as npx @decocms/blocks serve --preview localhost:8001.

  4. The first time, Chrome asks whether the site editor may reach a server on your machine (Local Network Access). Allow it.

Each save writes .deco/blocks and your app hot-reloads. The server regenerates the content module after every save, so you don't need deco content --watch as well. Nothing is committed: review the diff and commit it like any other change. The server listens only on your machine, but it has no authentication and answers any website open in your browser, so run it only while you're editing and stop it when you're done; --host also exposes it to your network (see The local server). The site editor remembers the server, so opening /site-editor again reconnects to it, and if you restart deco serve it waits for the server and reconnects on its own. Its flags, such as --port and --preview, are in the CLI reference.

Images and other uploads

When an editor uploads an image or another file in the site editor, deco serve writes it into your repository, in public/assets/, and the field stores the file's path, such as /assets/summer-banner.jpg. Uploads are ordinary files: you review them and commit them with the rest of your content.

Vite, TanStack Start and Next.js all serve public/ at the site root, so uploads are served at /assets/, in development and in production, with no configuration. The folder is relative to the folder that contains .deco, so in a monorepo it's your app's own public/. To write uploads somewhere else, pass --assets <dir>; the field still stores /assets/<name>, so your app has to serve that folder at /assets/.

With Vite, public/assets/ ends up in the same dist/assets/ folder as the build's hashed JavaScript and CSS. That's safe: the server never reuses a file name, so hosts that cache /assets/* for a long time serve it correctly.

Uploads make your repository bigger: every clone carries every image, and a replaced image stays in the history. Resize and compress images before you upload them, and link large media such as video from wherever you host it.

What works without your code

Because the site editor never runs your code, a few things that depend on it work differently:

  • Block previews: clicking a block's preview opens your dev app at that page. Gallery cards show the block's name, plus the @title, description and @image set in its JSDoc (see Widgets).
  • Pickers whose options come from your code show the options written into the schema, otherwise a text field (see Widgets).
  • Secret fields are write-only: the site editor encrypts what an editor types with your public key, .deco/secrets.pub, and never shows the saved value (see Secrets).
  • Fetching data and installing apps from the site editor: older Deco sites could run data loaders and install commerce apps from the site editor; here those live in your code. Add platform clients in code (see Calling APIs). These are different from content loaders, which deliver your saved blocks.

Settings

The site editor's Settings entry opens your site's CMS settings: one form with the hosts previews are allowed on, the telemetry switches and sample rates, and where analytics sends page views. Until someone saves it, the form shows the defaults, and the first save creates .deco/blocks/CMS.json. It's an ordinary saved block, so the change ships like any other content, and you can review it in the diff.

Settings take effect from the release, not from a draft: previewing a draft never changes its own preview hosts, telemetry or analytics. What code allows still wins, such as the highest sample rates or the hosts previews may ever use (see Allow previews per host).

Saved blocks and variants in the site editor

  • Saved blocks: a field that takes a block offers the saved blocks whose function returns the field's type. Picking one stores a reference, so editing it updates every place that uses it (see Reuse a block).
  • Variants: any field can have variants, each with a rule such as a date range, and the site editor writes the multivariate block for you (see Matchers and variants).