Seeding structure as code
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 })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.
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 remotelySet 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.
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 covers the same boundary from the agent's side, and Seeding and demo-data commands the operator's.