# The local dev loop

URL: https://kywi-docs-production.up.railway.app/developing/the-local-dev-loop
Type: docPage

Config edits need a restart and content edits do not, and two predev sync steps copy the browser runtime and the admin stylesheet into public/.

The useful split is not "server vs client" but *config vs database*. The config is a module the app imports, so anything you change in `kywi.config.ts` — a site, a theme, a content type, the `ax` block — needs a restart. Everything the database owns is live: a content type added in the Type Designer rebuilds core's schema maps in place, and the route handlers that captured those maps at registration see the new type on the next request. No restart, and no way to tell from the outside that anything reloaded.

## Two sync steps write into public/

Neither the admin stylesheet nor the browser runtime is served from `node_modules`: both are copied into `public/` by scripts that run before `dev` and `build`. Start the server some other way — `next dev` directly, a Dockerfile that skips lifecycle scripts — and you get a stale admin, or a public site whose nav and personalization runtime never load.

## package.json

## The scaffold only wires up the first of the two

A fresh project's `predev` and `prebuild` run `sync:kywi-admin-css` and nothing else — there is no `sync:runtime` script to chain. If your theme sets `clientRuntime`, or your site renders a header menu, add the copy step yourself and put it in `predev` and in `build`; the block above is a project that did. The symptom without it is a 404 on `/kywi.js`, on a site that server-renders correctly.

`/kywi.js` is requested whenever the shell renders a non-empty header menu — the same condition the nav itself renders on, since the script is what gives the nav its hover-intent and keyboard behaviour. The personalization runtime asks for the same file through a shared dedupe, so a page with both loads it once.

## There is no cache to clear for a content change

The generated site routes export `dynamic = 'force-dynamic'`, because a renamed page or a reordered menu has to appear without a rebuild. If a content edit is not showing up, the cause is upstream of Next — the wrong site resolved, a draft you have not published — not a stale route. The literal is written into the generated file rather than re-exported from the constructor: Next parses route segment config statically and fails the build on anything else, which is why that line looks redundant and is not.

## A second site is a Host, not a path

Site selection reads the `Host` header. `URL.hostname` drops the port, so a site whose `domain` or `domainAliases` include `docs.localhost` matches `docs.localhost:3800` — a two-host dev server with no DNS and no hosts-file entry. A path prefix will not select a site, and neither will `x-kywi-url`: in dev that header carries the server's own bound origin, which defeats host routing entirely.

# kywi.config.ts — the second site's aliases # domainAliases: ['docs.localhost', 'docs.127.0.0.1.nip.io', 'kywi-docs-production.up.railway.app'] curl -s localhost:3000/ # the first site curl -s -H 'Host: docs.localhost' localhost:3000/ # the second, same server

## one dev server, two sites

## fetch() cannot do this

`Host` is a forbidden header name, so a Node script written with `fetch()` silently talks to the default site no matter what you put in `headers`. Use `node:http` (or `curl`) in any script that has to reach a second site locally. See [Multi-site: the domain field and host-based resolution](/operating/multi-site-the-domain-field-and-host-based-resolution/).

## When the site comes up unstyled

In development the layout renders a hidden sentinel before the shell, ahead of anything a theme supplies: core's guard against a project that has lost core's stylesheet — a failure that otherwise looks like a CSS bug and gets debugged as one. It is gated on `NODE_ENV` and never reaches production. Which stylesheet should load, and in what order, is [The stylesheet layers of a Kywi project](/developing/the-stylesheet-layers-of-a-kywi-project/).

## From an empty database

pnpm exec kywi migrate # schema pnpm exec kywi seed # default site + superadmin + the root content node pnpm dev

`seed` gives you exactly those three rows; everything above that — types, pages, menus, media — is [yours to script](/developing/seeding-structure-as-code/). Note that `seed` imports your config directly rather than parsing it, so it will happily run against a config the app would refuse to boot on; a clean seed is not evidence the config is valid. Running migrations anywhere that has data is [an operating concern](/operating/running-migrations-against-a-live-database/).
