---
title: "Upgrade Nimbus"
description: "Move a Nimbus site to a new release, including the changes to files you own."
---

> Documentation Index
> Fetch the complete documentation index at: https://nimbus-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade Nimbus

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](/styling/how-customization-works) explains why they're separate.

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

1. **Update the package**

   ```sh
   npm i @cloudflare/nimbus-docs@latest
   yarn add @cloudflare/nimbus-docs@latest
   pnpm add @cloudflare/nimbus-docs@latest
   bun add @cloudflare/nimbus-docs@latest
   ```
2. **Run the migrations**

   ```sh
   npx @cloudflare/nimbus-docs migrate
   yarn nimbus-docs migrate
   pnpm nimbus-docs migrate
   bunx @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**

   ```sh
   npx @cloudflare/nimbus-docs outdated
   yarn nimbus-docs outdated
   pnpm nimbus-docs outdated
   bunx @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:

   ```sh
   npx @cloudflare/nimbus-docs diff src/layouts/DocsLayout.astro --apply
   yarn nimbus-docs diff src/layouts/DocsLayout.astro --apply
   pnpm nimbus-docs diff src/layouts/DocsLayout.astro --apply
   bunx @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:

   ```sh
   npx @cloudflare/nimbus-docs add api-layout --overwrite
   yarn nimbus-docs add api-layout --overwrite
   pnpm nimbus-docs add api-layout --overwrite
   bunx @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

```sh
npx @cloudflare/nimbus-docs check
yarn nimbus-docs check
pnpm nimbus-docs check
bunx @cloudflare/nimbus-docs check
```

```sh
npm run build
yarn run build
pnpm run build
bun 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](https://www.npmjs.com/package/@cloudflare/nimbus-docs) and in the repository, lists what each release changed.

## Next steps

- [Troubleshooting](/publish/troubleshooting): common errors by their exact text.
- [Ownership](/styling/how-customization-works): which files an upgrade touches.
- [CLI](/cli): every `outdated`, `diff` and `migrate` flag.

Source: https://nimbus-docs.com/publish/upgrading/index.mdx