Skip to content
Nimbus

Upgrade Nimbus

Move a Nimbus site to a new release, including the changes to files you own.

AI-generated · awaiting reviewUpdated

A Nimbus release has two parts: the @cloudflare/nimbus-docs package, which you upgrade like any dependency, and changes to starter and registry files, which live in your repo and change only when you take them. This page walks through both, and nimbus-docs migrate lists every step your version jump needs. Ownership explains why they’re separate.

Commit your work first, so every change the upgrade makes shows in git diff.

  1. Update the package

    npm i @cloudflare/nimbus-docs@latest

  2. Run the migrations

    npx @cloudflare/nimbus-docs migrate

    migrate compares the version your site last reviewed, recorded in nimbus.json, with the one you installed. It lists:

    • Migrations it can apply to your code, such as a renamed option. It asks before writing; --dry-run and --diff show the plan without writing.
    • Required upgrade reviews: changes you must make by hand, each with the files affected, what to do, and how to check it.
    • Optional upgrade entries: improvements you can adopt now or later, such as a redesigned component.

    Work through the required reviews. Then run the command migrate prints at the end, migrate --yes, to record the new version in nimbus.json. If nimbus.json doesn’t say which version you came from, pass it: migrate --from 0.17.0.

  3. Take starter changes

    npx @cloudflare/nimbus-docs outdated

    outdated lists the starter files, such as layouts and globals.css, that changed upstream since your site was created. For a file you haven’t edited, take the new version:

    npx @cloudflare/nimbus-docs diff src/layouts/DocsLayout.astro --apply

    For a file you have edited, run diff without --apply to see both sets of changes, and merge by hand.

  4. Take registry changes

    For components you installed with nimbus-docs add, reinstall the ones outdated lists:

    npx @cloudflare/nimbus-docs add api-layout --overwrite

    --overwrite replaces files you haven’t edited and asks about the ones you have. Without a terminal it keeps edited files and lists them.

Verify

npx @cloudflare/nimbus-docs check
npm run build

check exits with no errors, the build passes, and outdated lists no required package API work. Look through the site, then commit.

If something breaks

  • A build error that names a renamed option or removed helper usually has a migration: run migrate again and read its output.
  • An error from a file you own, such as a layout, means it needs the upstream change: compare it with diff <file>.

Each package’s changelog, on npm and in the repository, lists what each release changed.

Next steps

  • Troubleshooting: common errors by their exact text.
  • Ownership: which files an upgrade touches.
  • CLI: every outdated, diff and migrate flag.
Edit this page
Nimbus

Type to search…

↑↓ navigate↵ selectEsc close