Pages Router basics

The tea shop, with a pages folder

Everything in this course so far used the app folder: the App Router, which came in Next.js 13. Before it, every Next.js app used the pages folder: the Pages Router. Next.js 16.4.3 still supports it, and many apps you'll join were built with it. You don't need all of it to work in one: you need to read the folder, know two special files, answer requests in its API routes, and use its router.

Here is the tea shop as a Pages Router app: a home page, a page for each tea, and an endpoint that lists the teas. It's a real Next.js project, made the way create-next-app makes a Pages Router app, built with next build and run with next start. Click through its files, then open the Steps tab: Chrome typed mint into the search box, clicked Mint tea, then Next tea.

1import "@/styles/globals.css";2import type { AppProps } from "next/app";3import Layout from "@/components/layout";4 5export default function App({ Component, pageProps }: AppProps) {6  return (7    <Layout>8      <Component {...pageProps} />9    </Layout>10  );11}

The pages folder: one file, one route

In the App Router, a folder is a part of the address and a page.tsx file makes it a page (File-system routing). In the pages folder, the file itself is the address:

• pages/index.tsx is /. A file named index is its folder's own page, so pages/teas/index.tsx would be /teas.
• pages/about.tsx would be /about: any file name works, not only index.
• pages/teas/[id].tsx is a dynamic route: [id] matches any one part of the address, like /teas/mint (Dynamic routes).
• pages/api/teas.ts is /api/teas, an endpoint, not a page.

Each page is a React component, exported by default:

1import Head from "next/head";2import { useRouter } from "next/router";3import { teas } from "@/lib/teas";4 5export default function TeaPage() {6  const router = useRouter();7  if (!router.isReady) return <p>Loading…</p>;8  const index = teas.findIndex((tea) => tea.id === router.query.id);9  if (index === -1) return <p>We don't sell that tea.</p>;10  const tea = teas[index];11  const next = teas[(index + 1) % teas.length];12  return (13    <>14      <Head>15        <title>{`${tea.name} | Tea shop`}</title>16      </Head>17      <h1>{tea.name}</h1>18      <p>${tea.price} a box</p>19      <button onClick={() => router.push(`/teas/${next.id}`)}>Next tea</button>20    </>21  );22}23 

Line 2 imports useRouter from next/router, the Pages Router's router, and line 6 calls it. Line 8 reads the address's [id] part from router.query.id. Line 7 waits for router.isReady first, and the recording shows why. Open the Terminal tab: ○ /teas/[id], prerendered as static content. This page has no function that loads its data, so next build made one generic HTML output, reused for every id, before any id was known. In the Network tab, /teas/mint and /teas/oolong got the same HTML, Loading…, with 200. The id arrives in the browser: after hydration, isReady is true and Chrome showed Mint tea and $3 a box, or We don't sell that tea. for oolong.

That's the Pages Router's default for a page with no data function, and it's why its apps use getStaticProps and getServerSideProps: functions that load a page's data on the server, so the HTML holds it. Data fetching in the Pages Router teaches them.

The route table also lists /_app with no symbol, and ○ /404: Next.js's own page for addresses that don't exist, which /nowhere got, with 404. A pages/404.tsx would replace it.

_app and _document

Two files in pages start with an underscore. They have no address; they wrap every page. Each row compares where one job lives in the two routers:

_app: around every page, on the server and in the browser

1import "@/styles/globals.css";2import type { AppProps } from "next/app";3import Layout from "@/components/layout";4 5export default function App({ Component, pageProps }: AppProps) {6  return (7    <Layout>8      <Component {...pageProps} />9    </Layout>10  );11}12 

Next.js renders App for every page, and passes it the page as Component and that page's props as pageProps. Line 8 renders the page. Line 7 wraps it in Layout, the navigation with a search box. Line 1 imports the global CSS: in the Pages Router, _app is where global CSS goes (CSS in Next.js).

When a link changes the page, App stays, and only Component changes, so Layout's state stays too. In the recording's Steps, Chrome typed mint into the search box, then clicked Mint tea: the step made no page load, and the box still said mint. The last step opens /teas/oolong by its address, a full page load, and the box is empty again.

_document: the HTML around it, on the server only

1import { Html, Head, Main, NextScript } from "next/document";2 3export default function Document() {4  return (5    <Html lang="en">6      <Head />7      <body className="tea-shop">8        <Main />9        <NextScript />10      </body>11    </Html>12  );13}14 

_document renders only on the server, when a page's HTML is made (for this shop's static pages, during the build), and never in the browser, so it can't handle a click. Line 5 is the <html> tag with its lang, and line 7 the <body> with a class. Main, on line 8, is where the page goes, and NextScript, on line 9, adds the scripts. Open the recording's Network tab and pick / to see what they made:

• <html lang="en"> and <body class="tea-shop">, from lines 5 and 7.
• <div id="__next">, from Main: the layout and the page inside it, already in the HTML.
• <script id="__NEXT_DATA__" type="application/json">, from NextScript, beside the page's other scripts (the Network tab leaves out every script's contents). It's JSON that the browser reads when the Pages Router starts: the page, its query and its props, in client/index.tsx. The data functions in the next lesson send their data to the browser there.

