Docs · Update

Update to a new version without losing your data

A template has two halves: the backend (your Convex data and schema) and the frontend (the app code you cloned). They update independently — and neither one requires you to throw away what you already have.

The short version

→Backend: just run convex deploy again. Your table data is preserved.
→Frontend: add the template repo as an upstream remote and git pull the new version into your customizations.
→Neverdelete & re-clone or re-scaffold — that is the delete-recreate loop and it puts your data at risk.

1. Backend — redeploy, data untouched

Convex is data-first. When you redeploy, it preserves every row in every table. A deploy pushes new functions and a new schema against the database you already have — it does not wipe it and start over.

# from your project root
convex deploy

Schema changes that come with a new version are additive and forward-compatible by design: new tables and new optional fields are introduced without dropping or renaming what is already there. So updating the backend is usually just the one command above — your data flows straight through.

When a change is destructive

On the rare occasion a version genuinely needs a breaking schema change (renaming a field, splitting a table), it ships with an explicit migration in the release notes. You run that migration as a step — it is never silent, and it is never a reason to drop your tables.

2. Frontend — pull the new code in place

You cloned the template once and then made it yours. To get the new version's code, point git at the original template repo as a second remote called upstream and merge its changes into your branch.

# one-time: register the template repo as "upstream"
git remote add upstream <template-repo-url>

# pull the new version into your working branch
git pull upstream main

Git will merge cleanly where you haven't touched anything, and flag conflicts only in files you customized. Resolve those conflicts — keep your branding and content, take the template's framework improvements — then commit the merge.

# after resolving any conflicts in your customizations
git add .
git commit

# rebuild + redeploy
pnpm build:auto

build:auto rebuilds the frontend and, when a Convex deploy key is present, redeploys the backend in the same step — so the new code and the data-preserving redeploy ship together.

What to avoid: the delete-recreate loop

Do not delete and re-clone, and do not re-scaffold from scratch.

Tearing down a fresh copy and wiring a brand-new backend means standing up a new database — and that is exactly where you risk losing the data your old project holds. Updating in place — redeploy the backend, pull the frontend — keeps every table and every customization intact. It is the safe path, every time.

Coming soon

A versioned shared package is planned for the common framework parts that every template has in common. Once it lands, those updates ship through pnpm update with zero merge conflicts — the framework moves forward on its own version line while your repo only holds the parts that are genuinely yours.

← Setup guide Back to portal →