Next.js App Router Migration with Codemod

The importance of code migrations

Code migration projects are crucial for making codebases secure and performant, and for keeping users and developers happy and productive. Next.js introduced the App Router as a major architectural improvement that helps developers build more performant apps with a better developer experience. However, large-scale migrations are often tedious and error-prone, especially in larger codebases. As codebases grow, migration campaigns can go from difficult to practically impossible without proper tooling.

Note

There is a better way for code migrations at scale: codemods. These code automation bots automate a vast amount of coding for large migrations. Tech giants such as Meta, Google, and Uber have long automated their migration campaigns with the help of codemods and infrastructure around them.

Codemod: The code automation platform

At Codemod, we combine the power of AI and community to bring migration tools that were once confined to tech giants to every developer. In partnership with Vercel, we built the most comprehensive set of open-source codemods for Next.js migrations.

The Codemod platform includes:

Codemod CLI for running codemods locally with a single command
Codemod Studio for building and testing custom codemods visually
Codemod Registry to discover community and official codemods
Codemod Workflows for orchestrating multi-step migration campaigns

App Router migration for cms-wordpress with Codemod

To demonstrate the migration process, we tested our codemods on the popular cms-wordpress Next.js example, upgrading it from the Pages Router to the App Router.

The codemods automate the following changes:

Generating metadata and generateMetadata functions from <Head> usage
Moving dependencies from pages to the app directory and generating new API route handlers
Migrating useRouter hook usages to the new next/navigation hooks
Removing next/head usages and related component code
Creating boilerplate functions to replace getStaticPaths, getServerSideProps, and getStaticProps

Step 1: Run the migration codemods

No global install needed. Just run:

This executes the App Router migration recipe, which runs a set of codemods sequentially, eliminating the need to find and run each codemod in the correct order.

You can also browse the Codemod Registry to find individual Next.js codemods if you prefer to run them one at a time.

Step 2: Review the automated changes

After running the codemods, review the changes in your diff tool. The codemods handle the mechanical parts of the migration:

Creating the app directory structure
Moving route handlers and page components
Updating imports from next/router to next/navigation
Generating metadata exports from <Head> usage

Most of the migration work is automated, but some project-specific cases may require manual attention.

Step 3: Handle custom cases

Not every transformation can be fully automated. After the codemods run, you may need to handle:

Custom data fetching patterns that don't map directly to Server Components
Complex getStaticPaths return shapes
Third-party libraries that rely on Pages Router APIs

For these cases, you can build custom codemods using Codemod Studio. The Studio provides a visual environment for writing and testing transformations with JSSG, the primary transformation engine, which is built on ast-grep for fast, reliable code matching.

Alternatively, use Codemod MCP to create codemods directly from your IDE using AI assistance.

Step 4: Test, build, and ship

After applying all changes:

Run your test suite to catch any regressions
Build the project to verify there are no compilation errors
Test the application manually, paying attention to routing, data fetching, and dynamic routes
Ship the migration incrementally if possible, starting with simpler pages

Scaling migrations with Codemod

For teams with large codebases or multiple repositories, Codemod provides additional tools:

Codemod Workflows to orchestrate multi-step migrations across repos, combining deterministic codemods with AI-assisted transforms
Codemod Insights to track migration progress across your codebase
Migration campaigns to coordinate changes across teams with automated PR creation and progress tracking

If you have a large Next.js project and prefer to delegate the migration, contact us.