| name | migrate-a-web-frontend-framework |
| category | web |
| description | Migrate a production frontend framework while preserving behavior, accessibility, performance, URLs, state, and rollback. Use when a live web application must change rendering or component architecture without a rewrite outage. |
migrate-a-web-frontend-framework
Move bounded product slices through a compatibility architecture and prove outcomes before retiring the old runtime.
When to use
- Use when changing the framework, rendering mode, router, state system, or component runtime of a live frontend.
- Use a dependency upgrade when routing, rendering, state, and component contracts remain materially compatible.
Preconditions
- Confirm product, frontend, backend, design, accessibility, SEO, analytics, security, and operations owners.
- Gather routes, features, browsers, components, state, APIs, performance, tests, URLs, tracking, incidents, and deployment constraints.
Procedure
- Build a route and feature inventory across entry points, states, devices, permissions, data, SEO, analytics, and owners.
- Define outcome parity for behavior, accessibility, content, URLs, metadata, performance, security, and observability.
- Choose a compatibility architecture for shared routing, shell, identity, navigation, design tokens, APIs, state, and errors.
- Establish contract tests and visual, accessibility, browser, performance, and analytics baselines.
- Select vertical migration waves that can ship, observe, and roll back independently.
- Prevent duplicate state, handlers, telemetry, styles, and dependency payloads across runtimes.
- Migrate shared foundations only after representative slices prove the boundary.
- Compare old and new paths with synthetic, canary, and real outcome evidence.
- Rehearse rollback of routing and assets without reversing incompatible server data.
- Remove old code only after traffic, references, support, and rollback gates expire.
Failure plan
- Pause a wave for behavior, accessibility, URL, security, analytics, or performance regression.
- Keep old routing available for compatible cohorts until the new slice passes observation.
- If shared state diverges, stop dual mutation and restore one authoritative owner.
- Roll back frontend delivery without claiming server-side effects were undone.
Worked example
A commerce site moves from a client-only framework to server rendering. The inventory exposes account, checkout, search, localization, tracking, and saved-cart state. A shared edge router sends one product family to the new runtime while contracts keep URLs and API state stable. Canary comparison finds duplicate purchase analytics and a focus reset after navigation, so the wave pauses. Both defects are repaired, performance and accessibility baselines pass, and a rehearsal restores the old asset route without reverting completed orders.
Done
- A migration architecture record contains route and feature inventory, compatibility architecture, contracts, waves, ownership, and rollback
- A behavior parity report verifies accessibility, URLs, state, browser, performance, security, SEO, analytics, and user outcomes
- A cutover and rollback rehearsal records traffic movement, asset restoration, evidence preservation, and server-state boundaries
