Next.js App Router vs Pages Router
Short answer: the App Router (the app/ directory) is the newer, recommended way to build Next.js apps. It is built on React Server Components, nested layouts and streaming. The Pages Router (the pages/ directory) is the original system and is still supported. You can use both in the same project and migrate gradually.
File structure
# Pages Router
pages/
index.js -> /
about.js -> /about
blog/[slug].js -> /blog/:slug
api/hello.js -> /api/hello
# App Router
app/
layout.js -> root layout
page.js -> /
about/page.js -> /about
blog/[slug]/page.js -> /blog/:slug
api/hello/route.js -> /api/hello
In the App Router a route is a folder, and special files define its behavior: page, layout, loading, error, not-found and route.
Server Components by default
Components in app/ are Server Components unless marked otherwise. They render on the server, can read data directly and send no JavaScript for themselves to the browser. Add "use client" at the top of a file when you need state, effects or browser APIs:
"use client";
import { useState } from "react";
export default function Counter() {
const [n, setN] = useState(0);
return <button onClick={() => setN(n + 1)}>{n}</button>;
}
Read more in Server Components explained and server vs client components.
Data fetching
// Pages Router
export async function getServerSideProps() {
const res = await fetch("https://api.example.com/posts");
return { props: { posts: await res.json() } };
}
// App Router: just await in the component
export default async function Page() {
const res = await fetch("https://api.example.com/posts");
const posts = await res.json();
return <ul>{posts.map((p) => <li key={p.id}>{p.title}</li>)}</ul>;
}
The App Router replaces getStaticProps, getServerSideProps and getInitialProps with async components and caching options. See data fetching in Next.js.
Layouts
With Pages Router you share layout through _app.js and wrapper components, which re-mount on navigation. In the App Router, layout.js files nest and persist across navigation, so shared UI keeps its state.
Metadata and SEO
// App Router
export const metadata = {
title: "My page",
description: "A short description",
};
export async function generateMetadata({ params }) {
return { title: "Post " + params.slug };
}
In Pages Router you use next/head. For tips, see Next.js SEO best practices.
Comparison
| Pages Router | App Router | |
|---|---|---|
| Directory | pages/ | app/ |
| Rendering model | Client components with data functions | Server Components by default |
| Data fetching | getStaticProps / getServerSideProps | async components, fetch caching |
| Layouts | _app.js, manual | Nested layout.js |
| Loading and errors | Manual | loading.js, error.js, Suspense streaming |
| API routes | pages/api | route.js handlers |
| Maturity | Very mature | Newer, actively developed |
Migrating gradually
- Update Next.js and keep the existing
pages/folder. - Create
app/layout.jswith your root HTML structure. - Move routes one at a time into
app/; a path must exist in only one router. - Convert data functions to async Server Components and mark interactive parts with
"use client". - Move API routes to
route.jsfiles when convenient.
Which should you use?
- New project: App Router.
- Large existing Pages Router app: keep it, and migrate page by page when there is a benefit.
- Heavy reliance on libraries that need client-side context: check compatibility with Server Components first.
New to the framework? Start with what Next.js is and the API routes and route handlers guide.
FAQs
Is the Pages Router deprecated?
No. It remains supported, but new features focus on the App Router.
Can I use both routers?
Yes, in the same project, as long as the same URL is not defined in both.
Is the App Router better for SEO?
Both can render full HTML on the server. The App Router makes it easier to render on the server by default and to stream content.
Do I have to rewrite everything?
No. You can migrate incrementally.
