Updating the Codebase

You own a copy of the boilerplate. Your branding, your pages, your database — none of it lives on our servers. Updates work the way updates work in any git project: we publish a release, you merge it, you resolve the handful of places where your work and ours overlap.

Setup — once, right after you clone

pnpm setup:upstream

That single command does three things, all of them local to your clone:

Every update

# 1. See what you're getting into. Read-only, changes nothing.
pnpm upgrade:check
 
# 2. Rehearse it. Performs the merge in a throwaway worktree and reports
#    the conflicts, then deletes it. Your repository is never touched.
pnpm upgrade:try --build
 
# 3. Do it for real, on a branch
git checkout -b update-v3.0.0
git merge v3.0.0
 
# 4. Resolve whatever conflicts remain (see below)
 
# 5. Catch up dependencies, configs and database
pnpm install
pnpm fix:configs --apply     # when a release says so — see below
pnpm db:status
 
# 6. Prove it compiles AND runs, then merge into your main
npx tsc --noEmit
pnpm build
pnpm verify:smoke

What pnpm upgrade:check tells you

It is the whole reason this is not scary. Before you touch anything, it prints:

• the release you are on and the newest one available
• the changelog entries between the two
• migrations this release adds that your database hasn't got
• env vars this release adds that are missing from your .env.local
• the conflict forecast — the exact list of files you have changed that this release also changes, split into "handled for you" and "you will resolve by hand"

If the forecast is empty, the merge is mechanical.

Your config inherits from ours

Every config/*.config.ts is protected on merge, so your version survives. On its own that also meant a key we added was silently withheld — and it happened: siteConfig.legal and siteConfig.poweredByBadge shipped in 1.18.0 and reached nobody who had cloned earlier.

Since 2.0.0 each config is wrapped in a defineX({ ... }) call and layers over config/defaults/. Your values still win; only keys you have not set fall through to ours.

pnpm fix:configs --apply
npx tsc --noEmit

Your legal, FAQ and help copy inherits the same way. If you never rewrote those pages you are running our example text, and our corrections to it now reach you. To take a document over, copy it out of config/defaults/legal.defaults.ts (or faq.defaults.ts, help.defaults.ts) into your own config — from then on it is yours in full and stops receiving our changes.

Resolving conflicts

pnpm upgrade:check sorts the forecast into three groups, and each is a different kind of work:

git checkout --ours  config/site.config.ts        # keep your branding
git checkout --theirs lib/supabase/auth-helpers.ts # take our fix
git add <file>

After keeping your version of a config file, skim our version for new keys and copy them across — git diff HEAD...MERGE_HEAD -- config/site.config.ts shows you what we added.

Where conflicts actually happen

Most customizations never conflict, because they aren't in code:

• Colours, typography, radius, shadows — stored in your database, edited at /admin/design. Nothing to merge.
• Card and page layouts, map defaults — same, database-backed.
• Brand name, logos, contact details, plans, feature flags, pricing cards, FAQ — in config/, protected by the merge driver. Keys added by a release still reach you: your config holds your overrides, and anything you have not set falls back to config/defaults/, which is core and does update.

Conflicts come from editing page files. If you rewrote app/(marketing)/pricing/page.tsx or your Header.tsx, those will conflict whenever we change them — that's honest, unavoidable git, and the changelog flags those releases with [ui] so you see it coming.

See What to customize for the full map.

Taking only part of a release

Sometimes you want the API fix and not the redesign. That is possible here because no commit mixes the two — a technical change and a visual change never share a commit.

pnpm upgrade:pick v3.0.0

lists the release's commits split into core (lib/, app/api/, components/ui/ — you never edited these) and customer-facing (marketing pages, layout, styles, config). Then:

git checkout -b core-of-v3.0.0
pnpm upgrade:pick v3.0.0 --apply

cherry-picks only the core commits and leaves every customer-facing one behind.

Does it still run?

pnpm build proves the code compiles. It does not prove a page renders.

pnpm verify:smoke

boots the built app and checks that the home page, pricing, FAQ, categories, sign-in, dashboard, admin, the projects API, the sitemap and robots.txt all answer. Routes behind a feature flag you turned off are skipped. It is the difference between "it compiles" and "it works", and it takes about a minute.

Database migrations

Run this after every merge:

pnpm db:status

It compares the migration files in supabase/migrations/ against a ledger table in your own Supabase project and prints exactly which ones you still owe. Paste those files into the Supabase SQL Editor in the order shown.

Let AI do it

The repo ships an /upgrade slash command for Claude Code. It runs the pre-flight, creates the branch, merges the tag, applies the who-wins rule file by file, lists pending migrations and runs lint + typecheck + build:

/upgrade v3.0.0

Using Cursor or another assistant instead? Paste this:

If something goes wrong

You merged on a branch, so nothing is lost:

git merge --abort                    # mid-merge, undo it
git checkout main && git branch -D update-v3.0.0   # after the fact

Your production site is unaffected until you merge that branch into main and deploy.

Downloaded a ZIP instead of cloning?

There is no upgrade path from a ZIP — a snapshot has no history to merge against. Move to git once:

git init && git add . && git commit -m "chore: my customized DirectoryLaunch"
git remote add origin https://github.com/you/my-directory.git
git push -u origin main
pnpm setup:upstream

The first merge after that needs --allow-unrelated-histories and will be noisy. Every release after it behaves normally.

Do you have to update?

No. A version you deployed keeps working. Merge a release when it contains something you want, or when it is a security release — those are PATCH bumps in the changelog and always safe to take.