All posts

How SaaScaffold updates merge into your site

Almost every boilerplate promises lifetime updates. The catch comes once you've changed the code: a new release edits the same files you did, taking it means an afternoon of merge conflicts, and before long the site stops taking updates at all. SaaScaffold is laid out so that updates keep merging after you customize it, and so that your coding agent can do the merging for you.

A SaaScaffold site is not a fork you maintain alone. It starts from a base release and keeps receiving new ones, and each release arrives as a git tag named base-v<version>. You upgrade by merging that tag into your site.

Every path has an owner

base-ownership.json puts each path into one of three classes:

  • Site: your configuration, copy, styles, site records, and your own tables and migrations. The base ships a starting copy once and never changes it afterwards.
  • Generated: files rebuilt by a command, such as pnpm-lock.yaml. Your copy is kept; regenerate it after merging.
  • Base: everything else, merged normally.

Site files carry merge=ours in .gitattributes, so when both sides changed one, git keeps yours without a conflict. Run pnpm base:setup once in every clone to turn that on.

Where your code goes

Your code lives in apps/web/src/site/: configuration, copy, styles, the home page, products, payment channels, AI models and prices, the sign-in dialog and background steps. Worker names and IDs live in site/wrangler.jsonc, and your tables in the site migration channel. New route files you add never conflict.

If you must edit a base file, keep the change small and write down why in site/agents/, so whoever takes the next upgrade knows what to re-apply.

An upgrade, start to finish

Once, when you create your site, point git at the base and at your own repository:

git remote rename origin upstream          # the base releases
git remote add origin <your-site-repo>     # your own repository
pnpm base:setup

Then for every upgrade:

git fetch upstream --tags
pnpm base:doctor --target base-v1.3.0
git switch -c upgrade-base-v1.3.0
git merge base-v1.3.0

base:doctor lists the base files changed on both sides before you merge, so you know where conflicts will be. After the merge: pnpm install, pnpm wrangler:sync, pnpm db:migrate and pnpm test, then deploy as usual.

Bring the branch into main with a merge commit. Never squash or rebase it: the next upgrade needs that merge to find what changed.

What the merge keeps out

merge=ours keeps your copy and drops the base change to that file. So read every changelog section between your release and the target: it names new migrations, new configuration keys and any change to a site file you need to copy over by hand.

Or ask your agent to do it

Every step above is also written as a runbook for coding agents, and the runbooks ship in the repository. AGENTS.md sends Claude Code or Codex to agents/README.md, which maps a request like "merge the new base release" to the git and upgrade runbooks. The agent runs base:doctor, merges the tag on its own branch, runs the commands after the merge and the tests, and brings the branch in with a merge commit.

The runbooks also tell it how to resolve each kind of conflict, by the file's class:

  • A site file conflicts: base:setup wasn't run in this clone. The agent aborts the merge, runs it, and merges again.
  • A base file you edited: it starts from the new base version and re-applies your change, preferably moved into apps/web/src/site/ so it stops conflicting, then updates the note in site/agents/.
  • Base tables or migrations: it stops and asks you, because the right fix depends on which migrations have already run in production. It never edits, renumbers or deletes a migration to get a merge through.

When it doesn't understand a conflict, it shows you both sides instead of guessing. It never pushes to the base repository, and pushing to yours or deploying waits for your go-ahead.

More on extending SaaScaffold.