Environment variables — every value a cmssy app reads

A cmssy app reads two kinds of value: what the workspace gives you, and what your own app decides. Keeping them apart is the whole of this page.

Required

Copy these from Settings → Headless in the dashboard, or let npx @cmssy/cli link write them into .env.local for you.

Variable	What it is
`CMSSY_ORG_SLUG`	Your organization slug. It sits in the delivery path, which is why a workspace slug only has to be unique within its org.
`CMSSY_WORKSPACE_SLUG`	The workspace whose content this app renders.
`CMSSY_DRAFT_SECRET`	Guards draft preview and edit mode. Generated per workspace - not a string you invent.

Pass them to defineCmssyConfig raw. A ?? "" fallback turns a missing variable into an empty one, and the failure then surfaces somewhere unrelated.

Optional, and when you need them

Variable	When
`CMSSY_API_TOKEN`	A `cs_` token. Required for the `?cmssyDev=1` dev-draft overlay, and read by `cmssy link`. Development only - leaving it set does not change what visitors see.
`CMSSY_API_URL`	Delivery endpoint override. Defaults to `https://api.cmssy.io`; set it only for self-hosting or a staging backend.
`CMSSY_EDITOR_ORIGIN`	The admin origin allowed to frame your site. Defaults to cmssy cloud; set it only if you self-host the admin, because it drives both the postMessage bridge and the CSP `frame-ancestors`.

Yours, not the CMS's

These are not cmssy settings. cmssy stores canonical content and never your domain, your analytics IDs or your route secrets.

Variable	What it is
`CMSSY_REVALIDATE_SECRET`	Guards your own `/api/revalidate` route. You invent the value and give the same one to the `content.changed` webhook - see webhooks.
`NEXT_PUBLIC_SITE_URL`	Your public origin. Canonical URLs, hreflang alternates and the sitemap are built from it.
`NEXT_PUBLIC_GA_ID`, `NEXT_PUBLIC_GTM_ID`	Analytics and tag manager. Guard on them so preview deployments and local runs stay out of your numbers - see scripts.

Server-only means server-only

Every CMSSY_* variable above is server-side. Next only ships NEXT_PUBLIC_* to the browser, so a client component that reads the config does not get a misconfigured value - it gets a missing one.

That is the failure people meet: defineCmssyConfig throwing about missing variables when the variables are set correctly. The cause is an import, not the environment - a "use client" component pulled a value out of a module that reads the config. Types are fine, they are erased. Values drag process.env into the bundle.

Keep secrets out of version control, and set the same variables in your host (Vercel project settings, or equivalent) for production.

Next steps

Installation - where these first get used.
Draft preview - what the draft secret and the API token actually unlock.
CLI - cmssy link writes the required three and verifies them.