Upgrades

When the template ships a breaking change, the upgrade lands here as a single Claude Code prompt that does the work for you. You paste it, Claude rewrites your project to match the new structure, you commit. No git pull, no merge conflicts, no manual edits.

Available upgrades

How to run an upgrade

git add .
git commit -m "Upgrade to v0.2.0 (/app/* routing)"

Do I actually need to upgrade?

Not always. The simplest test:

You can also check the date of your last template sync with git log -1 --format="%ad". If it's older than the date in the table above, the upgrade applies.

What if my project is heavily customised?

The prompts are designed to discover and migrate your custom code too — not just the template's own files. Each prompt's first step inventories your project, finds any pages or features you added, and applies the same changes to them.

If your project has diverged in unusual ways (custom middleware, layered architecture, etc.) the prompt may not catch every reference. After Claude finishes, run the verification grep at the bottom of the upgrade page — it surfaces any leftover references to old paths.

What if it goes wrong?

Every upgrade prompt is idempotent and reversible:

1. Reversible: if the result looks broken, run git status to see what changed, then git reset --hard HEAD to roll back to before the prompt ran. Nothing was pushed anywhere — the changes are local until you commit.
2. Idempotent: the prompt's first step (step 0) checks whether the upgrade has already run. If you re-run it on an already-upgraded project, it stops gracefully.

So your worst-case is "it doesn't work, I roll back, I open a GitHub issue". You cannot break the live app.

How versioning works

The template uses semver git tags for releases on the template repo:

• Patch (v0.1.0 → v0.1.1) — bug fixes only, no upgrade prompt needed
• Minor (v0.1.0 → v0.2.0) — new features, OR breaking changes (while in 0.x)
• Major (v0.x.x → v1.0.0) — breaking changes once the template stabilises

While the template is in the 0.x range, breaking changes ship as minor bumps — this matches the standard semver convention for pre-1.0 software, where the contract isn't yet stable. Major bumps are reserved for v1.0 and beyond.

The package.json version is not bumped in lockstep — this isn't an npm package, just a git template. Use git tags to pin a specific version: git checkout v0.2.0.

Each upgrade entry has from: and to: in its frontmatter, so you can match your project's state to the right upgrade.

For Git-comfortable users

If you're comfortable with Git and your project hasn't diverged much, you can skip the prompt and pull updates manually:

git remote add upstream <vue-starter-repo-url>   # one-time
git fetch upstream
git merge upstream/master                        # resolve conflicts

Most users find the prompt approach easier — it doesn't require dealing with merge conflicts in code you didn't write.