---
title: "Upgrading and Migration"
description: "Keeping your Next.js application up-to-date ensures you have access to the latest performance improvements, security patches, and new features like the App Router, Turbopack, and React updates. Nex..."
last_updated: "2026-09-23T10:57:21.246404+00:00"
canonical_url: "https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/troubleshooting/upgrading-and-migration"
---

## Overview

Keeping your Next.js application up-to-date ensures you have access to the latest performance improvements, security patches, and new features like the App Router, Turbopack, and React updates. Next.js provides built-in CLI commands and automated code transformation tools (codemods) to streamline upgrading your dependencies and refactoring your codebase.

> [!NOTE]
> Before running any upgrade commands or codemods, make sure your git working directory is completely clean by committing or stashing your changes, or use the `--force` flag to bypass this safety check.

---

## Upgrading Next.js Versions

### ### Overview

You can upgrade your Next.js application to a newer version or distribution channel using the built-in upgrade command.

### How to Upgrade

1. Open your terminal and navigate to your project directory.
2. Run the upgrade command, specifying your target version or distribution channel if desired:

```bash
npx @next/codemod upgrade
```

### Revision Options

When running the upgrade command, you can specify a target revision to determine which version of Next.js to install.

Supported revisions:
- **NPM dist tags**: `latest`, `canary`, `rc`, `beta`
- **Semantic version types**: `patch`, `minor`, `major`
- **Exact version numbers**: e.g., `15.0.0`

> [!TIP]
> If you do not provide a revision, the upgrade command automatically defaults to `minor` or matches your project's current release channel (such as `canary`).

---

## Running Automated Codemods

### ### Overview

Codemods are automated scripts that programmatically update your source code to handle breaking changes, rename deprecated components or configuration properties, and adopt new API conventions across major versions.

### Running a Specific Codemod

You can apply a specific codemod to your project files by running the transform tool and passing the codemod name:

```bash
npx @next/codemod <codemod-slug> [source-path]
```

### Available Codemod Transforms

The following automated transforms are available to help refactor your codebase across different Next.js versions:

| Codemod Slug | Minimum Version | Description |
| :--- | :--- | :--- |
| `url-to-withrouter` | `6.0.0` | Transform deprecated automatically injected `url` property on top-level pages to use `withRouter`. |
| `name-default-component` | `9.0.0` | Transform anonymous components into named components to ensure compatibility with Fast Refresh. |
| `add-missing-react-import` | `10.0.0` | Add missing React imports to files to support the new React JSX transform. |
| `cra-to-next` | `11.0.0` | Automatically migrate a Create React App project to Next.js (experimental). |
| `next-image-experimental` | `13.0.0` | Dangerously migrate from `next/legacy/image` to `next/image` by adding inline styles and removing unused props (experimental). |
| `next-image-to-legacy-image` | `13.0.0` | Safely migrate applications importing `next/image` to the renamed `next/legacy/image` import. |
| `built-in-next-font` | `13.2.0` | Uninstall `@next/font` and transform imports to use the built-in `next/font`. |
| `metadata-to-viewport-export` | `14.0.0` | Migrate viewport-related metadata from the `metadata` export to a new `viewport` export. |
| `next-og-import` | `14.0.0` | Transform imports from `next/server` to `next/og` for Dynamic OG Image Generation. |
| `next-request-geo-ip` | `15.0.0-canary.153` | Install `@vercel/functions` to replace `geo` and `ip` properties on `NextRequest`. |
| `next-async-request-api` | `15.0.0-canary.171` | Transform usage of Next.js async Request APIs. |
| `app-dir-runtime-config-experimental-edge` | `15.0.0-canary.179` | Transform App Router Route Segment Config `runtime` value from `experimental-edge` to `edge`. |
| `next-experimental-turbo-to-turbopack` | `15.4.2-canary.21` | Update `next.config.js` to use the new top-level `turbopack` configuration. |
| `next-lint-to-eslint-cli` | `15.4.2-canary.55` | Migrate from `next lint` to the standalone ESLint CLI. |
| `middleware-to-proxy` | `15.6.0-canary.54` | Migrate from the deprecated `middleware` convention to `proxy`. |
| `remove-unstable-prefix` | `16.0.0-canary.10` | Remove the `unstable_` prefix from stabilized APIs. |
| `remove-experimental-ppr` | `16.0.0-canary.11` | Remove `experimental_ppr` Route Segment Config from App Router pages and layouts. |

> [!WARNING]
> Codemods modify your application files directly. Always review the changes in your version control system after running a transform.

---

## Workflow Summary

The standard upgrade and migration workflow follows these steps:

```mermaid
flowchart TD
    A[Clean Git Working Directory] --> B[Run Upgrader or Codemod]
    B --> C[Review Automated Code Changes]
    C --> D[Test Application Build]
```

## Related

- [Installation and Setup](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/getting-started/installation-and-setup)
- [Project Structure Overview](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/getting-started/project-structure-overview)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/llms.txt) for all pages in this wiki.