<Head /> on line 6 is next/document's, and it's only for what every page shares. A page's own title comes from Head in next/head, a different component: the tea page's line 15 sets Mint tea | Tea shop, which Chrome showed as the tab's title.

API routes

Every file in pages/api is an API route: an endpoint that answers with data instead of a page. They are the Pages Router's counterpart to the App Router's Route Handlers, and the build marks them ƒ, server-rendered on demand.

1import type { NextApiRequest, NextApiResponse } from "next";2import { teas, type Tea } from "@/lib/teas";3 4export default function handler(req: NextApiRequest, res: NextApiResponse<Tea[] | { error: string }>) {5  if (req.method !== "GET") {6    res.setHeader("Allow", "GET");7    return res.status(405).json({ error: "Only GET is allowed." });8  }9  res.status(200).json(teas);10}11 

Line 4 is the one function the file exports: handler, with req, the request, and res, the response. They are Node.js's request and response objects, with a few helpers Next.js adds. Every method arrives here, so line 5 checks req.method. Anything but GET gets line 6's Allow: GET header and line 7's 405. Line 9 sends the teas with 200.

In the recording's Network tab, /api/teas answered 200 with the three teas as JSON. POST, from another program sent {"name":"Oolong"} and got 405, allow: GET and {"error":"Only GET is allowed."}.

Here is the same endpoint as an App Router Route Handler, to compare (not recorded here; the Route Handlers lesson records them):

import { teas } from "@/lib/teas";

// Only GET is exported, so Next.js answers a POST with 405 by itself.
export async function GET() {
  return Response.json(teas);
}

A Route Handler exports a function for each method, here only GET, and Next.js answers a POST with 405 by itself. It takes the web's Request and returns a Response, where an API route writes to res. Both are public: anyone can send them anything, so one that reads or changes private data checks who is asking first, as Authorization and the data access layer does.

next/link and next/router

Link is imported from next/link in both routers. In the Pages Router, a click on one swaps the page in place, without loading a new document: the home page's links did that in the recording. To move from code instead, like after a button press, use the router. The tea page's line 19 calls router.push with the next tea's address, and in Steps, Click Next tea moved Chrome to /teas/lemon, again with no page load.

Both routers export a hook called useRouter, from two different places, and they are not the same thing:

• next/router's is the Pages Router's: query, isReady, pathname, push, back and more.
• next/navigation's is the App Router's: push, replace, back, refresh, but no query and no isReady. The App Router reads the address with useParams, usePathname and useSearchParams (Linking and navigating).

Mixing them up is a common mistake in an app that has both folders. Each version below was built; before you pick, guess which ones build:

