P-17 — Migrating from Pages Router to App Router

App Router:

// app/blog/[slug]/page.tsx
import { notFound } from 'next/navigation';
 
export async function generateStaticParams() {
  const posts = await getAllPostSlugs();
  return posts.map((slug) => ({ slug }));
}
 
export const revalidate = 3600; // ISR interval, replaces `revalidate` from getStaticProps
 
export default async function BlogPost({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await getPostBySlug(slug);
 
  if (!post) notFound();
 
  return <Article post={post} />;
}

Notes on the mapping:

• generateStaticParams returns an array of plain objects matching the dynamic segment names — no { params: {...} } wrapper, unlike getStaticPaths.
• There's no direct per-page equivalent of fallback: 'blocking' | true | false. By default, paths not returned by generateStaticParams are still rendered on demand at request time and cached going forward — closest to fallback: 'blocking'. To render only the paths you enumerated and 404 everything else, set export const dynamicParams = false in the same file.
• revalidate moves from a per-request return value to a route-segment config export (export const revalidate = <seconds>), or you can pass a { next: { revalidate } } option directly to a fetch() call for per-request granularity.

---

API Routes → Route Handlers

pages/api/*.ts files exported a single default function and switched on req.method. app/*/route.ts files export one named function per HTTP method instead.

Pages Router:

// pages/api/users/[id].ts
import type { NextApiRequest, NextApiResponse } from 'next';
 
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const { id } = req.query;
 
  if (req.method === 'GET') {
    const user = await getUser(id as string);
    if (!user) return res.status(404).json({ error: 'Not found' });
    return res.status(200).json(user);
  }
 
  if (req.method === 'PATCH') {
    const updated = await updateUser(id as string, req.body);
    return res.status(200).json(updated);
  }
 
  res.setHeader('Allow', ['GET', 'PATCH']);
  return res.status(405).end(`Method ${req.method} Not Allowed`);
}

App Router:

// app/api/users/[id]/route.ts
import { NextRequest, NextResponse } from 'next/server';
 
export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const user = await getUser(id);
 
  if (!user) {
    return NextResponse.json({ error: 'Not found' }, { status: 404 });
  }
  return NextResponse.json(user);
}
 
export async function PATCH(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const body = await request.json();
  const updated = await updateUser(id, body);
  return NextResponse.json(updated);
}

There is no manual 405 handling to write — Route Handlers automatically respond 405 Method Not Allowed for any HTTP method you didn't export. The file location convention also changes: it's route.ts (or .js), not an arbitrarily-named file, and it lives alongside page.tsx files under the matching path segment — app/api/users/[id]/route.ts responds at /api/users/:id, exactly like the old pages/api/users/[id].ts did.

req.query and req.body don't exist on the App Router's NextRequest. Query params come from request.nextUrl.searchParams; the body comes from await request.json() (or .formData(), .text(), depending on content type).

---

next/router → next/navigation

This is the change that breaks the most code silently, because both modules export a hook called useRouter() — but they are not compatible, and TypeScript won't always catch the difference at the call site if you're accessing a property that happens to exist on neither type's autocomplete you're looking at.

Pages Router (next/router): one hook does everything.

import { useRouter } from 'next/router';
 
function ProductPage() {
  const router = useRouter();
 
  const pathname = router.pathname;         // '/products/[id]'
  const { id, sort } = router.query;         // dynamic params AND query string, merged
  const asPath = router.asPath;              // actual URL, e.g. '/products/42?sort=price'
 
  const goToCart = () => router.push('/cart');
 
  useEffect(() => {
    const handleRouteChange = (url: string) => console.log('navigating to', url);
    router.events.on('routeChangeStart', handleRouteChange);
    return () => router.events.off('routeChangeStart', handleRouteChange);
  }, [router]);
 
  return <button onClick={goToCart}>Checkout</button>;
}

App Router (next/navigation): the same responsibilities are split across four hooks, and none of them merge params and query string together.

'use client';
 
import { useRouter, usePathname, useSearchParams, useParams } from 'next/navigation';
 
