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
| File | Resolution |
| ----------------------- | ---------------------------------------------------------------------------- |
| pnpm-lock.yaml | Accept upstream: git checkout --theirs pnpm-lock.yaml, then pnpm install |
| src/lib/db/schema.ts | Keep both — your tables + new upstream tables |
| src/lib/validation.ts | Keep both — your schemas + new upstream schemas |
| messages/*.json | Keep both — your translations + new upstream keys |
| src/config/app.ts | Keep your values, add any new fields from upstream |
| package.json | Accept upstream deps, keep your custom additions |
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.
| Path | What it controls |
| -------------------------- | ---------------------------------------------- |
| src/config/app.ts | Brand name, features, auth settings, AI config |
| src/config/navigation.ts | Dashboard and admin sidebar items |
| src/config/marketing.ts | Pricing tiers, testimonials, stats |
| src/app/globals.css | Theme colors and fonts |
| messages/*.json | UI translations |
| content/blog/ | MDX blog posts |
| content/docs/ | Documentation articles |
| codapult.plugins.ts | Plugin registration |
| plugins/ | Community plugin directory |
| .env.local | Secrets, API keys, provider selection |
| public/ | Static assets — logos, favicons, OG images |
| e2e/ | Your E2E tests |
Safe — Extend, Don't Replace
Add new files alongside existing ones. Avoid modifying the files that ship with Codapult.
| Path | How to extend |
| -------------------------------- | ------------------------------------- |
| src/app/(dashboard)/dashboard/ | Add new dashboard pages (new folders) |
| src/app/(marketing)/ | Add new marketing pages |
| src/app/api/ | Add new API routes (new folders) |
| src/components/ | Add new components |
| src/lib/actions/ | Add new server actions (new files) |
| src/lib/trpc/routers/ | Add new tRPC routers |
| src/lib/db/schema.ts | Add new tables at the bottom |
| src/lib/validation.ts | Add new Zod schemas at the bottom |
Caution — Edit with Care
Changes here may conflict during merges. Prefer configuration over direct edits.
| Path | Prefer instead |
| ------------------------- | --------------------------------------------- |
| Sidebar.tsx | Edit src/config/navigation.ts for nav items |
| admin/layout.tsx | Edit src/config/navigation.ts for nav items |
| AuthForm.tsx | Edit src/config/app.ts for providers |
| schema.ts (core tables) | Add new tables, don't rename core ones |
| permissions.ts | Add new permissions, don't remove core ones |
| onboarding/index.ts | Add new tours, leave existing as templates |
| next.config.ts | Modify only if you know what you're doing |
Core — Don't Edit
These are infrastructure files that Codapult updates frequently. Use configuration, env vars, or the adapter pattern instead.
| Path | Configure via |
| ------------------------ | ------------------------------------------------------ |
| src/lib/auth/ | AUTH_PROVIDER env var + src/config/app.ts |
| src/lib/payments/ | PAYMENT_PROVIDER env var |
| src/lib/storage/ | STORAGE_PROVIDER env var |
| src/lib/notifications/ | NOTIFICATION_TRANSPORT env var |
| src/lib/jobs/ | JOB_PROVIDER env var |
| src/lib/ai/ | EMBEDDING_PROVIDER, VECTOR_STORE_PROVIDER env vars |
| src/lib/rate-limit.ts | Tunable per-route in API route files |
| src/lib/guards.ts | Used as-is |
| src/lib/trpc/init.ts | Add routers in src/lib/trpc/routers/ |
| src/lib/graphql/ | Extend schema, don't rewrite core |
| src/lib/plugins/ | Write plugins in plugins/ |
| src/components/ui/ | Update via pnpm dlx shadcn@latest add |
| src/proxy.ts | Rarely needs changes |
| src/instrumentation.ts | Configure via env vars |
Merge Conflict Risk
| Zone | Risk | Why |
| --------------------------- | -------------- | --------------------------------------------- |
| src/config/ | Very low | Your files, rarely changed upstream |
| content/, messages/ | Very low | Your content |
| src/components/marketing/ | Low | Upstream may add sections, yours are separate |
| src/lib/db/schema.ts | Medium | New core tables may be added upstream |
| pnpm-lock.yaml | High (easy) | Accept upstream, then pnpm install |
| src/lib/ (core) | High if edited | Don't edit core — use config/adapters/plugins |
Version Numbering
Codapult follows Semantic Versioning:
| Version bump | What it means | Merge difficulty |
| --------------------------- | -------------------------------------- | ------------------------------------------------ |
| Patch (v1.0.1 → v1.0.2) | Bug fixes, security patches | Easy — few conflicts |
| Minor (v1.0.0 → v1.1.0) | New features, new modules | Moderate — new files, possible schema additions |
| Major (v1.0.0 → v2.0.0) | Breaking changes, structural refactors | May require manual migration — see release notes |
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.:
- Accept upstream:
git checkout --theirs <file> - 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:
- Keep both your tables and upstream's new tables
- Make sure there are no duplicate table names
- Run
pnpm db:pushto apply