The hosted Deco CMS

Your editors want a fix live without waiting for an application build, and they want to edit without cloning the repository. That's what the hosted Deco CMS is for: an optional service Deco runs on top of the same files. It changes how fast content reaches visitors and where editors work, not how your code is written.

Deco CMS is complete without it: your functions, your content files, your deploys and your own telemetry collector are all you need. This page shows what the hosted Deco CMS adds, what it doesn't do, and how to connect your site.

What it adds

Deco runs these services for a connected site:

What stays the same

• Your repository is the authoring source of truth. Content is still the JSON files in .deco/blocks, and every edit is still a commit. The delivery channel selects what visitors receive; a fast content rollback can temporarily select an older release without reverting Git.
• Your code doesn't change. Block functions, the block map, resolve, list and routing work the same way. The same createCMS call takes two more options, site and token.
• The content module stays. Your build still bundles the content module, .deco/blocks.gen.ts. A cold server uses that bundled content until its first successful release fetch. After that, an API outage leaves the newest successfully loaded release in memory; it does not revert the server to its bundled content. See Fallback.

What it doesn't do

• It doesn't run your app. Your app runs where you deploy it: Node, Cloudflare Workers or any other host you choose.
• It doesn't run your code. The Deco API serves content files; your servers call your functions. The site editor never runs your code either (see What works without your code).
• It doesn't build or deploy. Code still ships through your own pipeline; only content can skip the deploy.

Connect your site

A site is connected by two values: its site ID in the hosted Deco CMS and its site token. Read them from environment variables, by convention DECO_SITE and DECO_SITE_TOKEN, and pass them to createCMS next to your content:

import { createCMS } from "@decocms/blocks";
import blocks from "./.deco";
import content from "./.deco/blocks.gen";
 
const site = process.env.DECO_SITE;           // your site's ID in the hosted Deco CMS
const token = process.env.DECO_SITE_TOKEN;    // your site token (secret)
 
export const cms = createCMS({
  blocks,
  content,
  site,
  token,
  // Optional: also send telemetry to the hosted collector
  telemetry: site && token ? { site, token } : false,
});

The site ID isn't a secret; the token is, so keep it out of the repository. When either value is undefined, in development or in tests for example, the CMS reads content only, exactly like createCMS({ blocks, content }). So the same lines work everywhere, and a site keeps working if you disconnect it.

Local files win in development. In your dev server, even with both values set (in .env.local or .dev.vars), ordinary requests read your local .deco/blocks, not the published release, so your edits and the site editor's saves through deco serve show up right away. A ?__draft= link still loads that draft from the Deco API.

site and token load releases and drafts, nothing else. Telemetry is separate and opt-in: it goes only where the telemetry option points, so pass the same two values there to use the hosted collector, or point it at your own collector instead. Drafts need a few lines of wiring in your app; see Wire drafts into your app. How often servers check for a release is the interval option of createCMS; see Check interval.

Next.js

Set DECO_SITE and DECO_SITE_TOKEN in your host's environment (and in .env.local, which you keep out of Git, to try it locally). Create the CMS in a module that starts with import "server-only", or import it only from one that does, as the Next.js guide does: the build then fails if a Client Component imports it, which keeps the token out of the browser.

Cloudflare Workers

On Workers, environment variables come from env in cloudflare:workers:

import { createCMS } from "@decocms/blocks";
import { env } from "cloudflare:workers";
import blocks from "../.deco";
import content from "../.deco/blocks.gen";
 
export const cms = createCMS({
  blocks,
  content,
  site: env.DECO_SITE,
  token: env.DECO_SITE_TOKEN,
  telemetry: { site: env.DECO_SITE, token: env.DECO_SITE_TOKEN },   // optional: the hosted collector
});

Locally, wrangler dev reads them from a .dev.vars file you keep out of Git. In production, set the site ID as a plain variable in wrangler.jsonc (vars) and the token as a secret:

npx wrangler secret put DECO_SITE_TOKEN

Release checks on Workers run after the response, inside ctx.waitUntil, on their own; see How a commit becomes a release. Sites with several megabytes of content should read Large content on Workers.

Terms

Site ID and site token

The two values that connect your app to the hosted Deco CMS, usually the DECO_SITE and DECO_SITE_TOKEN environment variables, passed to createCMS as site and token. They load releases and drafts. Passed under telemetry too, they send telemetry to the hosted collector. Only the token is secret.

Deco API

The delivery service that serves prepared release and draft assets from storage/CDN. It never reads GitHub in response to a production content request.

Hosted collector

The hosted Deco CMS's endpoint for telemetry, used when telemetry is { site, token } (see Hosted telemetry), and for page views, analytics' default collector.

Release

A release as the Deco API serves it: the content of one commit to your production branch, live without a deploy. See Publishing without a deploy.

Draft pointer

The string the site editor puts in a ?__draft= link: where a draft lives on the Deco API, with a token the site editor signed, and which version. cms.forDraft(pointer) reads it. See Previewing drafts.

Draft branch

The branch the site editor's GitHub backend commits an editor's saves to, created on the first save. Publishing brings it to your production branch. See Editing in the site editor on GitHub.

On these pages

• Site editor on GitHub: draft branches, uploads in hosted storage, publishing, and CI on the site editor's commits.
• Previewing drafts: the ?__draft= link, wiring drafts into your app, and who may preview.
• Publishing without a deploy: how a commit becomes a release, how servers pick it up, the fallback, and keeping running code compatible with new content.
• Production delivery and rollback: immutable assets, channel promotion, outage behavior and restoring an older release.
• Keeping drafts current: automatic production updates, conflict resolution and bounded merge memory.
• Hosted telemetry: turning on the hosted collector for telemetry.