Upgrading Codapult

How Updates Work

Codapult uses git merge — the same approach used by Supastarter, Makerkit, and other premium boilerplates. You keep your customizations in your own repository and merge tagged releases from the upstream Codapult repo.

Your repo (main)     ──●──●──●──────●──●──── (your commits)
                             ↑              ↑
Codapult upstream   ──○──○──○──○──○──○──○── (our releases)
                        v1.0  v1.1  v1.2

Every release is a git tag (e.g. v1.2.0). You merge the tag into your repo, resolve any conflicts, and continue building.

One-Time Setup

After purchasing Codapult, add the upstream remote:

git remote add upstream [email protected]:<org>/codapult.git

Verify it's configured correctly:

git remote -v
# origin   [email protected]:you/my-saas.git (your repo)
# upstream [email protected]:<org>/codapult.git (Codapult)

Update Process

1. Check Available Versions

git fetch upstream --tags
git tag -l 'v*' --sort=-v:refname | head -20

2. Read the Changelog

Check CHANGELOG.md or the release notes for the target version. Pay attention to:

• Breaking changes — may require action on your side
• Migration steps — specific instructions for that version
• New features — optional modules you can enable in src/config/app.ts

3. Merge the Release

git stash  # if you have uncommitted changes

git merge upstream/v1.2.0 --no-commit

git diff --cached --stat  # review what changed

4. Resolve Conflicts

If you followed the Customization guide:

• src/config/ — your values win, but merge new fields (e.g. appConfig.ai)
• content/ — no conflicts (your content)
• Core src/lib/ — upstream wins (you shouldn't have edited them)
• .env.example — check for new env vars and copy missing ones to .env.local

5. Install and Verify

pnpm install
pnpm dev          # check the app works
pnpm lint         # check for type/lint errors
pnpm test         # run unit tests

6. Commit

git add .
git commit -m "chore: upgrade Codapult to v1.2.0"

7. Apply Schema Changes

If the release notes mention database changes:

pnpm db:generate  # generate new migration
pnpm db:push      # apply to dev database

Safe Zones — Where to Edit

Understanding which files are safe to modify helps you minimize merge conflicts when upgrading.

Safe — Customize Freely

These files are your product space. Codapult updates rarely touch them.

Safe — Extend, Don't Replace

Add new files alongside existing ones. Avoid modifying the files that ship with Codapult.

Caution — Edit with Care

Changes here may conflict during merges. Prefer configuration over direct edits.

Core — Don't Edit

These are infrastructure files that Codapult updates frequently. Use configuration, env vars, or the adapter pattern instead.

Merge Conflict Risk

Version Numbering

Codapult follows Semantic Versioning:

Release cadence:

• Patches — as needed for bug fixes and security
• Minor — every 2–4 weeks with new features
• Major — rare, only for structural changes

Update regularly (every minor release). The longer you wait, the harder the merge.

Troubleshooting

Haven't updated in months

Option A — Incremental merge (recommended):

git merge upstream/v1.1.0 --no-commit && git commit -m "chore: upgrade to v1.1.0"
git merge upstream/v1.2.0 --no-commit && git commit -m "chore: upgrade to v1.2.0"

Option B — Cherry-pick specific fixes:

git log upstream/main --oneline
git cherry-pick <commit-hash>

pnpm-lock.yaml always conflicts

This is expected. Always resolve by accepting upstream and regenerating:

git checkout --theirs pnpm-lock.yaml
pnpm install
git add pnpm-lock.yaml

Edited core files and everything conflicts

For files in src/lib/auth/, src/lib/payments/, etc.:

1. Accept upstream: git checkout --theirs <file>
2. Re-apply your changes on top (or move them to plugins/config)

Going forward, keep your edits in safe zones to avoid this.

New database tables conflict with mine

In src/lib/db/schema.ts:

1. Keep both your tables and upstream's new tables
2. Make sure there are no duplicate table names
3. Run pnpm db:push to apply