Migrating: App Router | Next.js (original) (raw)

How to migrate from Pages to the App Router

This guide will help you:

• Update your Next.js application from version 12 to version 13
• Upgrade features that work in both the pages and the app directories
• Incrementally migrate your existing application from pages to app

Upgrading

Node.js Version

The minimum Node.js version is now v18.17. See the Node.js documentation for more information.

Next.js Version

To update to Next.js version 13, run the following command using your preferred package manager:

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

ESLint Version

If you're using ESLint, you need to upgrade your ESLint version:

npm install -D eslint-config-next@latest

Good to know: You may need to restart the ESLint server in VS Code for the ESLint changes to take effect. Open the Command Palette (cmd+shift+p on Mac; ctrl+shift+p on Windows) and search for ESLint: Restart ESLint Server.

Next Steps

After you've updated, see the following sections for next steps:

• Upgrade new features: A guide to help you upgrade to new features such as the improved Image and Link Components.
• Migrate from the pages to app directory: A step-by-step guide to help you incrementally migrate from the pages to the app directory.

Upgrading New Features

Next.js 13 introduced the new App Router with new features and conventions. The new Router is available in the app directory and co-exists with the pages directory.

Upgrading to Next.js 13 does not require using the App Router. You can continue using pages with new features that work in both directories, such as the updated Image component, Link component, Script component, and Font optimization.

Component

Next.js 12 introduced new improvements to the Image Component with a temporary import: next/future/image. These improvements included less client-side JavaScript, easier ways to extend and style images, better accessibility, and native browser lazy loading.

In version 13, this new behavior is now the default for next/image.

There are two codemods to help you migrate to the new Image Component:

• next-image-to-legacy-image codemod: Safely and automatically renames next/image imports to next/legacy/image. Existing components will maintain the same behavior.
• next-image-experimental codemod: Dangerously adds inline styles and removes unused props. This will change the behavior of existing components to match the new defaults. To use this codemod, you need to run the next-image-to-legacy-image codemod first.

Component

The Component no longer requires manually adding an <a> tag as a child. This behavior was added as an experimental option in version 12.2 and is now the default. In Next.js 13, <Link> always renders <a> and allows you to forward props to the underlying tag.

For example:

import Link from 'next/link'
 
// Next.js 12: `<a>` has to be nested otherwise it's excluded
<Link href="/about">
  <a>About</a>
</Link>
 
// Next.js 13: `<Link>` always renders `<a>` under the hood
<Link href="/about">
  About
</Link>

To upgrade your links to Next.js 13, you can use the new-link codemod.