Upgrade and Compatibility

A generated app is an independent source tree. NextDevTpl 3.x does not overwrite existing projects. Upgrades recreate the same selection in a comparison directory, review its diff, and merge changes in small groups.

Upgrade steps

1. Commit current work, back up the database, and pass the current quality gate.
2. Inspect and keep nextdevtpl.generated.json.
3. Generate a temporary project with the target version and original choices:

pnpm dlx create-nextdevtpl@<target-version> ../nextdevtpl-upgrade \
  --preset <original-preset> --target <original-target> --no-install --yes

4. Compare tooling, src/core, src/adapters, src/services, feature code, schema, environment variables, and deployment configuration in that order.
5. Create forward-only database migrations and test them on a non-production DB.
6. Pass lint, type checking, tests, build, and a Preview health check before release.

Repository maintainers can use the repository's upgrade guide.

Combination checks

Template maintainers can run:

pnpm verify:generated
pnpm verify:compatibility:structure
pnpm verify:compatibility --case minimal-server
pnpm release:check

Compatibility reports are written to artifacts/compatibility/<case>.json. See upstream compatibility troubleshooting for common failures and Cloudflare Worker runtime diagnostics.

Rollback principle

Return application code to the pre-upgrade commit. Repair migrations already executed in production with a reviewed forward migration instead of rewriting migration history or risking existing data.