# Updating The Theme

## Updating The Theme

**Skill level:** Intermediate (uses git)

When a new version of Homio 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 and layouts instead of editing section components** when you only need different content or a different look.
- **Commit often with clear messages**, so you know which changes are yours.

### Apply An Update With Git
<Steps>

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

2. Create a branch for the update:

   ```bash
   git checkout -b theme-update
   ```

3. Unzip the new version. Copy the files from its theme folder over your project, **except** `src/content/`, `src/config/`, `src/i18n/`, and `src/assets/images/`, which hold your content, prices, business details, and photos. Check `CHANGELOG.md` for new content files, i18n keys, or config keys and add them by hand.

   Copying also replaces files you may have customized: `src/styles/theme.css` (your colors), `src/lib/brandMark.ts` (if you changed the built-in logo mark), route files you edited in `src/pages/[...lang]/`, `public/images/` (your favicons and social image), `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:

   ```bash
   npm ci
   npm run astro-check
   npm run build
   ```

   `astro-check` runs `check-i18n`, which lists any new interface string the update added to `en.json` but your `fr.json` doesn't have yet.

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

</Steps>

<Aside type="tip">
  An AI assistant can do steps 3–5 for you: "Compare my project with the new
  theme version in [folder]. Apply the theme's code changes, keep my content in
  src/content, src/config, src/i18n, and src/assets/images, and list any new
  content fields, i18n keys, or config keys I should fill in."
</Aside>

### 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 Homio release that includes them unless you are comfortable fixing build errors.