Migrating from Pages Router to App Router: An Incremental Guide
- Category
- Guides
- Published
Already know the /pages directory? Here's a simple way to migrate to the /app directory in Next.js 13.
The Next.js App Router (in the /app directory) is a new way to build React applications. If you're already familiar with the Pages Router (in the /pages directory), Next.js has made it really easy to adopt the App Router incrementally, quite literally on a page-by-page basis. This guide explains how.
How is this guide different?
The App Router already has a migration guide, so how is this different?
We want to demonstrate a 1-to-1 mapping of Pages Router to App Router, but this is not a complete migration. In the snippets below you will see obvious potential refactors, and that is on purpose.
As an example, one App Router snippet below still has function called getServerSideProps
. It doesn't make sense to keep that name, but we want to demonstrate how getServerSideProps
can be expressed in the context of the App Router.
One more disclaimer: this will not explain how to migrate everything. We focused on the best practices for the Pages Router in Next.js 12.3, but left out older APIs like getInitialProps
.
One quick clarification
You probably know that the App Router supports both Client Components and the newly introduced Server Components.
Before the App Router, Client Components were just called Components. We want to clarify that after the App Router, absolutely nothing has changed about them.
Most importantly, within the App Router, Client Components are still rendered on the server, then hydrated on client. Search engine crawlers can still index their HTML.
Within this guide, the React code from your Pages Router will be copied to new files and labeled with "use client"
at the top. This is expected, since we're doing a 1-to-1 mapping.
Migrating from the Pages Router to the App Router
0. Create the /app directory
Before you can get started with the App Router, you will first need to create a /app directory as a sibling to your /pages directory.
1. Migrate /pages/_document to the App Router
If you have a Custom Document at /pages/_document.tsx, it should look something like this, though likely with some customization:
We need to convert this into a Root Layout, which can be treated as a 1-to-1 corollary to a Custom Document:
- Clone /pages/_document.tsx into /app/layout.tsx. We will keep both files since we're doing incremental adoption. (If you use .jsx that is no problem, you can use layout.jsx instead)
- Remove the next/document import line entirely
- Replace
<Html>
and</Html>
with the lowercase, HTML equivalent<html>
and</html>
. For accessibility, it's best to add a language to your opening tag, like<html lang="en">
- Replace
<Head>
and</Head>
with the lowercase, HTML equivalent<head>
and</head>
. If you only have a self-closing<Head />
, you can remove it entirely - Replace
<Main />
with{children}
, and update the default function export to accept a{children}
argument. For Typescript users,children
is of typeReact.ReactNode
- Remove
<NextScript />
entirely
When complete, /app/layout.tsx should look more like this, plus your customizations:
Important: /app/layout.tsx is required in the /app directory. If you do not have a Custom Document, you can copy-paste the above sample directly into /app/layout.tsx.
2. Migrate /pages/_app.tsx to the App Router
Note: If you do not have a file at /pages/_app.tsx you can skip to Step 3.
If you have a Custom App at /pages/_app.tsx, it should look something like this, though likely with some customization:
The /app directory does not have a 1-to-1 corollary for a Custom App, but it can easily be expressed in the new structure:
- Clone /pages/_app.tsx into /app/ClientLayout.tsx. We will keep both files since we're doing incremental adoption. (If you use .jsx that is no problem, you can use ClientLayout.jsx instead)
- Add a new line to the top of the file that reads
"use client"
(with the quotes) - Replace the default export's function signature. Instead of taking
Component
andpageProps
arguments, it should only take achildren
argument. For Typescript users,children
is of typeReact.ReactNode
. - Replace
<Component {...pageProps} />
with<>{children}</>
, or just{children}
if you have another wrapping element - If there are any remaining references to
pageProps
, please comment them out for now, and revisit them on a page-by-page basis. Next.js has added a new metadata API that should normally be used in place of accessingpageProps
here - We recommend changing the default export name from
MyApp
toClientLayout
. It is not strictly necessary, but it is more conventional
When complete, /app/ClientLayout.tsx should look more like this, plus your customizations:
Now, this is where things get a little different:
- In the Pages Router, /pages/_app.tsx is a "magic" layout file that is automatically added to the React tree
- In the App Router, the only layout file automatically added to the React tree is the Root Layout from Step 1. So, we will need to manually import and mount our
ClientLayout
inside /app/layout.tsx
Open /app/layout.tsx, import ClientLayout, and use it to wrap {children}
. When complete, your Root Layout should look like this, plus any customizations from Step 1:
3. Migrate each page to the App Router
Now that your layout has been copied into the App Router, it's time to start migrating your pages one-by-one. There will be a few steps for each page:
- Create a directory for the page
- Create one file to handle data fetching
- Create one file to render the page
- Remove the Pages Router page
For the avoidance of doubt: yes, we will be splitting your Pages Router page into two files: one for data fetching and one for rendering.
3.1. Create a directory for the page
Both the Pages Router and the App Router are "filesystem routers," but they are organized slightly differently. In the App Router, each page gets its own directory. Here is how to determine the directory name:
- If your file is named index.tsx, create the same parent directory structure
- For /pages/foo/index.tsx, create /app/foo
- For /pages/index.tsx, you already have /app
- If your file is not named index.tsx, create a directory with that filename
- For /pages/bar.tsx, create /app/bar
- For /pages/baz/[slug].tsx, create /app/baz/[slug]
- For /pages/baz/[[...slug].tsx, create /app/baz/[[...slug]]
3.2. Create a file to handle data fetching
Inside your page directory, create a file called page.tsx to handle data fetching. Copy-paste the following snippet as the foundation of this file (Note: we will create ClientPage.tsx in 3.3.):
If your Pages Router file does not have any data fetching, you can continue on to the next step. Otherwise, find your data fetcher below to learn how it can be migrated:
Migrating getStaticProps to the App Router
Consider the following is your implementation of getStaticProps
:
To migrate this with as little modification as possible, we will:
- Copy-paste
getStaticProps
into page.tsx - Call
getStaticProps
from within ourPage
component - Add
export const dynamic = "force-static"
so the page data is fetched once and cached, not refetched on every load - Pass the result to our (not yet created)
ClientPage
component
Here is the end result:
Migrating getServerSideProps to the App Router
Consider the following implementation of getServerSideProps
:
To migrate this with as little modification as possible, we will:
- Copy-paste
getServerSideProps
into page.tsx - Add
export const dynamic = "force-dynamic"
so the page data is refetched on every load - Replace any usage of
req
with the App Router equivalent - Our example uses Clerk for authentication, so the end result will replace this line with its App Router-compatible replacement
- Replace
req.headers
with the new headers() helper - Replace
req.cookies
with the new cookies() helper - Replace
req.url.searchParams
with the new searchParams helper - Replace any Dynamic Route segment usage with the new params helper
- Call
getServerSideProps
from within ourPage
component - Pass the result to our (not yet created)
ClientPage
component
Here is the end result:
Migrating getStaticPaths to the App Router
Consider the following implementation of getStaticPaths
:
In the App Router, this implementation barely changes. It's simply given a new name (generateStaticParams
) and the output is transformed to something simpler. That means you can use your old implementation directly, and simply transform the output.
Here is the end result – we included an example of how it can be used in tandem with getStaticProps
:
3.3. Create a file to render the page
Now that data fetching is ready, we need to configure the rendering. To accomplish this:
- Copy your original Pages Router page into ClientPage.tsx
- Remove any data fetching code, since it now lives in page.tsx
That's it! We have already configured page.tsx to mount this file and pass props, so it should be working.
3.4. Remove the Pages Router page
Now that your page is ready in the App Router, you can delete the old Pages Router variant.
What's next?
Now that your Pages Router application is working in the App Router, it's time to start taking advantage of the App Router and React Server Components.
In particular, right now your ClientPage.tsx files are one big Client Component. Going forward, it's best to refactor this so "use client"
is used as sparingly as possible, ideally only on small components. A big Server Component importing many small Client Components will lead to less Javascript sent to the client, and a faster experience for your end user.
Ready to get started?
Sign up today