Architecture and migration · Completed
Next.js App Router migration playbook
A practical approach to moving established Next.js products from Pages Router while protecting delivery, metadata, data flow, and user-facing behavior.
- Role
- Migration engineer and author
- Timeline
- Jan 2024
- Technology
- Next.js · React · TypeScript · Material UI
Problem
An App Router migration changes more than a directory name: navigation APIs, server and client boundaries, metadata, data fetching, loading and error behavior, and third-party integrations all move at once. Treating it as a rewrite increases product risk.
Constraints
- The products already had working routes and user-visible behavior that could not simply be discarded.
- Migration work had to coexist with ongoing delivery rather than becoming an open-ended rewrite.
- Public evidence could describe the method and examples, but not confidential product details or outcomes.
My role
I applied App Router migrations across several projects, organized the work into explicit risk areas, and published the reusable first part of the approach with code examples.
Key decisions
Decompose by behavior, not only by folders
The playbook separates route structure, navigation, metadata, data fetching, errors, loading UI, styling, third-party libraries, lazy loading, and sitemap work so each change has a reviewable boundary.
Use the migration to clarify rendering ownership
The App Router creates a useful decision point: keep data and layout work on the server where possible, and introduce client components only for interactions that need browser state.
Preserve product continuity
The migration is framed as staged risk reduction. Existing behavior, SEO signals, and integration constraints remain acceptance criteria instead of being postponed until after a large rewrite.
Results
- A public, six-minute first-part guide covering route structure, router API changes, metadata, and data fetching with implementation examples.
- A reusable migration checklist that makes hidden cross-cutting work visible before a team commits to scope.
- Concrete public evidence of the approach is available in the linked article; client-specific implementations remain intentionally undisclosed.
Lessons
- Framework migrations are product changes because routing, loading, errors, and metadata are all part of the user experience.
- Breaking the work into observable behaviors makes progress and regression risk easier to discuss with non-specialists.
- A migration is more credible when it names what must stay stable, not only what the new architecture enables.
What this case study can show
The public article captures the structure and technical reasoning I used after migrating several projects. It deliberately does not identify clients, codebases, commercial metrics, or internal constraints. The evidence here is therefore the published method itself: a staged inventory of changes and examples that another engineer can inspect and challenge.
Why it matters
Migration plans often focus on the destination architecture and understate the path. This playbook treats navigation, rendering, SEO, loading states, and integrations as product behavior. That framing helps a team discuss sequencing and risk before implementation details take over.