function ProductPage() {
  const router = useRouter();
  const pathname = usePathname();           // '/products/42' — the real path, no query string
  const searchParams = useSearchParams();   // URLSearchParams — read with .get('sort')
  const params = useParams();               // { id: '42' } — dynamic segment values only
 
  const sort = searchParams.get('sort');
 
  const goToCart = () => router.push('/cart');
 
  return <button onClick={goToCart}>Checkout</button>;
}

Key differences to actually internalize, not just skim:

The missing router.events is the one that catches teams off guard, because it's usually load-bearing for things like page-view analytics or top-loading-bar progress indicators. There's no direct replacement hook. The two common substitutes: track navigation via a usePathname()/useSearchParams() combo in a Client Component wrapped around your children (comparing values across renders with useEffect), or move page-view tracking into <Link> onClick handlers and initial-load tracking into the root layout. Neither is a drop-in equivalent — treat this as an actual rewrite of that piece of code, not a search-and-replace.

Also note that useSearchParams() opts the component subtree into client-side rendering up to the nearest Suspense boundary — if you read search params in a Client Component that's supposed to be statically rendered, wrap it in <Suspense> or the build will warn (and in some cases de-optimize the whole route to dynamic rendering).

---

_app.tsx / _document.tsx → RootLayout

_app.tsx wrapped every page and was where global CSS, context providers, and persistent layout lived. _document.tsx controlled the raw <html>/<body> shell and only ran on the server. app/layout.tsx merges both responsibilities into a single Server Component.

Pages Router:

// pages/_app.tsx
import type { AppProps } from 'next/app';
import { ThemeProvider } from '@/components/theme-provider';
import '@/styles/globals.css';
 
export default function App({ Component, pageProps }: AppProps) {
  return (
    <ThemeProvider>
      <Component {...pageProps} />
    </ThemeProvider>
  );
}

// pages/_document.tsx
import { Html, Head, Main, NextScript } from 'next/document';
 
