For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/web/updating-the-kit.md (or send Accept: text/markdown).
Update your copy when the kit improves
Bring improvements from the source repository into your copy — record your starting point, fetch the new revision, merge it on a branch and verify before deploying.
1. Record what you started from
Treat an update as a small project, not a paste: you compare the kit revision you have with the newer one, carry the changes over and test in a branch before deploying. This works whether your project is a fork of a kit repository — a copy GitHub keeps connected to the source — or code you copied into your own app.
Before anything else, write a note in your project with three things: the kit commit you started from — the SHA, Git's short code that identifies one exact version — the repository you received (supastack-web, supastack-mobile, supastack-desktop or the All Platforms monorepo), and the changes you have already made yourself.
The kit repositories and the monorepo have different histories, so never merge a branch from one into a fork of another. If you never recorded a starting SHA, find the closest shared version with git merge-base in a fork, or identify the last files and tests you copied in a selective adoption — and review a wider diff when the exact baseline is uncertain.
2. Fetch and merge the new revision
Run the commands below in a terminal inside your project folder, with your work saved and committed — a clean working tree, so nothing half-done mixes into the merge. Words inside angle brackets are replace-me templates: substitute your own values in place of the whole <thing>. The GitHub address shown is a placeholder; use the address of the repository you forked.
What the lines do: git remote add teaches your copy a second address named kit-upstream — the kit repository — and git fetch downloads its newest state without touching your files. git switch -c creates a separate upgrade branch so your main branch stays untouched while you review. git log lists the commits you are about to take and git diff --stat summarizes which files changed; read the full diff for the modules you use, not only the commit titles. git merge brings the new code into the upgrade branch.
If Git reports the kit-upstream remote already exists, skip the remote add line and continue with git fetch. <previous-kit-sha> is the starting SHA you recorded in step 1.
# Upstream is the platform repository you forked — substitute its real URL
# (supastack-web shown; use supastack-mobile or supastack-desktop as fits).
git remote add kit-upstream https://github.com/<org>/supastack-web.git
git fetch kit-upstream
git switch -c upgrade/kit-update
git log --oneline <previous-kit-sha>..kit-upstream/main
git diff --stat <previous-kit-sha>..kit-upstream/main
git merge kit-upstream/main3. Resolve conflicts without losing your work
A conflict means both sides changed the same lines: the kit moved on and you customized the same place. Git pauses the merge and marks the file — it is asking you to choose, not reporting damage.
Open each marked file in your editor and decide line by line: keep your product's own text, names and settings, and take the kit's fixes and structural changes. Never resolve a conflict by replacing a file you customized with the kit's whole new version — that erases your work. Resolve inside the upgrade branch and run the tests for each resolved area before continuing.
If the merge goes wrong, git merge --abort returns the branch to its pre-merge state. Nothing in this flow changes your main branch or your deployment until you merge the upgrade branch yourself.
4. Update data and deploy in the right order
New kit revisions can change the database. Read the new files in packages/db/drizzle/ — the migration folder — and back up production data before applying migrations; test them against a disposable copy first. Deploy compatible schema changes before the code that needs them: if a migration removes or reshapes data, rolling back app code alone cannot restore the old schema.
Compare the new .env.example with your own settings and add newly required values in your hosting dashboard. .env files carry secrets and are never committed to Git — you recreate them by hand on each machine and deployment, and they stay out of NEXT_PUBLIC_ and EXPO_PUBLIC_ values.
Before deploying, run the kit's own verification gates. In the All Platforms monorepo, corepack pnpm check:local runs lint, typecheck, the unit tests and a format check with no paid credentials; corepack pnpm verify:local adds the production build and the browser test suites. In a single-surface fork, run that repository's own test and build commands. Then do a staging smoke pass: sign in, try a second workspace, and run your product's main user journey.
When everything passes, write down the accepted target SHA and the conflicts you resolved — that note is the starting baseline for the next update.
corepack pnpm check:local
# fuller gate: adds the production build and browser suites
corepack pnpm verify:local5. If you copied pieces instead of forking
A selective adoption — copying kit modules into an existing app — shares no Git history with the kit, so git merge cannot help. Compare the old source SHA with the target source SHA instead, and port only the changes that touch your adopted slice.
Review the module's public types, persistence schema and migrations, server caller, configuration, tests and docs as one unit — a change inside a package can require a matching route or environment change elsewhere, and copying a single helper can leave the rest on an outdated contract. Keep a short adaptation note — which kit files you took, which you skipped, what you changed — so the next update can replay your choices.
If an update breaks something in your running copy, work through the troubleshooting guide before undoing your own changes.