One config, several sites
Sites are matched per request by Host header and reconciled into their database rows by slug at boot, so a new domain is a config edit plus a layer entry.
A second site is three edits to one project: an entry in sites, a theme that entry names, and a regenerated layer registry. One app process, one database, one deploy — what differs per request is the Host header.
sites: [
defineSite({
id: 'default',
name: 'kywi-marketing-v3',
domain: 'kywi-marketing-production.up.railway.app',
domainAliases: ['localhost', '127.0.0.1'],
defaultLocale: 'en',
theme: 'default',
}),
defineSite({
id: 'docs',
name: 'Kywi Docs',
domain: 'docs.kywi.dev',
domainAliases: ['docs.localhost', 'kywi-docs-production.up.railway.app'],
defaultLocale: 'en',
theme: 'docs',
}),
],The layer registry is generated from your config
kywi.layers.ts enumerates the sites this config declares, so it is regenerated by create-kywi-app upgrade from a scan of kywi.config.ts — never hand-written. The same command creates sites/<id>/ and sites/<id>/themes/<theme>/ for a configured site that has no layer yet, then leaves those files alone forever; it never touches kywi.config.ts, lib/modules.tsx or anything else you own. A theme layer lives under its site, so two sites both using the name default are two different modules, not one.
The registry is asserted against the config at module load — build time, not request time — so a config edit without a regenerate fails the build with one of two lines:
kywi.layers.ts is stale: configured site "docs" is missing from the generated registry.
kywi.layers.ts is stale: site "docs" references theme "docs" but the registry does not import it.Which site a request is for
The active site is resolved from the request's Host header and memoised in a React cache(), so every helper on one render shares a single lookup. Matching tries the site's domain first, then its domainAliases, against URL.hostname — which drops any :port, and is why two hosts on one dev server work with no DNS at all. A Host that matches nothing falls back to sites[0], and a malformed one is caught: a visitor behind a broken proxy sees the first site, never a 500.
Do not reach for x-kywi-url instead. In development it carries the server's own bound origin, which defeats host routing entirely.
Config owns four columns of the site row
A configured site's kywi_sites row is reconciled by slug — the row's slug is the config id — at boot and again during kywi migrate. A missing row is created along with a published home page, so a newly declared site's / renders immediately rather than 404ing until someone opens the admin.
Which four columns, what happens to an admin edit of them, and why an orphaned row is reported rather than deleted are the general config-vs-database rule, not something specific to sites — see Config-as-code vs. the database.
Boot-time reconciliation is best-effort — a read-only role logs one line and the app keeps serving the sites that do have rows. kywi migrate runs the identical reconcile, which is what converges a deploy whose app process cannot write; see Multi-site: the domain field and host-based resolution.
Two things the config loader rejects, and one that never fires
Duplicate site ids and duplicate domains are both config-load errors: the first makes the slug-to-UUID map ambiguous, the second makes Host-to-site routing non-deterministic.
pathPrefix is accepted by the type and the validator, and the resolver has a branch for it — and that branch is reachable, just not from the public page render. Public-page resolution always calls the resolver with a pathname of /, so there the prefix branch cannot match. The API layer is different: every route built on resolveSiteContext (experiments, AX, audiences, audience preview) resolves the request's real pathname, so a configured pathPrefix genuinely can select a site there. It still cannot disambiguate two sites on one host, though — the config schema rejects a duplicate domain outright, so no arrangement exists for a prefix to resolve. Serve a second site on its own host, not on a path.
Adding or changing a domainAliases entry is a config-only edit, not a database change: it takes effect at the next boot with no row written and no kywi migrate involved, for the same reason config-owned values in general do.