Walkthrough, customize your starter app

If you ran the Quickstart, you already have a running app with a Tasks list in the sidebar. This walkthrough explains what the starter generated and how to change it. If you customized it in Make it yours, those changes stay in place.

Already scaffolded?

If you still have your Quickstart app (my-app/), reuse it, skip Step 1 and jump to Step 2.

What the starter includes. kumiko new app scaffolds a demo tasks feature: entity, CRUD handlers, list + edit screens, sidebar nav, and seeded rows. You declare the shape once; Kumiko derives the table, API, access rules, and admin UI.

At the end you understand:

• which files the scaffold created and what each does
• how the tasks feature wires entity → handlers → screens → nav
• how to add a field and see it in the UI after bun dev

Prerequisite: Bun ≥ 1.2.20. Follow the Quickstart first if you do not have ./my-tasks/ yet.

Step 1, Scaffold (or use your Quickstart app)

bunx @cosmicdrift/kumiko-cli@latest new app my-tasks
cd my-tasks
bun install

The workspace includes src/features/tasks/feature.ts (full demo feature), src/seed.ts (demo rows for bun dev), bin/dev.ts, src/client.tsx, .env.example, and docker-compose.yml.

src/run-config.ts mounts secrets, sessions, and tasksFeature. config, user, tenant, and auth-email-password are auto-mounted by composeFeatures because bin/main.ts passes auth: { admin: { … } }.

Step 2, Configure env + boot validation

cp .env.example .env

Set in .env:

JWT_SECRET=$(openssl rand -base64 32)
KUMIKO_SECRETS_MASTER_KEY_V1=$(openssl rand -base64 32)

Then validate without a database:

bun run boot

[runProdApp] boot validation OK (8 features, 8 registry entries)

That’s KUMIKO_DRY_RUN_ENV=boot: every feature mounted, dependencies resolved, schemas validated, no Postgres or Redis.

Step 3, See it in the browser

docker compose up -d
bun dev

The welcome banner prints the URL (default http://localhost:4173) and admin login. Sign in as [email protected] / changeme, open Tasks, demo rows are already there:

See it live

Watch for three things: the sidebar nav entry, the sortable list columns, and a new row appearing over SSE when you create a task, all from feature.ts, no hand-written React.

What just happened

File	What it does
src/run-config.ts	Which features your app mounts (APP_FEATURES).
src/features/tasks/feature.ts	Entity + handlers + screens + nav for the demo.
src/seed.ts	Inserts demo tasks on first bun dev (idempotent).
bin/dev.ts	Dev server + welcome banner + seeds: [seedDemoTasks].
bin/main.ts	Production bootstrap (bun run start).

Step 4, Customize the starter feature

Open src/features/tasks/feature.ts. The starter already declares:

• taskEntity, fields (title, status, priority, isUrgent)
• CRUD handlers, defineEntity*Handler for create/update/delete/list/detail
• listScreen + editScreen, generated admin UI definitions
• r.nav(...), sidebar entries pointing at those screens

One field change

Add a notes text field below, save, let bun --watch reboot, and the new column appears in the list. That’s schema-driven UI in one edit.

Add a notes text field to see schema-driven UI updates:

// In taskEntity.fields:
notes: createTextField(),

Add "notes" to listScreen.columns and editScreen.layout.sections[0].fields. Save, bun --watch reboots and the new column appears (dev mode auto-creates the column; production needs bun run schema:generate).

Re-run boot to confirm composition still validates:

bun run boot

Step 5, Add another feature

The starter’s tasks feature is yours to edit or delete. For a second domain feature, use the CLI (scaffolds a bare entity, add screens when you need UI):

bunx @cosmicdrift/kumiko-cli add feature notes

This creates src/features/notes/ and auto-mounts it in src/run-config.ts.

Next steps

• Mount bundled features (audit, delivery, tier-engine, …) in src/run-config.ts.
• What you get, full capability tour.
• Concepts, why Kumiko works the way it does.
• Patterns, complete r.* API reference.

Generated screenshots

The images above come from the ui-walkthrough sample’s Playwright runner, same tasks shape as the starter, so they stay in sync with the framework.

If something does not match this doc, open an issue.