export default function Document() {
  return (
    <Html lang="en">
      <Head>
        <link rel="icon" href="/favicon.ico" />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

App Router:

// app/layout.tsx
import type { Metadata } from 'next';
import { ThemeProvider } from '@/components/theme-provider';
import '@/styles/globals.css';
 
export const metadata: Metadata = {
  icons: { icon: '/favicon.ico' },
};
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

A few things worth being precise about:

• RootLayout is a Server Component by default. If your provider (theme context, a client-side query cache, etc.) needs useState, useEffect, or React Context that consumers read via a hook, the provider component itself needs 'use client' at its own definition — but you still import and render it from the Server Component RootLayout directly. Providers "sandwich" fine: a Server Component parent rendering a Client Component provider around Server Component children is the standard, supported pattern.
• Global CSS can only be imported from the root layout (or another top-level layout/page under app/), not from arbitrary components — same restriction that existed for _app.tsx, just enforced at a different file.
• There's no pageProps concept. Each page.tsx fetches its own data; nothing is threaded through from a parent "app" wrapper.
• metadata (or generateMetadata for dynamic values) replaces manually writing <head> tags in _document.tsx or using next/head — see the next section for why next/head specifically stops working.

---

Middleware During Partial Migration

This is the good news in this module: Middleware requires zero changes during migration. middleware.ts operates on the incoming Request before Next.js decides whether the matched route lives under app/ or pages/ — it is router-agnostic by design. A matcher like /dashboard/:path* fires identically whether /dashboard is currently served by pages/dashboard.tsx or app/dashboard/page.tsx.

Practically, this means auth checks, redirects, and header-forwarding logic you've already written in Middleware keep working untouched as you migrate the routes behind them. The one thing to double check is that your matcher's route list stays in sync with reality as paths move — if a migrated route changes its URL segment structure (rare, but possible during a directory reorganization), update the matcher accordingly. The Middleware logic itself never needs to know which router served the page.

---

The Pitfalls That Actually Block Migrations

These are the specific, recurring issues that stall a Pages-to-App migration mid-way, roughly in the order teams hit them.

1. next/head silently does nothing in the App Router. If you migrate a page and leave a <Head> component from next/head inside it, it won't throw — it just won't render anything into the document head. Replace it with the metadata object export or generateMetadata() async function.

2. Client-only libraries need an explicit 'use client' boundary, and it has to be at the right level. Any component using useState, useEffect, browser-only APIs (window, localStorage), or a library that assumes a DOM (many chart and rich-text-editor libraries) needs 'use client' at the top of the file. The common mistake isn't forgetting the directive — it's putting it on the entire page.tsx, which forces the whole tree client-side, when the fix should be isolating just the interactive leaf component and keeping the page itself a Server Component.

3. Reading cookies/session state moves from a request object to an async function call. req.cookies (GSSP) or req.cookies (API routes) becomes await cookies() from next/headers — and it can only be called from Server Components, Route Handlers, and Server Actions, not from Client Components. If your auth helper reads cookies and is imported into a Client Component, that import will fail; the helper needs a server-only and client-side path, or needs to be called higher up and passed down as data.

4. _error.tsx doesn't map cleanly onto one file — it maps onto two. pages/_error.tsx handled both rendering errors and custom status-code pages (like a custom 500). The App Router splits this: error.tsx (a Client Component boundary, catches errors in its segment and below, does not catch errors in the layout that renders it) and global-error.tsx (catches errors in the root layout itself, and must render its own <html>/<body> since it replaces the root layout when triggered). A single _error.tsx handler doesn't have a single-file replacement.

5. Custom 404s move from a page file to a function call. pages/404.tsx becomes app/not-found.tsx, but you also need to actually trigger it — call notFound() from next/navigation inside the Server Component, rather than the Pages Router's return { notFound: true }.

6. Catch-all route syntax is unchanged, but the file location convention isn't. [...slug].tsx and [[...slug]].tsx (optional catch-all) work exactly the same way inside app/ — same bracket syntax — but the file must be named page.tsx inside a folder named for the segment: pages/blog/[...slug].tsx becomes app/blog/[...slug]/page.tsx, not app/blog/[...slug].tsx.

7. The <Image> component's required props changed subtly. The App Router's next/image still needs width/height or fill, but if you're migrating a page that relied on Pages Router defaults around lazy loading or the deprecated layout/objectFit props from older next/image versions, those props were already removed well before Next.js 13 — if your Pages Router code predates that removal, you're fixing two migrations at once (old Image API → new Image API, then Pages → App), and it's worth doing the Image API cleanup as a separate, earlier pass so it doesn't get conflated with App Router bugs.

8. getInitialProps, if anything still uses it, has no App Router equivalent at all. Unlike GSSP/GSSP-static, getInitialProps (usually left over in a custom _app.tsx or _error.tsx for older codebases) predates the split between static and server rendering and doesn't map onto a single App Router primitive. Code still relying on it needs to be re-architected onto explicit Server Component data fetching, not mechanically translated.

9. Layout state doesn't automatically persist across navigations the way _app.tsx state did. In the Pages Router, <Component {...pageProps} /> re-rendered inside a _app.tsx that itself didn't remount, so state held in _app.tsx (a shopping cart count, a sidebar's open/closed state) survived page navigation for free. In the App Router, a Client Component holding that state needs to live in a layout.tsx that's shared across the routes where the state should persist — moving it into an individual page.tsx will reset it on every navigation, because page.tsx remounts on route change while a shared layout.tsx does not.

10. Two build outputs, two mental models, until the migration is actually done. It's tempting to consider the migration "mostly done" once most traffic goes through app/, but every remaining pages/ file still needs _app.tsx/_document.tsx maintained, still uses the old data-fetching functions, and still needs its own testing pass. Teams that stall here tend to do so because the last 10% of routes are the highest-traffic, most stateful ones (exactly the routes the migration order above tells you to save for last) — budget for that tail explicitly rather than assuming it'll go as fast as the leaf pages did.

---

Next: AI Integration and Streaming Route Handlers →

---