Pages Router

In the Pages Router every file in pages/ that exports a React component is a route, every file in pages/api/ is a server-only endpoint, and a handful of reserved files (_app, _document, _error, 404, 500) customise how pages are initialised, wrapped in HTML and shown when something goes wrong. Data is not fetched by components: it is fetched by an exported data function next to the page, which runs on the server and hands its result to the component as props. The page component itself is a normal React component that is rendered on the server (for the first HTML) and again in the browser (hydration), which is why, in the App Router’s vocabulary, every Pages Router component is a Client Component.

The scratch app used on this page has these routes. next build prints them in a table headed Route (pages):

Source: Pages Router: Project Structure

The symbols are the ones used on the App Router pages: ○ is a statically optimised page, ● a page generated with getStaticProps (the table lists each path that getStaticPaths produced), and ƒ a page rendered per request. /_app has no symbol because it is not a route. /books/[id] shows a Revalidate of 1m because its getStaticProps returns revalidate: 60, and an Expire of 1y. The legacy /legacy page is ƒ because it uses getInitialProps, which, as explained below, always renders on request.

The Pages Router maps files to URLs. The conventions are the ones the App Router later kept in spirit but not in file names (there is no page.tsx here: the file is the page).

A specific route wins over a dynamic one, and a dynamic one over a catch-all (the official dynamic routes page lists the exact precedence). One practical limit is worth remembering: every file under pages/ that matches the configured page extensions is a route, so you do not colocate components or tests there the way the App Router lets you colocate files next to page.tsx; keep them in a components/ folder (as the examples do) or restrict the extensions with pageExtensions in next.config.ts.

The dynamic route and its helpers are the best illustration of how the Pages Router splits a route in two: the component renders, and the data functions decide what to render and when. The [id] page used throughout this page is shown in full in the data functions section; the dynamic-routes mechanics (parameters, precedence, catch-alls) are explained, with the App Router syntax, on Dynamic Routes and Route Groups.

Source: Pages Router: Routing, Pages Router: Dynamic Routes and pageExtensions

pages/_app.tsx overrides the App component Next.js uses to initialise every page. It receives Component (the active page; it changes on every client-side navigation) and pageProps (the props the page’s data function returned, or an empty object). It is the place to render a layout that persists across navigations, to inject shared data, and to import global CSS — in the Pages Router a global stylesheet may only be imported here. Providers for React Context, a Redux store or an authentication session wrap Component in this file; that is the pattern both books use, and it is also why a Pages Router app is hard to make lean: whatever _app imports is bundled into every page.

Source: Pages Router: Custom App and Pages Router: Pages and Layouts

A page opts into a different layout by setting Page.getLayout, which _app calls (the official pages-and-layouts page calls this the per-page layouts pattern). Component.getLayout is the single piece of layout machinery of the Pages Router; it is replaced by native nested layouts in the App Router, as the migration section shows. Three caveats from the official page matter in practice:

pages/_document.tsx customises the <html> and <body> that wrap every page. It is rendered only on the server, so event handlers such as onClick do not work in it, and the components it uses (Html, Head, Main and NextScript, all imported from next/document) are all required for the page to render correctly.

Source: Pages Router: Custom Document

