Updating the app

---

Why avoiding merges is usually safer:

• Template changes are often coupled. Pulling in one change without the related ones can break things.
• Your project likely uses a specific Wasp version. New template code may target a different version.
• The more your app has diverged, the harder and riskier it is to merge.
• Even if you only want a single new feature, you may end up refactoring multiple areas to make it work.

---

If you still need a change there are 2 viable paths.

Pre-flight checklist for either path:

• Confirm your current Wasp version in main.wasp and note it in the PR.
• Back up your database and .env files.
• Open a feature branch and plan a rollback.
• Write a short upgrade plan listing files you will touch.

---

Path A - Bring template changes into your existing project

Best when your app has not diverged much.

1. Create a new git branch for the update.
2. Review recent template commits and PRs to understand what changed and which Wasp version they target.
3. Cherry-pick or copy only the minimal files you need. Prefer small, isolated diffs over bulk merges.
4. Align versions. If the template change requires a newer Wasp version, update the wasp version in main.wasp and upgrade dependencies, or backport the change to your current version.
5. Reconcile schema and migrations. If Prisma entities changed, run wasp db migrate-dev locally and verify data safety.
6. Rewire env vars. Add any new variables to .env.server or .env.client as needed.
7. Run the full suite. Start the app, run e2e-tests, exercise the affected flows, and check logs.

---

Path B - Port your app into a fresh template

Best when your app has diverged a lot or you want multiple new template features.

1. Scaffold a fresh project from the latest template.
2. Match the Wasp version noted in the fresh template and keep it.
3. Copy your business logic in layers: routes and pages, operations, server utils, UI components - one feature at a time.
4. Recreate schema changes and run wasp db migrate-dev.
5. Bring over config and env vars. Keep names consistent.
6. Reinstall only the dependencies you actually use.
7. Run the app and e2e-tests. Verify payments, auth, file upload, and admin dashboard.

---

Post-upgrade checks

• App boots locally and on your staging environment.
• Auth works for email and any social providers you use.
• Webhooks process events end to end.
• Admin dashboard loads analytics.
• No missing env vars at runtime.
• e2e-tests pass.

---

Rule of thumb

If a change feels like it requires more than a few small, targeted diffs, use Path B. It is often faster and safer than wrestling with a complex merge.