Updating The Theme

Skill level: Intermediate (uses git)

When a new version of Kivo is released, CHANGELOG.md in the theme lists what changed. The version you have is in package.json ("version").

Keep Updates Easy

The way you customize decides how easy updates are:

• Change content and config, not components. Updates mostly touch components and styles, so a site customized through src/content/, src/config/, src/i18n/, and a few color tokens in theme.css is the easiest to update.
• Use page blocks instead of editing section components when you only need different content or a different layout.
• Commit often with clear messages, so you know which changes are yours.

Apply An Update With Git

1. Commit all your work, so your project is clean.

2. Create a branch for the update:

   git checkout -b theme-update

3. Unzip the new version. The theme is in its themes/kivo/ folder. Copy the files from that folder over your project, except src/content/, src/config/, src/i18n/, and src/assets/images/, which hold your content. Check CHANGELOG.md for new content files or config keys and add them by hand.

   Copying also replaces files you may have customized: src/styles/theme.css (your colors), route files you edited in src/pages/[...lang]/, public/images/ (your favicons and social image), README.md, package.json and package-lock.json (re-add any dependency you installed yourself, such as wrangler), and wrangler.toml, netlify.toml, vercel.json, or vercel.sh. Restore your versions of those in the next step, or skip them while copying.

4. Review the changes in the Source Control panel. Where a file has both your changes and the theme’s, keep both.

5. Run the checks:

   npm ci
   npm run astro-check
   npm run build

6. Look through the site, then merge the branch into your main branch.

Updating Dependencies

npm outdated lists newer versions of the theme’s tools. Major updates of Astro or Tailwind CSS can need code changes; wait for a Kivo release that includes them unless you are comfortable fixing build errors.