Next Upgrade

Next Upgrade is a community skill for migrating and upgrading Next.js applications, covering version migration strategies, App Router adoption, API route conversion, configuration updates, and codemods for automated code transformation.

What Is This?

Overview

Next Upgrade provides patterns for upgrading Next.js applications between major versions. It covers version migration with dependency updates, breaking change resolution, and incremental upgrade paths, App Router adoption for migrating from Pages Router with parallel route support during transition, API route conversion from pages/api to app/api with new request and response handling, configuration updates for next.config changes, middleware migration, and new compiler options, and codemods using next/codemod for automated transformation of deprecated patterns. The skill enables teams to upgrade Next.js applications with minimal disruption and reduced risk of regression.

Who Should Use This

This skill serves teams planning major Next.js version upgrades with minimal downtime, developers migrating from Pages Router to App Router incrementally, and engineers resolving breaking changes and deprecated APIs during upgrades.

Why Use It?

Problems It Solves

Major version upgrades introduce breaking changes that require coordinated code updates. Pages Router to App Router migration cannot happen all at once in large applications. Deprecated APIs need systematic replacement before they are removed. Configuration changes between versions require careful review to maintain existing behavior.

Core Highlights

Codemods automate common migration patterns like import changes and API updates. Incremental App Router adoption allows pages and app directories to coexist during migration. Version upgrade checklist tracks breaking changes requiring manual attention. Test verification confirms behavior preservation after each migration step.

How to Use It?

Basic Usage

#!/bin/bash

npm install next@latest \\
  react@latest \\
  react-dom@latest

npx @next/codemod@latest \\
  upgrade latest

npx next build 2>&1 \\
  | grep -i error

npm test

npx @next/codemod@latest \\
  next-image-to-legacy-image .

npx @next/codemod@latest \\
  new-link .

npx @next/codemod@latest \\
  app-dir-api-routes .

Real-World Examples

// Pages Router -> App Router
// BEFORE: pages/products/[id].tsx
// export async function
//   getServerSideProps(ctx) {
//   const product =
//     await getProduct(ctx.params.id);
//   return { props: { product } };
// }

// AFTER: app/products/[id]/page.tsx
interface Props {
  params: Promise<{ id: string }>;
}

export default async function
    ProductPage({
      params }: Props) {
  const { id } = await params;
  const product =
    await getProduct(id);

  return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.description}</p>
      <span>
        ${product.price}
      </span>
    </div>
  );
}

// BEFORE: pages/api/products.ts
// export default function
//   handler(req, res) {
//   res.json({ products: [] });
// }

// AFTER: app/api/products/route.ts
export async function GET() {
  const products =
    await db.products.findMany();
  return Response.json({
    products });
}

export async function POST(
  request: Request
) {
  const body =
    await request.json();
  const product =
    await db.products.create({
      data: body });
  return Response.json(
    product,
    { status: 201 });
}

Advanced Tips

Run codemods on a clean git branch to review changes before merging. Migrate routes incrementally by moving one section at a time from pages to app directory. Use Next.js middleware for redirects during migration when URLs change between routers.

When to Use It?

Use Cases

Upgrade a Next.js 13 application to the latest version with automated codemods and manual breaking change resolution. Migrate a Pages Router application to App Router incrementally over multiple sprints. Convert pages/api routes to app/api route handlers with new response patterns.

Related Topics

Next.js migration, App Router, codemods, breaking changes, and version upgrades.

Important Notes

Requirements

Git version control for tracking migration changes. Existing test suite for verifying behavior after upgrades. Node.js version compatible with the target Next.js version.

Usage Recommendations

Do: upgrade one major version at a time rather than skipping multiple versions. Run the full test suite after each migration step to catch regressions early. Review the official upgrade guide for each version for breaking changes.

Don't: attempt a full Pages Router to App Router migration in a single pull request for large applications. Run codemods without reviewing the generated changes. Upgrade production without testing the build and all critical user flows.

Limitations

Codemods cannot handle all migration patterns and manual changes are often required. Pages Router and App Router coexistence adds complexity during the transition period. Some third-party packages may not support the latest Next.js version immediately after release.