Authoring Guide · Getting Started

Versions and upgrades

How create-kb versions work, why 1.2 sites stay safe when 2.0 ships, and how to migrate when you choose to

Updated Aug 26, 2026 · 3 min read

Versions and upgrades

create-kb versions the generator: the snapshot of the app copied into your repo. It does not install a runtime npm dependency that auto-updates your site.

That is the safety model. When we publish create-kb@2.0.0, people who scaffolded 1.2.x keep the 1.2 files on disk. Their yarn build does not start using 2.0. Nothing in their repo changes until they decide to migrate.

Your generated project records that snapshot in kb.engine.json:

Semver for create-kb

We follow semver on the npm package.

BumpExampleWhat it means for new npx create-kbWhat it means for an existing site
Patch1.2.1Bugfixes, docs, small safe starter tweaksYour site is unchanged. Optional: copy specific fix files if a changelog tells you to
Minor1.3.0New optional features (new MDX component, extra kb.config.json keys with defaults)Your 1.2 site keeps running. New keys are optional. You can keep 1.2 forever
Major2.0.0Breaking starter or MDX API (renamed files, required config, dropped Node)Your 1.2 site still runs. You only take 2.0 by migrating. We publish a migration page for that major
1.2 does not break when 2.0 exists

Releasing a new major does not rewrite other people's repositories. npm create-kb@2 is what new scaffolds get. Old projects stay on the engine they copied.

How to stay on 1.2 on purpose

Pin the generator when you create the project:

Later, npx create-kb@latest is only for new directories. It will not upgrade my-notes in place.

When you want a newer engine

There is no npm update for the copied Next.js app. Treat an upgrade as a content-preserving copy.

  1. Read kb.engine.json so you know what you are leaving.
  2. Read the changelog for every major you would skip: create-kb CHANGELOG.
  3. Scaffold next to the old project, same identity flags you used originally:

  1. Copy your data and custom UI into the new tree. Keep:

    • content/ (docs and blog)
    • public/assets/ that you added
    • kb.config.json
    • components/HomePageClient.tsx, components/Footer.tsx, components/Navigation.tsx if you edited them
    • app/globals.css if you edited tokens
    • config/docs-order.config.ts

  2. Do not blindly copy old author/, scripts/, or package.json onto 2.0. Those are the engine. Let the new scaffold own them unless you patched them and you know why.

  3. yarn install && yarn dev in the new tree. Fix anything the major migration notes call out.

  4. Point git at the new tree (or replace files on the same branch after a review).

Majors can rename files

A 2.0 migration page will list required edits (for example a renamed config key). Minors will not require you to change kb.config.json for the old site to keep building.

What we will not do

  • We will not publish a patch or minor that makes old 1.x snapshots fail to build if left untouched.
  • We will not make npx create-kb@latest overwrite an existing project directory (the CLI already refuses non-empty folders).

A later engine-as-npm-package (npm update @.../kb-engine) would change this story. Until that exists, the snapshot model above is the contract.

See also