Skip to content

The local dev loop

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.jsonjson
{
  "scripts": {
    "dev": "next dev",
    "build": "pnpm sync:runtime && next build",
    "sync:kywi-admin-css": "node scripts/sync-kywi-admin-css.mjs",
    "predev": "pnpm sync:kywi-admin-css && pnpm sync:runtime",
    "prebuild": "pnpm sync:kywi-admin-css",
    "sync:runtime": "node -e \"require('fs').copyFileSync('node_modules/@kywi-software/js/dist/kywi.js','public/kywi.js')\""
  }
}

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

one dev server, two sitesbash
# 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

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.

From an empty database

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