Updates & Upgrades

SaaSyBase is now stable enough that most future releases are much more likely to be improvements, bug fixes, security updates, and polish than deep breaking rewrites. In plain terms, that means most updates should feel like normal maintenance, not like rebuilding your app. This guide explains how to apply newer official SaaSyBase releases safely once your copy is already live and customized.

Why live updates need a different workflow

The main idea is simple: once your site is live, you are no longer updating a blank starter. You are updating your version of SaaSyBase, with your branding, your settings, your database, and your own product changes already in place.

You will see the word upstream in this guide. For non-technical operators, that just means the newer official SaaSyBase version you are updating from.

Tip

Most releases should not require database changes, auth changes, or payment rewiring. Those are the exception, not the default. The safe workflow here exists so you can handle both the common simple update and the occasional deeper infrastructure update without guessing.

What most updates will actually look like

Small UI improvements and admin quality-of-life fixes.
Bug fixes in existing features.
Security hardening and safer defaults.
Documentation improvements and clearer setup guidance.
Occasional new optional features you can adopt when ready.

Note

A good default assumption is: read the release, test it in staging, and expect it to be routine unless the release specifically says otherwise.

What usually changes in a boilerplate update

Change area	Why it matters on a customized install	What to check before deploy
Routine code improvements	This is the most common case: normal fixes, UI polish, docs, and safer defaults.	Review the release notes, test in staging, and deploy normally if nothing infrastructure-related changed.
Environment variables and secrets	Sometimes a release adds one or two new settings the app expects during build or runtime.	Compare your deployed env vars with the updated repo before building.
Customized UI and product logic	Your team may have changed routes, layouts, admin flows, or business logic directly.	Review conflicts file by file and keep or merge the parts that belong to your product.
Auth or payments	Less common, but important when a release touches login, billing, subscriptions, or webhooks.	Retest the exact auth and payment providers you use in production.
Database or Prisma changes	These happen sometimes, but should not be treated as the default expectation for every release.	Only do the migration-specific checks when the release actually includes database changes.
Storage and uploads	Important only if the release touches media handling or your install uses customized storage settings.	Confirm your storage configuration still matches the intended behavior.
Seeded records and defaults	Useful for first installs, but your live database is already the source of truth.	Do not treat seed scripts as part of normal upgrade flow.

Recommended sync strategy

Keep your product in a repository or branch that can intentionally pull from the official SaaSyBase source. Do not update a live install by manually copying files from a newer zip or by editing the production server directly. You want a reviewable history that shows exactly what changed and how conflicts were resolved.

Typical upstream sync flow

# once: add the original SaaSyBase repo as an upstream remote
git remote add upstream <saasybase-upstream-url>

# before each update
git fetch upstream
git checkout main
git merge upstream/main

# or rebase if that matches your team's workflow
# git rebase upstream/main

Tip

Smaller, more frequent upgrades are easier to validate than rare large jumps. If you update regularly, most releases should stay simple and predictable.

Safe upgrade workflow

Recommended sequence for customized live installs

Read what changed first

Start with the release notes or change summary. For most teams, this answers the main question quickly: is this a routine update or one that touches infrastructure?

Inventory your own customizations

List the parts your team changed: custom pages, plans, login screens, payment behavior, storage, email templates, admin settings, or one-off scripts. This shows where the update might overlap with your own work.

Back up production first

Take a fresh database backup and export the effective production env configuration. If you store uploads locally, back those up too.

Prepare the update away from production

Merge the new official SaaSyBase version into a release or staging branch first. Do not experiment directly on the live server.

Diff environment requirements

Compare your existing deployed settings and secrets against the updated repo. A missing variable can break the build before the app even starts.

Run basic checks before staging

At minimum, run the project checks that cover the updated areas.

npm run typecheck
npm run lint
npm test

Deploy staging with production-like configuration

Use the same auth provider, payment provider, and storage mode that production uses. A staging environment that behaves very differently from production is not a reliable test.

Test the workflows your business depends on

Verify sign-in, checkout, admin settings, uploads, cron endpoints, and your product-specific flows. If the release mentions a database change, include that in staging too.

Prepare rollback before production

Know how you will restore the database, revert the deployment, or forward-fix quickly if the update fails. Decide that before the maintenance window starts.

Deploy production using the normal ordered flow

Run the same production process every time: migrate first, then build, then start or promote the release.

npm run prisma:deploy
npm run build
npm run start

Run post-deploy smoke checks immediately

Call the authorized health endpoint, sign in as an admin and a normal user, verify your core billing or checkout flow, confirm webhook delivery, and inspect logs before marking the release complete.

Common upgrade mistakes to avoid

Do not run npx prisma db seed on every production update. In this repo, seed data is for first-time bootstrap or deliberate demo or local setup, not routine live upgrades.
Do not assume every update needs Prisma or database work. Only switch into migration mode when the release actually includes schema changes.
Do not assume auth-provider switching is “just config.” Better Auth and NextAuth share the self-hosted lane, but Clerk is still a separate identity boundary.
Do not update webhook code without re-checking the matching provider dashboard endpoint and webhook secret in the deployed environment.
Do not trust a green build by itself. Runtime failures can still appear in env loading, storage, cron auth, or provider callbacks.
Do not patch production by hand and try to reconstruct the change later. Make the change in Git first so you can review and roll it back safely.

Minimum validation checklist after an upgrade

The authorized /api/health response shows the expected database, auth provider, and payment provider.
Admin sign-in still works and at least one normal user sign-in path still works.
Your primary checkout or billing workflow still succeeds in the configured payment provider.
Webhook deliveries succeed for the providers you use.
The pages or dashboards your team customized most heavily still render and submit correctly.
Cron endpoints still accept the expected bearer token and complete without auth or runtime failures.
Uploads, logos, and file-backed assets still load from the configured storage provider.
No new high-severity errors appear in /admin/logs or Sentry during the release window.

SaaSyBase-specific notes

Most updates should be routine maintenance, not structural rewrites. If a release does include Prisma changes, keep production on PostgreSQL and use npm run prisma:deploy. The broader deployment rules are documented in Deployment and Local PostgreSQL.
If an update touches auth behavior, review Authentication with special attention to the provider-switching boundary between Clerk and the shared Better Auth or NextAuth lane.
If an update changes billing or checkout behavior, retest the exact provider you use in production rather than assuming feature parity across Stripe, Paystack, Paddle, and Razorpay. See Payments and Webhooks.
If an update changes admin settings, seeded plans, or editable site pages, compare new defaults against the records already stored in your database. After launch, your production database is the source of truth.
If an update touches uploads or media handling, confirm that your live environment still matches the intended storage lane. Container-local files are not a durable production storage strategy.

Note

The short version is simple: after launch, think of SaaSyBase as your app with an official update path, not as a starter you reinstall from scratch each time.