1import Head from "next/head";2import { useRouter } from "next/router";3import { teas } from "@/lib/teas";4 5export default function TeaPage() {6  const router = useRouter();7  if (!router.isReady) return <p>Loading…</p>;8  const index = teas.findIndex((tea) => tea.id === router.query.id);9  if (index === -1) return <p>We don't sell that tea.</p>;10  const tea = teas[index];11  const next = teas[(index + 1) % teas.length];12  return (13    <>14      <Head>15        <title>{`${tea.name} | Tea shop`}</title>16      </Head>17      <h1>{tea.name}</h1>18      <p>${tea.price} a box</p>19      <button onClick={() => router.push(`/teas/${next.id}`)}>Next tea</button>20    </>21  );22}

$ next build▲ Next.js 16.4.3 (Turbopack)   Running TypeScript ...  Finished TypeScript ...  Creating an optimized production build ...✓ Compiled successfully  Collecting page data ...✓ Generating static pages (4/4)  Finalizing page optimization ... Route (pages)┌ ○ /├   /_app├ ○ /404├ ƒ /api/teas└ ○ /teas/[id] ○  (Static)   prerendered as static contentƒ  (Dynamic)  server-rendered on demand

Each router's hook works in its own files. next/navigation's in a page file stopped at type checking, because the code asked for isReady and query, which it doesn't have. next/router's in an App Router component type-checked, then failed while Next.js rendered the page: NextRouter was not mounted. For a component that both routers render while you move an app over, the docs offer next/compat/router, next to the Pages Router's useRouter reference; moving an app is Migrating to the App Router's topic.

Both routers in one app

A project can have both folders. That's how apps move to the App Router, one page at a time. This version of the shop adds an app folder with a root layout and one page, app/about/page.tsx, and an About link in the shop's layout.

1import Link from "next/link";2 3export default function AboutPage() {4  return (5    <main>6      <h1>About the shop</h1>7      <p>Three teas, packed by hand.</p>8      <Link href="/">Back to the teas</Link>9    </main>10  );11}

$ next build▲ Next.js 16.4.3 (Turbopack)   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...   We detected TypeScript in your project and reconfigured your tsconfig.json file for you.  The following suggested values were added to your tsconfig.json. These values can be changed to fit your project's needs:   	- plugins was updated to add { name: 'next' }   Finished TypeScript ...  Collecting page data ...✓ Generating static pages (6/6)  Finalizing page optimization ... Route (app)┌ ○ /_not-found└ ○ /about Route (pages)┌ ○ /├   /_app├ ƒ /api/teas└ ○ /teas/[id] ○  (Static)   prerendered as static contentƒ  (Dynamic)  server-rendered on demand

Side by side, each router serves its own addresses, and next build prints a table for each: Route (app) and Route (pages). When both folders serve /about, the build stops with App Router and Pages Router both match path: /about. The app folder doesn't win; nothing does until one of the files is gone.

Crossing between them is a full page load. In the side-by-side version, Chrome typed mint into the search box on /, then clicked About:

1import Link from "next/link";2 3export default function AboutPage() {4  return (5    <main>6      <h1>About the shop</h1>7      <p>Three teas, packed by hand.</p>8      <Link href="/">Back to the teas</Link>9    </main>10  );11}

The click made a document request for /about: a whole new page, the way a plain <a> works. The two routers don't share a client-side router, so _app, its layout and the search box's mint are gone; /about has the App Router's root layout instead.

Reading a Pages Router codebase

In an app you've just joined, the first job is telling which router a file belongs to. A few things give it away at once: the folder, the file names, and the imports. Sort these lines and files:

Then find the four places that hold an app's shape: pages/_app.tsx for what wraps every page, pages/_document.tsx for the HTML around it, pages/api for the endpoints, and next.config for the settings.

Common mix-ups

• "The Pages Router is gone in Next.js 16." No. Next.js 16.4.3 builds and runs it; the docs keep a section for it.
• "_document is a layout, like _app." No. It renders on the server only, for the HTML around the app. A layout with state goes in _app.
• "Pages Router pages are Server Components." No. The Pages Router has none: each page's component goes to the browser too, and React hydrates the whole page.
• "router.query has the id in the first HTML." Not for a page with no data function. Its HTML was made during the build, before any id existed; the recorded /teas/mint said Loading….
• "Any useRouter works anywhere." No. next/router's only works under the Pages Router; next/navigation's has no query or isReady.
• "When both folders have a page for one address, app wins." No. The build stops until one is removed.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints.

components/
  layout.tsx
lib/
  teas.ts
pages/
  api/
    teas.ts
  teas/
    [id].tsx
  _app.tsx
  _document.tsx
  index.tsx
styles/
  globals.css

import Head from "next/head";
import { useRouter } from "next/router";
import { teas } from "@/lib/teas";

export default function TeaPage() {
  const router = useRouter();
  if (!router.isReady) return <p>Loading…</p>;
  const index = teas.findIndex((tea) => tea.id === router.query.id);
  if (index === -1) return <p>We don't sell that tea.</p>;
  const tea = teas[index];
  const next = teas[(index + 1) % teas.length];
  return (
    <>
      <Head>
        <title>{`${tea.name} | Tea shop`}</title>
      </Head>
      <h1>{tea.name}</h1>
      <p>${tea.price} a box</p>
      <button onClick={() => router.push(`/teas/${next.id}`)}>Next tea</button>
    </>
  );
}

export default function About() {
  return (
    <>
      <h1>About the shop</h1>
      <p>Three teas, packed by hand.</p>
    </>
  );
}

import type { NextApiRequest, NextApiResponse } from "next";
import { teas, type Tea } from "@/lib/teas";

export default function handler(req: NextApiRequest, res: NextApiResponse<Tea | { error: string }>) {
  const tea = teas.find((item) => item.id === req.query.id);
  if (!tea) return res.status(404).json({ error: "We don't sell that tea." });
  res.status(200).json(tea);
}

"use client";

import { useRouter } from "next/router";

export default function BackButton() {
  const router = useRouter();
  return <button onClick={() => router.back()}>Back</button>;
}

"use client";

import { useRouter } from "next/navigation";

export default function BackButton() {
  const router = useRouter();
  return <button onClick={() => router.back()}>Back</button>;
}

export default function About() {
  return <h1>About the shop</h1>;
}

Check your understanding

For each question, ask which folder the file is in, and where its code runs.

Key takeaways

• In pages, a file's path is its address: index.tsx is its folder's page, and [id].tsx matches any one part.
• _app wraps every page and stays between pages: global CSS and the shared layout go there. _document renders <html> and <body> on the server only.
• Files in pages/api are API routes: one handler(req, res) for every method, the Pages Router's counterpart to the App Router's Route Handlers.
• useRouter from next/router belongs to pages; the App Router's is in next/navigation.
• Both folders can live in one app. A link between them loads the whole page, and one address in both stops the build.
• A page with no data function is made once at build time; its address's parts arrive in the browser.

Coming next: Data fetching in the Pages Router. getStaticProps, getStaticPaths and getServerSideProps put the tea into the HTML, and each maps to something in the App Router.