curl of any page returned <html lang="en"> and the application-name meta tag in <head>. The caveats are the reverse of `_app’s:

next/head renders elements into the document head from inside any component, which is how the Pages Router handles titles and meta tags. Two details from the official page and from our run: elements must be direct children of Head (or wrapped in at most one level of fragment or array) or they are not picked up on client-side navigations, and the <title> should receive one string. In the scratch app <title>{book.title} - Bookshelf</title>, whose children React sees as an array, produced an empty <title></title> in the server HTML, while the template literal form <title>{${book.title} - Bookshelf`}</title>` produced <title data-next-head="">Dune - Bookshelf</title>. In the App Router next/head is replaced by the Metadata API (see the migration table).

Source: Pages Router: Head

The Pages Router has three levels of error pages, all in pages/:

Source: Pages Router: Custom Errors

After next build and next start, curl -i /nope returned 404 with the body 404 - Page Not Found (the generated .next/server/pages/404.html contains it). A getServerSideProps that throws, on a temporary /boom page, returned 500 with 500 - Server-side error occurred and logged the stack trace on the server. Because 404.tsx and 500.tsx are rendered inside your custom _app, your global styles and theme apply to them, unlike the built-in pages, which follow the operating system’s colour scheme.

To show the built-in error page from a page (for example when an upstream API fails) import Error from next/error and render it with a statusCode; the component also accepts a title. If you define your own _error, import that one instead. _error, like _app, is a reserved pathname: /_error rendered directly returns 404 (our curl /_error did), and _error does not support the data functions.

Source: Pages Router: Custom Errors

Any file in pages/api/ is mapped to /api/* and treated as an endpoint instead of a page. API routes are server-only bundles: they add nothing to the client bundle. The handler receives a Node.js req (http.IncomingMessage, extended with req.cookies, req.query and req.body, the body parsed by content-type) and a res (http.ServerResponse, extended with res.status(code), res.json(body), res.send(body), res.redirect([status,] path) and res.revalidate(urlPath)). This is the Node.js-style API that the books use; it is not the Web Request/Response API of App Router Route Handlers.

Source: Pages Router: API Routes

The behaviour to remember about API routes:

res.revalidate is the Pages Router’s on-demand ISR trigger and must be protected, because anyone who can call it can make your server regenerate pages. The example reads the token from the environment (the value shown is a placeholder):

Source: Pages Router: Incremental Static Regeneration

GET on the same route returned 405. The App Router replacement is revalidatePath or revalidateTag called from a Route Handler or a Server Action, covered on Incremental Static Regeneration and Route Handlers and Backend for Frontend.

The Pages Router has two ways to navigate: the Link component from next/link (declarative, prefetches in production) and the router from next/router (programmatic). useRouter() is a React Hook, so it cannot be used in class components; withRouter is the class-component alternative, and a function component can wrap a class.

The methods are router.push(url, as, options) (adds a history entry), router.replace (same parameters, no new entry), router.prefetch (production only; Next.js does not prefetch in development), router.back, router.reload (a full reload), router.beforePopState(cb) to intercept popstate events, and router.events. url can be a string or a URL object ({ pathname: "/books", query: { q } }), and the options include shallow to change the URL without re-running the data functions. External URLs do not need the router: use window.location. The router fires routeChangeStart, routeChangeComplete, routeChangeError, beforeHistoryChange, hashChangeStart and hashChangeComplete; each callback receives the URL and an object with shallow.

Source: Pages Router: useRouter

Subscribe to events in an effect and unsubscribe in its cleanup, as shown; _app is a convenient place for global handlers because it is not unmounted on navigation. When a navigation to the same page with a different parameter must reset component state, either update the state in an effect or give the component a key so React remounts it.

Two version-specific facts matter when the two routers coexist. useRouter from next/router is not supported in the app directory (it can keep being used in pages); the App Router has its own useRouter from next/navigation that does not return pathname or query, which are replaced by usePathname, useSearchParams and useParams. And next/compat/router exports a useRouter that returns null instead of throwing when the Pages Router is not mounted, which lets one component run in both routers during a migration. For linking details see Linking and Navigation.

A page that needs data exports one of three functions, and each one decides when the page is rendered. They run only on the server (their code is removed from the client bundle), and what they return reaches the browser as JSON serialised into the page, so it must be serialisable (no Date, Map or Set) and nothing secret may be returned as a prop.

Next.js decides on its own that a page is static when it has no blocking data requirement, which it infers from the absence of getServerSideProps and getInitialProps. That page is prerendered to HTML at build time without you writing a data function; it is still hydrated and fully interactive. The home page of the scratch app (pages/index.tsx, a page with next/head and useRouter but no data function) is shown as ○ in the route table, and next build wrote .next/server/pages/index.html. The official page’s example makes the rule visible: pages/about.js is emitted as .next/server/pages/about.html while adding getServerSideProps turns it into JavaScript (about.js) that renders per request.

The consequences of a static page that you must plan for:

Source: Pages Router: Automatic Static Optimization

The server response for /?name=Ada contained Greeting for: reader and an empty "query":{} in NEXT_DATA: the HTML is the prerendered one, and Ada appears only after hydration. That is the whole point of the optimisation (the file is served from a CDN without running anything) and the whole source of the "flash of default content" on query-driven pages; when the first render must depend on the query, use getServerSideProps instead. The hydration side of this is explained on Hydration and the client-rendered half on Client-Side Rendering.

Some Pages Router features have no App Router counterpart of the same shape, and a few have none at all. Knowing which is which is the first step of a migration plan.

Source: Pages Router: Internationalization, Pages Router: Preview Mode, Pages Router: Draft Mode and Upgrading to version 16

The removals in the last rows are the part of Next.js 16 that hits Pages Router projects specifically: the upgrade guide’s example for the removed publicRuntimeConfig is written for pages/index.tsx, and AMP removal affects pages that used useAmp. The Pages Router i18n configuration and the legacy next-i18next setup are covered with their App Router alternatives on Internationalization; draft mode and previews belong to the Advanced Patterns page, which is written alongside this one. Middleware, now called Proxy, is configured the same way for both routers (see Redirects, Rewrites and Proxy).

The Pages Router has a short list of caches, none of which cacheComponents changes: the build output of static and getStaticProps pages, the ISR cache (visible through x-nextjs-cache), the Cache-Control headers that you set (and that Next.js sets on ISR responses, as in the output above). Everything else is request-time. To check that, the Pages Router scratch app was built with CACHE_COMPONENTS=1 (which sets cacheComponents: true) and with it unset: the route table was identical in both modes.

Cache Components starts to matter per route that you move. In the migrated copy of the app (below) the new app/books route reads searchParams. With the previous model it built and served as ƒ. With Cache Components the same page failed next build with Route "/books": Next.js encountered uncached or runtime data during prerendering and the message blocking-prerender-dynamic; the fix is to read searchParams inside a component wrapped in Suspense, as the Partial Prerendering and Cache Components and Caching pages explain. So an application can turn cacheComponents on while it still has pages routes, provided the routes already in app follow the new rules. The mapping of getStaticProps and revalidate to caching APIs depends on the model you target; the table below names both.

The App Router was designed to work alongside the Pages Router: the app directory and the pages directory can both be present, and routes can be moved one at a time. The official migration guide recommends splitting the change into small steps, because moving to the App Router may be the first time you meet Server Components, Suspense and the new data model at once. The order that follows is the guide’s, with the Next.js 16 corrections called out.

Before the steps, remember what the two routers share and what they do not:

This page’s own version-by-version claims come from the 16 upgrade guide and the Pages Router API pages' version history tables; the full 13 to 16.3 change log is on the upgrade page of this section. The practical effect of 16.0 on a Pages project: the build uses Turbopack unless you pass --webpack, so any custom webpack configuration, Babel config or loader must be checked, and next lint is gone in favour of running ESLint directly.

The consulted books are written for the Pages Router (Next.js 12, React 17 and Next.js 13.2, React 18), so almost all of their structure still applies; what has moved is below.