Nx Migration Template

This template provides a step-by-step guide for migrating an Nx monorepo to the latest version.

Prerequisites

• Ensure all current changes are committed before starting migration
• Review current Nx version: nx --version
• Create a backup branch if needed: git checkout -b backup-before-nx-migration

Migration Steps

Step 1: Prepare Migration

nx migrate latest

What this does:

• Updates package.json with latest Nx version and compatible dependencies
• Generates migrations.json file with pending code migrations
• Recommended to update one major version at a time

Step 2: Review Changes

• Inspect package.json for any dependency conflicts or undesired changes
• Review migrations.json to understand what code/config changes will be applied
• Verify all Nx packages remain on the same version
• Check for any breaking changes in the migration notes

Step 3: Install Dependencies

npm install

What this does:

• Installs all updated dependencies from the modified package.json
• Ensures new package versions are available for migration

Step 4: Apply Migrations

nx migrate --run-migrations

What this does:

• Updates source code and configuration files automatically
• Applies breaking change fixes
• All changes remain unstaged for manual review

Step 5: Verification Checklist

• Run build: npm run build
• Run linting: npm run lint
• Run tests: npm run test
• Check for any compilation errors
• Verify all packages build successfully
• Test critical functionality manually

Step 6: Review & Commit

• Review all unstaged changes using git diff
• Stage and commit verified changes
• Clean up: rm migrations.json
• Push changes to remote repository

Advanced Options

Interactive Migration

Use interactive mode for more control:

nx migrate latest --interactive

Update Specific Packages Only

Update only Nx core packages:

nx migrate @nx/workspace@latest

Community Plugins

Update community plugins separately:

nx migrate my-plugin

Troubleshooting

Common Issues

1. Dependency conflicts: Check package.json for version mismatches
2. Failed migrations: Review migrations.json and apply manually if needed
3. Build errors: Check for breaking changes in updated packages
4. Test failures: Update test configurations as needed

Rollback Process

If migration fails:

1. Reset to previous state: git reset --hard HEAD
2. Remove migrations.json: rm migrations.json
3. Restore original package.json from git history

Best Practices

• ✅ One major version at a time: Avoid jumping multiple major versions
• ✅ Review before committing: Inspect all changes thoroughly
• ✅ Test comprehensively: Run full test suite after migration
• ✅ Keep migrations.json: Until all team branches are updated
• ✅ Document issues: Note any manual fixes needed for future reference

Resources

• Nx Migration Documentation
• Advanced Update Process
• Migration Generators