# One config, several sites

URL: https://kywi-docs-production.up.railway.app/developing/one-config-several-sites
Type: docPage

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', }), ],

## kywi.config.ts

## 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.

## The runtime’s siteId is the default site, not the request’s

The process-level `siteId` is `sites[0]`'s UUID, resolved once at boot. Keying a public query on it is what makes a multi-site app serve the first site's content on every domain. Every site-scoped read on the render path takes its `siteId` from the active-site lookup instead — core marks the few internal fallbacks that remain with a `DEFAULT-SITE FALLBACK` comment so they are greppable.

## 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](/developing/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](/operating/multi-site-the-domain-field-and-host-based-resolution/).

## Two things the config loader rejects, and one that never fires

Duplicate site `id`s and duplicate `domain`s 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.
