# Seeding structure as code

URL: https://kywi-docs-production.up.railway.app/developing/seeding-structure-as-code
Type: docPage

Structure that must be reproducible — types, pages, layouts, menus, media — is written by idempotent scripts against the API, never by copying rows.

`kywi seed` gives you four rows: a default site, a superadmin user, an "Administrators" group with that user in it, and the root content node. It is the floor, not the mechanism. Types, pages, layouts, menus, feeds, audiences and the media they reference are the project's own scripts, and they are how a site gets rebuilt on an empty database without anyone copying rows between environments.

## A page is a layout document, not a component

A page script assembles `{ regions: { main: [ … ] } }` and PUTs it. What ships is content — the same document the admin's Layout tab and the front-of-site overlay editor open — so the owner can restructure it afterwards without touching the script. A page written as JSX cannot be edited by the person the CMS is for, which is the whole reason not to write one.

import { band, buildPage, component, layout, loadComponents, mediaIds, mod, resetIds, withSite } from './_lib.mjs' const S = 'visual-editing' // the page slug; every node id derives from it function spec({ media }) { return { slug: S, title: 'Visual editing', isNav: true, seo: { title: '…', description: '…' }, layout: layout([ band(S, 'none', mod(S, 'splitFeature', { image: media['front-edit-selected'], /* every other prop, explicitly */ })), band(S, 'none', mod(S, 'heading', { text: '…', level: 'h2' })), component(S, 'final-cta'), // every page ends with this ]), } } async function main() { resetIds() await loadComponents() await withSite(async (site) => { const media = await mediaIds(site) // run scripts/pages/media.mjs first await buildPage(site, spec({ media })) }) } main().catch((e) => { console.error(e); process.exitCode = 1 })

## scripts/pages/<new-page>.mjs — the README’s skeleton shape

## Idempotence is the constraint, not a nicety

Node ids are derived from a per-page, per-tag counter rather than generated, so building the same page twice stores a **byte-identical** document. That is what buys you a re-runnable corpus: no churn in the component instance index, no orphaned responsive-style selectors, no duplicate pages or components accumulating every time someone re-runs the build. A script that generates ids is not idempotent no matter how carefully it upserts.

## Seed media before every page script, not once

Every `image` prop is resolved *by filename*, at build time, against whatever the Media library holds at that moment — there is no id baked into the script to fall back on. So the media step runs immediately before each page script, not once at the start of the day. It is idempotent, and re-running it is the fix both for a page script that throws about a missing library entry and for a page rendering a 404'd image. It is also the repair path for a restored database whose upload volume came up empty: the media step deletes the rows whose files 404, re-uploads them, and the page scripts that follow repoint every layout at the new ids.

## The same scripts, against a deployed site

Nothing about the target is hardcoded, so production seeding is the same commands with a different environment. Two URLs, not one: the scripts reach the site over REST with an admin token *and* over an MCP stdio subprocess, and those read different variables.

export BASE_URL=https://your-site.example.com # REST: adminApi / adminList / media checks export KYWI_API_URL=https://your-site.example.com/api/v1 # the MCP subprocess's REST calls export KYWI_MCP_API_KEY=... # the site's MCP API key export ADMIN_EMAIL=... # defaults to admin@kywi.dev export ADMIN_PASSWORD=... # defaults to admin123 — never rely on that remotely

Set only `BASE_URL` and the failure is silent in the worst direction: REST writes land on the remote site while every MCP call keeps talking to `localhost:3000`, so the run "succeeds" and the deployed site is half built.

## Pass ?siteId= on every site-scoped call

The content and trash route family still resolves the first configured site when the query parameter is absent. A seeding script for a second site that omits it does not fail — it writes to site one. Append it to every call rather than to the ones you think need it; that is the only version of this rule that survives someone adding a request later. See [Site scoping and the siteId contract](/integrating/site-scoping-and-the-siteid-contract/).

## What belongs in a script

Structure that must be reproducible on a fresh database: the content model, the pages that carry the information architecture, menus, feeds, the media those pages reference. Not the things an editor owns from day one — a re-run of a script is an overwrite of live content, and a script that owns a page the marketing team also edits will eventually delete their work. If a page will be edited in the admin after launch, create it there and let the script stop at the structure around it. [Layout writes an agent can and can't reach](/agent/layout-writes-an-agent-can-and-cant-reach/) covers the same boundary from the agent's side, and [Seeding and demo-data commands](/operating/seeding-and-demo-data-commands/) the operator's.
