Services

Pages Router to App Router Migration for Mature Next.js Codebases

Use this page if the App Router move changes runtime behaviour enough that the Next.js migration needs planning like a platform migration, not a mechanical file conversion.

Move a mature Next.js codebase to the App Router without turning caching, rendering, and middleware changes into launch risk.

Typical symptoms

  • The current Pages Router codebase is blocking newer Next.js platform features.
  • Teams want App Router features but do not want a risky big‑bang rewrite.
  • Caching and rendering semantics are not well understood across the migration.

Likely causes

  • The current codebase mixes assumptions that do not translate directly into the App Router.
  • Server and client boundaries are not yet explicit enough for a safe migration.
  • The migration path has not accounted for caching, middleware, and route ownership changes.

What I look at first

  • Quick check: map the routes that rely on middleware, caching assumptions, or browser‑only behaviour before you move them.
  • Which routes need to move first and which can remain in the Pages Router temporarily.
  • Where caching and rendering changes will affect behaviour after migration.

How I help fix this

  • Plan a route‑by‑route migration that avoids unnecessary platform shocks.
  • Clarify server, client, and caching boundaries before implementation.
  • Support the migration through the highest‑risk route types first.

When to bring me in

  • Bring me in before the first migration slice bakes in the wrong caching and server/client boundaries.
  • Bring me in when the team understands the desire to move but not yet the operational cost of moving.

Related technical articles

Selected project context

  1. Virgin Atlantic
    & Holidays

    Lead engineer on this massive replatforming project, unifying twelve disparate applications under a new headless architecture with React and Next.js.

    Screenshot of the Virgin Atlantic & Holidays website; part of John Kavanagh's development portfolio.

Related services

  1. Parent hub

    Migrations to Next.js

    Choose the right Next.js migration path when an older front end, legacy platform, or hard‑to‑maintain site needs a cleaner architecture and safer migration plan.

  2. Capability

    Next.js Platform Consulting

    Bring in senior Next.js architecture support when a legacy platform, older front end, or hard‑to‑maintain site needs migration planning, platform rescue, and clearer delivery direction.

  3. Adjacent scenario

    Drupal to Next.js Migration

    Move a Drupal‑led estate to Next.js without losing aliases, preview behaviour, or SEO continuity on content‑heavy routes.

Questions teams usually ask

Do we have to migrate the whole codebase at once?
No. In most mature codebases the safer route is phased adoption, keeping lower-risk routes or shared utilities in place while the first App Router slices prove the new rendering and caching model.
Is this mainly a routing task or a caching task?
Usually both. The file moves are the smallest part of the work; the real risk sits in caching behaviour, server and client boundaries, and middleware assumptions that no longer behave the same way.

Tell me what needs fixing

Send me the affected page or route, point me at the code if that helps, and tell me what you expected to happen versus what is happening now. If this connects to a Next.js migration, technical SEO drop, performance issue, launch, or platform move, include that context too. I'll come back with the clearest next step.

Send the details
Skip past clients

Previous Clients