Skip to content

The three deployment modes

Three deployment modes differ only in which public-render files the scaffold emits — core never branches on `mode` at runtime.

mode is a required field on kywi.config.ts, and it is the scaffold's question, not the server's. It decides which files create-kywi-app writes into your project. Nothing in core reads it to decide how a request is handled.

kywi.config.tsts
export default defineKywiConfig({
  // Deployment mode:
  //   'coupled'   — this app renders the public site AND serves the API + admin.
  //   'headless'  — API + admin only; no public rendering (GET / is 404).
  //   'decoupled' — API + admin here; a separate frontend consumes @kywi-software/sdk.
  mode: 'decoupled',
  // …

What mode does not do

Core reads config.mode in exactly three places, and all three only hand the value back: the config-introspection JSON, the admin's runtime config, and the read-only Deployment mode row on the site settings screen. No route, no middleware, no render path branches on it. Editing the field in a running project changes one line of admin chrome and nothing else — in particular, flipping headless to coupled does not make anything render, because the files that would render it were never written.

What it decided, once

Every mode gets the same admin catch-all, the same app/api/v1/[...kywi]/route.ts, the same middleware, the same layer registry, and the same four AX root routes (llms.txt, llms-full.txt, sitemap.xml, robots.txt). Coupled adds the public render path on top; headless and decoupled add one file that refuses to render.

text
coupled                              headless / decoupled
──────────────────────────────────   ──────────────────────────────────
app/(site)/layout.tsx                app/page.tsx  → notFound()
app/(site)/[[...slug]]/page.tsx
app/(site)/site.css
components/site-nav.tsx
scripts/sync-kywi-admin-css.mjs

sites/<id>/themes/<theme>/index.tsx  sites/<id>/themes/<theme>/index.tsx
  templates = { nav: SiteNav }        templates = {}

The theme layer follows from the same branch: a non-coupled scaffold exports an empty templates map, because the nav template it would otherwise name lives in the coupled-only components/site-nav.tsx. A theme you write later against a headless project has no rendering host to hang templates on.

Headless and decoupled emit the same project

The two non-coupled modes produce an identical file set; four of those files differ only by the mode string inside them. kywi.config.ts records it in the config object, app/page.tsx's comment and not-found note name it, AGENTS.md states it in one sentence, and README.md does so twice — once in its opening description, and again in a Separate frontend heading that decoupled alone gets, with a createKywiSdk snippet pointed at /api/v1. The distinction is a statement of intent for whoever reads the repo next — headless means nothing is planned to consume it as a site, decoupled means something is. Choose either and you can change your mind by editing prose.

Changing the field later

create-kywi-app upgrade works out which mode a project is by regex over kywi.config.ts — it looks for a quoted coupled, headless or decoupled after mode:. When it matches nothing it assumes coupled and says so, then regenerates the layer files on that assumption. So the field is worth keeping literal and on one line: a value assembled from a variable or an env lookup reads as absent, and your headless project gets upgraded as if it rendered pages.

Switching modes for real is a file operation, not a config edit. Going coupled means adding the five render-path files and re-pointing the theme layer's templates; going headless means deleting app/(site) and components/site-nav.tsx and adding the 404 home page. See What the scaffold generates for what each of those files is, and Rendering a page in coupled mode for what the coupled path actually does.

Which mode you want

The choice is about where HTML is produced, and it constrains less than it looks like it does — but the one thing it cannot buy you is a browser-side integration. A separate frontend consumes the API from its server: see Topologies that work — and the cross-origin wall before you design around a decoupled deployment, and Coupled, headless, decoupled for the version of this decision you make before scaffolding.