Skip to content

Upgrading core inside your project

Bump the packages, then run the upgrade command: a per-file hash decides what is replaced, refused or kept, and the refusals are the interesting ones.

Two steps, in this order. Bump the packages first — the generated files target the CLI's version, and generating them against an older installed core produces an advisory rather than a working project.

pnpm

pnpm add @kywi-software/core@latest @kywi-software/js@latest @kywi-software/cli@latest @kywi-software/mcp@latest

Then npx create-kywi-app@<version> upgrade --dry-run. The dry run is not a separate code path: it plans, applies, reports and computes the exit code exactly as the real run does, with the writes suppressed. Its report and its exit code are therefore the real ones, which is what makes "dry run clean before merging" a rule worth having.

The stamp decides everything

Every generated render file opens with // kywi-render v2 (create-kywi-app 0.23.0) sha256:…, hashing the bytes below that line with no normalisation — no whitespace forgiveness, no line-ending forgiveness. So the command never guesses whether a file is still its own output.

The report words

What each line of an upgrade report means for one file. Of these six per-file outcomes, only the two refusals — edited and unstamped — leave a file untouched and exit non-zero (2), and those are the two that need a decision from you.
NameTypeDefaultDescription
currentnothing written—

The file already equals the new emission.

replacedoverwritten, no backup—

The stamp is intact — or the file is unstamped but its whole-file hash matches a known historical emission, which is the same proof. Either way it holds no work of yours.

REFUSED (edited)left alone—

Stamped, hash differs. Someone changed it. Exit code 2.

REFUSED (unstamped)left alone—

No stamp and no known-emission match: hand-written, or from a scaffold too old to stamp. Exit code 2.

created / keptlayer files—

A sites/** layer file is written when a configured site has none — otherwise the project would not boot — and from that moment it is yours: never compared, never overwritten.

REFUSED (legacy) / removeddeleted under --force—

One of six pre-layered glue files whose contents now live in core. A stale copy shadows the real thing, so these are removed rather than replaced.

There is a third, coarser non-zero exit that never reaches this per-file table at all. When the config scan that regenerates the registry reports a problem — or the project cannot be read as a create-kywi-app project in the first place — the command writes nothing anywhere and exits 1, before a single file is decided. Exit 2 means "some files need your attention"; exit 1 means "the run never started."

A project that has stopped keeping a private copy of core's render path reports nothing but current and kept, and exits 0:

the shape to aim forbash
$ npx create-kywi-app@0.21.0 upgrade --dry-run
Upgrading kywi-marketing-v3 (coupled mode)…
  (dry run — nothing will be written)
  current: lib/kywi.ts
  current: middleware.ts
  current: app/(site)/layout.tsx
  current: app/(site)/[[...slug]]/page.tsx
  current: kywi.layers.ts
  current: app/api/v1/[...kywi]/route.ts
  current: app/llms.txt/route.ts
  current: app/llms-full.txt/route.ts
  current: app/sitemap.xml/route.ts
  current: app/robots.txt/route.ts
  current: app/admin/[[...admin]]/page.tsx
  kept: sites/default/index.ts
  kept: sites/default/themes/default/index.tsx
  kept: sites/northwind-analytics-demo/index.ts
  kept: sites/northwind-analytics-demo/themes/default/index.tsx
  note: AGENTS.md guidance is from create-kywi-app 0.15.1; run `create-kywi-app agents --force` to refresh.

✔ 0 created, 0 replaced, 11 current, 4 kept, 0 refused.

What --force does, and what it does not

--force converts refusals into writes, and copies every original into .kywi-upgrade/<timestamp>/ first. Nothing is destroyed, including the six legacy files it deletes. Files replaced without a refusal get no backup line — they were provably unmodified emissions. Add .kywi-upgrade/ to .gitignore; TypeScript already ignores it, because include globs skip dot-prefixed directories.

Three advisories, none of which change the exit code

An ejected artifact whose stamped core version has drifted from the installed one; an installed core on an older minor than the files being generated; and a stale AGENTS.md guidance stamp. All three are notes, so a clean exit code does not mean there is nothing to read.

Taking a component over: eject, not copy

Four of core's client components can become the project's: nav, frontEdit, personalizationRuntime and jsLoader. create-kywi-app eject <artifact> copies one into sites/<site>/themes/<theme>/ and wires it into that layer's templates, so the layer chain renders your copy. Built-in module renderers are not on the list, and an ejected file still carries comments written for core's internals. From the moment you eject, that file stops following core upgrades — which is the point and also the price.

Doing this against a deployed site — the migration, the ordering against a running database, the rollback — is Upgrading between minor versions. What the scaffold owns and what you own is What the scaffold generates.