Skip to content

Updating

Jump to bottom
yCENzh edited this page Sep 19, 2026 · 1 revision

Updating

pnpm add shirones@latest
npx shirones info
npx shirones init --update

That is the routine. The interesting part is what each step is protecting you from.

Check before you apply

npx shirones info is read-only and tells you what changed on the theme's side since you last looked — including the upstream theme commit the package was built from, which is a better signal than the package version alone.

Run it before upgrading if you have a lot of overrides. It will not tell you whether your overrides still apply, but it will tell you how far you are moving.

After upgrading

npx shirones init --update

This adds what the theme now has that you do not: new config modules, new project-level scaffold files. It never overwrites. Safe to run on a dirty tree, safe to run twice.

What it does not do is merge. If the theme added three fields to siteConfig and you have your own siteConfig.ts, the file is left exactly as it is. info reports it under changed config so you know to look:

diff shirones/config/siteConfig.ts node_modules/shirones/src/config/siteConfig.ts

The theme's current version is right there in node_modules. Diffing against it is faster than reading release notes and more reliable.

When the theme renames something

Two failure modes, and they behave differently.

A renamed config module fails loudly-ish. The integration asks for the new name, finds neither your copy nor a packaged one under that name, and throws:

[shirones] Could not find config module "siteConfig".
  Looked in: /you/my-blog/shirones/config
         and: /you/my-blog/node_modules/shirones/src/config

More often the theme keeps the old name working and adds a new one, in which case your old file simply stops being read. The integration warns about exactly this at startup:

[shirones] [overrides] 1 config file(s) match no module the theme loads, so they are never read:
  - /you/my-blog/shirones/config/siteConfig.ts

Move your edits into the new module and delete the old file.

A renamed component fails silently. Your mirrored file stops matching any package path, so the theme uses its own version again and your customisation quietly disappears. There is no warning, because the theme cannot distinguish a stale override from a component you wrote yourself — both are files in src/components/ that match nothing in the package.

After a major upgrade, list your overrides and check them against the current inventory:

find src/components src/layouts -type f | sort
cat node_modules/shirones/manifest.json

Anything you have that the manifest no longer lists is either yours by design or an override that needs moving.

When --update is not enough

If the theme's config modules have changed substantially, merging by hand can cost more than re-applying your edits:

npx shirones init --force

This replaces the template trees and moves the previous copies to .shirones-backup/. Your content directory is inside what gets replaced, so read the log and pull your posts back out of the backup afterwards.

A reasonable workflow for a big jump:

cp -r shirones/content /tmp/my-content      # belt and braces
npx shirones init --force
rm -rf shirones/content && cp -r /tmp/my-content shirones/content
diff -r .shirones-backup/shirones/config shirones/config   # re-apply your edits

Breaking changes to watch for

shirones/collections used to export a defineCollections() helper. It is gone. Astro's typegen cannot introspect a schema hidden behind a function call, so the generated src/content.config.ts now calls defineCollection per collection with the schema inline. init --force rewrites the file for you; by hand, the shape is in Project layout.

ResolvedShironesPaths no longer has isPluginMode or isInRepo. Both were replaced by a single isThemeRepo. Only relevant if you wrote tooling that reads the integration's resolved paths, which is not something the public API encourages.

Locking a version

The theme's dependencies are inherited from the upstream theme repository verbatim, and its peerDependencies are derived from the same manifest so that an upstream bump flows through instead of stranding you. In practice this means upgrading shirones can move astro and svelte with it. Read the peer ranges in the new version's package.json before you upgrade if your project pins them.

Next

Clone this wiki locally