Choosing between nest update CLI and manual package.json edits for deterministic rollback after a failed NestJS major upgrade

Answer

To guarantee a reversible upgrade path, the safest approach is to commit the pre‑upgrade state, use a lockfile, and rely on npm ci (or yarn install --frozen-lockfile) to restore the exact runtime environment. The choice between nest update and manual package.json edits only affects how you reach that state, not the rollback mechanism itself.

Trade‑offs

• CLI update rewrites all dependency ranges in package.json and updates internal files in a single step. It saves time but can silently bump transitive packages that are not listed explicitly, which may introduce subtle incompatibilities that only surface at runtime.
• Manual pinning gives fine‑grained control over every version, allowing you to cherry‑pick a compatible set of packages. It requires careful editing and a subsequent npm install to surface peer‑dependency conflicts, but you can review the diff before committing.

Lockfile‑based rollback

When a lockfile (e.g., package-lock.json for npm) is committed, npm ci will recreate the exact dependency tree that existed at the time of the commit. This works for both CLI‑driven and manual upgrades: after a failed upgrade, simply revert the commit and run npm ci to return to the pre‑upgrade state.

Manual pinning and transitive conflicts

Editing package.json manually does expose peer‑dependency mismatches at install time because npm install (or yarn install) will validate the entire tree. However, it can miss conflicts that only become apparent when a library is executed in a particular runtime context. Therefore, after any manual edit, you should run the full test suite to surface such issues before committing.

Practical rollback steps

1. Commit the current package.json and lockfile:

   git add package.json package-lock.json
   
   git commit -m "Pre‑upgrade: NestJS 7.x"
   

2. Upgrade using either method:
   • CLI: nest update @nestjs/core @nestjs/common @nestjs/platform-express --force (add --force only if you explicitly want to ignore peer warnings).
   • Manual: edit package.json to the desired major versions, then npm install.
3. Test the application:

   npm test
   

4. If tests fail or runtime errors occur: revert the commit and restore the lockfile:

   git checkout HEAD~1 -- package.json package-lock.json
   
   npm ci
   

5. Verify that the restored environment matches the pre‑upgrade state:

   npm list @nestjs/core @nestjs/common @nestjs/platform-express
   

What diagnostic detail might change the recommendation?

If you discover that the upgrade requires a non‑standard patch or that a third‑party library has its own breaking change that cannot be satisfied by any single major version of NestJS, you may need to adopt a more granular approach (e.g., pinning specific transitive dependencies). In that case, you would ask:

Do any of the dependent libraries (e.g., @nestjs/microservices, @nestjs/graphql) have their own major‑version constraints that conflict with the target NestJS release?