Major framework migrations

Framework Major Migrations

When to Use

Use when upgrading a primary application framework across one or more major versions (e.g., React 18 $\rightarrow$ 19, Next.js 14 $\rightarrow$ 15, Vue 2/3, Angular 17 $\rightarrow$ 18 $\rightarrow$ 19, Vite 5 $\rightarrow$ 6, Tailwind v3 $\rightarrow$ v4, Laravel 10 $\rightarrow$ 11 $\rightarrow$ 12, Symfony 6 $\rightarrow$ 7, Django 4.2 $\rightarrow$ 5.x, Electron/Tauri majors).

Multi-Major Stepping Rule

Never leapfrog multiple major versions in a single unverified jump if the framework's migration path relies on per-major deprecation bridges or CLI migrations (e.g., ng update requires stepping one major version at a time: 16 -> 17 -> 18). Even when a direct jump is technically possible, evaluate each intermediate major's breaking changes sequentially.

Phase-by-Phase Migration Playbook

Phase 1: Pre-Migration Readiness & Satellite Audit

1. Eliminate Deprecations on the Current Version First:
   • Before bumping the major version, resolve deprecation warnings emitted by the current version (e.g., Symfony deprecation logs, Django -W error::DeprecationWarning, React StrictMode warnings, Vue compat flags).
2. Audit Ecosystem / Satellite Package Compatibility:
   • A framework major upgrade fails if critical ecosystem plugins do not yet support the new major (e.g., UI component libraries, router, state store, ORM adapter, auth library, test utils like @testing-library/* or @vue/test-utils).
   • Map every framework-coupled dependency and verify its compatible target version before editing manifests.

Phase 2: Coordinated Core + Toolchain Bump

Update the framework core alongside its mandatory build and compiler companions:

• React / Next.js: react + react-dom + @types/react + @types/react-dom + next + eslint-config-next. Check async Request APIs (cookies(), headers(), params, searchParams becoming Promises in Next 15), caching defaults (fetch no longer cached by default), and React 19 ref-as-prop / useActionState.
• Vue / Nuxt: vue + vue-router + pinia + @vitejs/plugin-vue + vue-tsc + @vue/test-utils.
• Angular: Run npx @angular/cli@<major> update @angular/core@<major> @angular/cli@<major> on a clean working tree so official Angular schematics transform decorators, standalone imports, control flow, and angular.json builders.
• Laravel / Symfony: Bump laravel/framework (or symfony/* + extra.symfony.require) together with first-party packages, PHP minimum version, and PHPUnit/Pest. Review framework skeleton diffs (laravel/laravel comparison) when structural files (bootstrap/app.php, config/*.php) change only on major boundaries.
• Build & Styling Toolchains (Vite / Webpack / Tailwind / ESLint):
  • ESLint v8 $\rightarrow$ v9: Migrate .eslintrc.* to eslint.config.js (Flat Config) and verify every plugin's flat-config compatibility.
  • Tailwind CSS v3 $\rightarrow$ v4: Check @import "tailwindcss"; CSS-first configuration, removed utilities, and PostCSS/Vite plugin replacements (@tailwindcss/vite / @tailwindcss/postcss).

Phase 3: Configuration, Serialization & Runtime Verification

• Check session storage, cache keys, cookie signing, queue job serialization, and SSR hydration payloads so rolling deploys or existing browser sessions do not crash after deployment.
• Verify both development server (dev / HMR) and production build (build + start / preview), plus unit and E2E critical paths.