Back

Guide

Jul 03, 2023

Back

Guide

Jul 03, 2023

Migrating from Pages Router to App Router: An Incremental Guide

Colin Sidoti

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:

/pages/_document.tsx1
import { Html, Head, Main, NextScript } from 'next/document'
2
 
3
export default function Document() {
4
  return (
5
    <Html>
6
      <Head />
7
      <body>
8
        <Main />
9
        <NextScript />
10
      </body>
11
    </Html>
12
  )
13
}

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 type React.ReactNode
Remove <NextScript /> entirely

When complete, /app/layout.tsx should look more like this, plus your customizations:

/app/layout.tsx1
export default function RootLayout({
2
  children,
3
}: {
4
  children: React.ReactNode
5
}) {
6
  return (
7
    <html lang="en">
8
      <body>{children}</body>
9
    </html>
10
  )
11
}

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:

/pages/_app.tsx1
import type { AppProps } from 'next/app'
2
 
3
export default function MyApp({ Component, pageProps }: AppProps) {
4
  return <Component {...pageProps} />
5
}

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 and pageProps arguments, it should only take a children argument. For Typescript users, children is of type React.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 accessing pageProps here
We recommend changing the default export name from MyApp to ClientLayout. It is not strictly necessary, but it is more conventional

When complete, /app/ClientLayout.tsx should look more like this, plus your customizations:

/app/ClientLayout.tsx1
"use client"
2
 
3
export default function ClientLayout({
4
  children,
5
}: {
6
  children: React.ReactNode
7
}) {
8
  return <>{children}</>
9
}

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:

/app/layout.tsx1
import ClientLayout from "./ClientLayout"
2

3
export default function RootLayout({
4
  children,
5
}: {
6
  children: React.ReactNode
7
}) {
8
  return (
9
    <html lang="en">
10
      <body>
11
        <ClientLayout>
12
          {children}
13
        </ClientLayout>
14
      </body>
15
    </html>
16
  )
17
}

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.):

page.tsx1
import ClientPage from "./ClientPage"
2

3
export default async function Page() {
4
  return <ClientPage />
5
}

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:

1
export const getStaticProps: GetStaticProps<PageProps> = async () => {
2
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
3
  const repo = await res.json()
4
  return { props: { repo } }
5
}

To migrate this with as little modification as possible, we will:

Copy-paste getStaticProps into page.tsx
Call getStaticProps from within our Page 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:

page.tsx1
import ClientPage from "./ClientPage"
2
 
3
export const getStaticProps: GetStaticProps<PageProps> = async () => {
4
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
5
  const repo = await res.json()
6
  return { props: { repo } }
7
}
8

9
export const dynamic = "force-static"
10

11
export default async function Page() {
12
  const { props } = await getStaticProps();
13
  return <ClientPage {...props} />
14
}

Migrating getServerSideProps to the App Router

Consider the following implementation of getServerSideProps:

1
import { getAuth } from "@clerk/nextjs/server"
2

3
export const getServerSideProps: GetServerSideProps<PageProps> = async ({ req }) => {
4
  const { userId } = getAuth(req);
5

6
  const res = await fetch('https://api.example.com/foo', {
7
    headers: {
8
      Authorization: `Bearer: ${process.env.API_KEY}`
9
    }
10
  })
11
  const data = await res.json()
12
  return { props: { data } }
13
}
14

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
1. Our example uses Clerk for authentication, so the end result will replace this line with its App Router-compatible replacement
2. Replace req.headers with the new headers() helper
3. Replace req.cookies with the new cookies() helper
4. Replace req.url.searchParams with the new searchParams helper
Replace any Dynamic Route segment usage with the new params helper
Call getServerSideProps from within our Page component
Pass the result to our (not yet created) ClientPage component

Here is the end result:

page.tsx1
import { auth } from "@clerk/nextjs"
2
import ClientPage from "./ClientPage"
3

4
export const getServerSideProps: GetServerSideProps<PageProps> = async () => {
5
  const { userId } = auth();
6

7
  const res = await fetch('https://api.example.com/foo', {
8
    headers: {
9
      Authorization: `Bearer: ${process.env.API_KEY}`
10
    }
11
  })
12
  const data = await res.json()
13
  return { props: { data } }
14
}
15

16
export const dynamic = "force-dynamic"
17

18
export default async function Page() {
19
  const { props } = await getServerSideProps();
20
  return <ClientPage {...props} />
21
}

Migrating getStaticPaths to the App Router

Consider the following implementation of getStaticPaths:

1
export async function getStaticPaths() {
2
  return {
3
    paths: [{ params: { id: '1' } }, { params: { id: '2' } }],
4
  }
5
}

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:

page.tsx1
import ClientPage from "./ClientPage"
2

3
export async function getStaticPaths() {
4
  return {
5
    paths: [{ params: { id: '1' } }, { params: { id: '2' } }],
6
  }
7
}
8

9
export async function generateStaticParams() {
10
  const staticPaths = await getStaticPaths();
11
  return staticPaths.paths.map(x => x.params);
12
}
13

14
export const getStaticProps: GetStaticProps<PageProps> = async ({ params }) => {
15
  const res = await fetch(`https://api.example.com/foo/${params.id}`)
16
  const data = await res.json()
17
  return { props: { data } }
18
}
19

20
export default async function Page({ params }) {
21
  const { props } = await getStaticProps({ params });
22
  return <ClientPage {...props} />
23
}

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.