Pages Router to App Router — Mixed Router Caused API Routes to Return 404 for 3 Days

Migrating from the Pages Router to the App Router is the most common large-scale Next.js migration project. It's not a simple upgrade — the two routing systems have fundamentally different mental models. The Pages Router treats every file as a page component with explicit data-fetching functions. The App Router treats every file as a server-rendered component with async data fetching.

Both routers can coexist in the same Next.js project. This is intentional — Vercel designed the App Router to support incremental adoption. You can add an app/ directory alongside your existing pages/ directory and both work together, routing traffic based on the filesystem hierarchy. The critical rule: routes cannot overlap. If pages/api/user.js exists, you cannot have app/api/user/route.js — one will silently return 404.

In a recent production incident, a team running a mixed router deployment discovered that all API routes were returning 404. The cause: they had added an app/api/ directory for a new endpoint, but an existing pages/api/ directory had the same route structure. The App Router took precedence for the overlapping paths — and returned 404 because the App Router route handler returned the wrong response format.

This article covers the complete migration strategy: coexistence rules, incremental adoption patterns, data fetching migration (getServerSideProps/getStaticProps to Server Component fetch), layout nesting differences, route groups, parallel routes, and the production incident that happens when you get the route structure wrong.

Coexistence Rules — Both Routers Can Live Together, BUT

Next.js supports running both the Pages Router and the App Router in the same project. When you add an app/ directory alongside pages/, both are active. Next.js checks the app/ directory first for a matching route. If found, the App Router handles it. If not found, Next.js falls back to the Pages Router.

The critical rule: a route can be handled by ONLY ONE router. If /blog/hello exists in both pages/blog/[slug].js and app/blog/[slug]/page.tsx, the App Router version takes precedence — the Pages Router version is completely ignored, even if the App Router version throws an error or returns 404.

This means: during migration, every route must exist in exactly ONE router. You cannot have the same route partially migrated. The approach is to migrate routes one at a time: remove the pages/ version AND add the app/ version in the same deploy. For the duration of the migration, both routers handle different sets of routes.

The API route conflict (the production incident described above) is the most dangerous version of this rule. Because API routes don't have a visual presence, a 404 from a missing HTTP method export can go unnoticed for days. The fix: migrate all API routes in a single batch, not incrementally.

# Check for overlapping routes between pages/ and app/
# Run BEFORE any migration deploy to detect conflicts

# List all routes from both directories
find app pages -type f \( -name 'page.tsx' -o -name 'route.ts' -o -name '*.js' \) \
  | sed 's|^./||' \
  | sed 's|/page\.tsx$||' \
  | sed 's|/route\.ts$||' \
  | sed 's|\.js$||' \
  | sed 's|/index$||' \
  | sort \
  | uniq -d

# If this outputs any paths, you have overlapping routes.
# The App Router version will take precedence.
# Example output:
# ```
# api/users
# blog/[slug]
# ```
# Means both app/api/users/route.ts (or page.tsx)
# AND pages/api/users.js exist — a conflict.

Incremental Migration Strategy — Pages One at a Time

The correct migration strategy is NOT to rewrite the entire app. It's to migrate one route at a time, maintaining both routers in parallel until every route is migrated. The strategy has four phases.

Phase 1 — Foundation: Create the app/ directory with a root layout.tsx. This layout must include global CSS imports, fonts, and context providers that were previously in _app.tsx and _document.tsx. Without this step, migrated pages will render without styles or providers.

Phase 2 — API Routes: Migrate all API routes from pages/api/ to app/api/ in a single batch. Since API routes have no UI and no layout nesting, they are the easiest to migrate and the most dangerous to leave mixed. Export all HTTP methods as named exports.

Phase 3 — Leaf Pages: Migrate the most deeply nested pages first (e.g., /blog/[slug] before /blog). Leaf pages depend on layouts, not the other way around. Migrating leaves first means you can test each page independently. Each leaf page becomes a Server Component with direct async fetch instead of getServerSideProps.

Phase 4 — Layouts: Migrate layouts last. The App Router's nested layout system is a significant architectural change. Migrate from bottom to top: migrate the innermost layout first, then the parent layout, then the root layout. Each layout migration should be a separate PR.

// Phase 1: Root Layout
// app/layout.tsx — must mirror _app.tsx + _document.tsx
// Without this, migrated pages have no styles

// Phase 2: API Routes (ALL at once)
// pages/api/users.js  →  app/api/users/route.ts
// pages/api/posts.js  →  app/api/posts/route.ts

// Phase 3: Leaf Pages (one at a time)
// pages/blog/[slug].js  →  app/blog/[slug]/page.tsx
// Steps:
//   1. Create app/blog/[slug]/page.tsx
//   2. Convert getStaticProps → fetch with revalidate
//   3. Convert getStaticPaths → generateStaticParams
//   4. Remove pages/blog/[slug].js

// Phase 4: Layouts (bottom-up)
// pages/blog.js (layout for /blog/*)  →  app/blog/layout.tsx
// pages/_app.tsx (global layout)      →  app/layout.tsx (already done in Phase 1)

// NEVER do in one PR:
// - Migrate more than 1-2 leaf pages
// - Leave overlapping routes
// - Skip Phase 1 (root layout without styles)

Data Fetching Migration — getServerSideProps to Server Component Fetch

The most dramatic change between routers is data fetching. In the Pages Router, data fetching is decoupled from the component via getServerSideProps (SSR) and getStaticProps (SSG/ISR). In the App Router, data fetching happens directly inside Server Components using async/await with fetch().

Migration mapping: getServerSideProps → fetch(url, { cache: 'no-store' }). The no-store cache option tells Next.js not to cache the response — equivalent to SSR. getStaticProps → fetch(url, { next: { revalidate: N } }). The revalidate option enables ISR with N-second background regeneration. getStaticProps without revalidate → fetch(url). Default fetch is static (no caching directives) — equivalent to SSG.

The critical difference: in the Pages Router, getStaticProps returned { props: { ... } } and the component received those props. In the App Router, you call fetch directly in the component body — there are no props. This means error handling, loading states, and null checks must happen inside the component, not in a separate data fetching function.

For pages that need getStaticPaths (dynamic routes with pre-built paths), the App Router equivalent is generateStaticParams. It returns an array of param objects directly (no { paths, fallback } wrapper). The fallback behaviour is replaced by dynamicParams: true (equivalent to fallback: true) or false (equivalent to fallback: false) exported from the page.

// ===== PAGES ROUTER (BEFORE) =====

import type { GetServerSideProps, GetStaticProps } from 'next'

// SSR — fresh data on every request
export const getServerSideProps: GetServerSideProps = async () => {
  const res = await fetch('https://api.example.com/posts')
  const posts = await res.json()
  return { props: { posts } }
}

export default function Page({ posts }: { posts: any[] }) {
  return <div>{posts.map(post => <PostCard key={post.id} post={post} />)}</div>
}

// ===== APP ROUTER (AFTER) =====

// SSR — fresh data on every request
// Default export is async — fetch directly in component
export default async function Page() {
  const res = await fetch('https://api.example.com/posts', {
    cache: 'no-store', // Equivalent to getServerSideProps
  })
  const posts = await res.json()

  return (
    <div>
      {posts.map(post => (
        <PostCard key={post.id} post={post} />
      ))}
    </div>
  )
}

// ===== ISR MIGRATION =====

// Pages Router: getStaticProps with revalidate
export const getStaticProps: GetStaticProps = async () => {
  const res = await fetch('https://api.example.com/posts')
  const posts = await res.json()
  return { props: { posts }, revalidate: 3600 }
}

// App Router: fetch with next.revalidate
export default async function Page() {
  const res = await fetch('https://api.example.com/posts', {
    next: { revalidate: 3600 }, // Equivalent to ISR
  })
  const posts = await res.json()
  return <div>{posts.map(post => <PostCard key={post.id} post={post} />)}</div>
}

Layout Nesting — The Architectural Game Changer

The Pages Router has a flat layout system: _app.tsx (wraps every page), _document.tsx (controls HTML document structure). Every page shares the same layout hierarchy. If you need different layouts for different sections, you must build a custom layout system with conditional rendering.

The App Router introduces nested layouts: every directory can have a layout.tsx that wraps all pages in that directory and its subdirectories. This is the most architecturally significant difference between the two routers.

Example: /blog/[slug]/page.tsx is wrapped by app/blog/[slug]/layout.tsx (if it exists), which is wrapped by app/blog/layout.tsx, which is wrapped by app/layout.tsx. Each layout persists across navigations within its segment — the sidebar in /blog/layout.tsx remains mounted when navigating between blog posts.

The migration challenge: your existing _app.tsx likely contains providers (Theme, Auth, QueryClient, Toaster) and global styles. These must be moved to app/layout.tsx. If you have section-specific layouts built with custom code in the Pages Router, those become nested layout files in the App Router.

The production insight: App Router layouts are Server Components by default. If your layout needs interactivity (a sidebar with user state, a navigation with client-side routing), you need to add 'use client' to the layout or extract interactive parts into client subcomponents. However, making a layout a client component means ALL its children (every page in that segment) are also client-rendered — defeating the Server Component benefit.

// ===== PAGES ROUTER LAYOUTS =====
// pages/_app.tsx — wraps ALL pages globally

import type { AppProps } from 'next/app'
import { ThemeProvider } from '@/providers/theme'
import { AuthProvider } from '@/providers/auth'
import '@/styles/globals.css'

export default function App({ Component, pageProps }: AppProps) {
  return (
    <ThemeProvider>
      <AuthProvider>
        <Component {...pageProps} />
      </AuthProvider>
    </ThemeProvider>
  )
}

// ===== APP ROUTER LAYOUTS =====
// app/layout.tsx — root layout, wraps ALL app/ pages

import { ThemeProvider } from '@/providers/theme'
import { AuthProvider } from '@/providers/auth'
import '@/styles/globals.css'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <ThemeProvider>
          <AuthProvider>
            {children}
          </AuthProvider>
        </ThemeProvider>
      </body>
    </html>
  )
}

// app/blog/layout.tsx — wraps only /blog/* pages
// This sidebar persists across blog post navigations

import { Sidebar } from '@/components/sidebar'

export default function BlogLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <div className="flex">
      <Sidebar />    {/* Stays mounted between posts */}
      <main>{children}</main>
    </div>
  )
}

Route Groups and Parallel Routes — New Patterns, No Pages Router Equivalent

The App Router introduces two routing patterns that have no Pages Router equivalent: Route Groups and Parallel Routes.

Route Groups: directories named in parentheses (group) that do NOT affect the URL path. Use them to organise routes without changing the URL structure. For example: app/(marketing)/about/page.tsx renders at /about, not /(marketing)/about. The (marketing) group is purely organisational — it can have its own layout that applies only to marketing pages.

Parallel Routes: directories named with @ prefix that render multiple independent segments on the same page. For example, a dashboard with a main content area and a sidebar — each can be a separate file that renders independently. Parallel routes enable complex layouts like modals that appear alongside the underlying page, where the modal content is a separate route segment.

Migration strategy: you do not need to use these patterns during migration. They are additive — adopt them for new features built in the App Router. Do not try to replicate them in the Pages Router. When migrating existing pages, keep the same URL structure — use Route Groups only if you need different layouts for different sections at the same URL level.

// ===== ROUTE GROUPS =====
// Directory structure (URLs in comments):

// app/
//   (marketing)/          ← No URL segment! Just for layout organisation
//     layout.tsx           ← Layout for all marketing pages
//     page.tsx             ← /
//     about/page.tsx       ← /about
//     pricing/page.tsx     ← /pricing
//   (dashboard)/           ← No URL segment
//     layout.tsx           ← Different layout for dashboard pages
//     page.tsx             ← /dashboard
//     settings/page.tsx    ← /dashboard/settings

// ===== PARALLEL ROUTES =====
// app/dashboard/
//   layout.tsx             ← Contains both @sidebar and @main slots
//   @sidebar/
//     page.tsx              ← Renders in the 'sidebar' slot
//   @main/
//     page.tsx              ← Renders in the 'main' slot

// app/dashboard/layout.tsx
// export default function DashboardLayout({
//   sidebar,  ← Content from @sidebar
//   main,     ← Content from @main
// }: {
//   sidebar: React.ReactNode
//   main: React.ReactNode
// }) {
//   return (
//     <div className="flex">
//       <aside>{sidebar}</aside>
//       <main>{main}</main>
//     </div>
//   )
// }

Error and Loading States — From Custom Handlers to Conventions

The Pages Router handles loading and error states manually: a isLoading state in the component, try/catch in getServerSideProps with error props, and _error.js for global errors. The App Router introduces file-convention-based error and loading boundaries.

loading.tsx: place a loading component in any directory. Next.js automatically wraps the page content in a Suspense boundary and shows the loading component while the page's async data is being fetched. No manual loading state management needed.

error.tsx: place an error component in any directory. Next.js automatically wraps the content in an ErrorBoundary. The error component receives error and reset props — reset allows the user to retry the failed render. Error boundaries are per-directory — an error in app/blog/[slug]/page.tsx shows the error component from app/blog/[slug]/error.tsx, not the root error.

not-found.tsx: shown when notFound() is called from a Server Component or when the URL does not match any route. Replaces the custom 404 page in the Pages Router.

Migration: move your loading spinner JSX to loading.tsx in the appropriate directory. Move your error UI to error.tsx. Move your custom 404 page to not-found.tsx. The convention-based approach eliminates the boilerplate of managing loading/error state in every component.

// ===== loading.tsx — Auto-wrapped in Suspense =====
// app/blog/loading.tsx — shown when any /blog/* page is loading

export default function BlogLoading() {
  return (
    <div className="space-y-4 animate-pulse">
      {Array.from({ length: 6 }).map((_, i) => (
        <div key={i} className="h-24 bg-gray-200 rounded-lg" />
      ))}
    </div>
  )
}

// ===== error.tsx — Per-segment error boundary =====
// app/blog/[slug]/error.tsx — only for individual blog post errors
'use client' // Error boundaries must be Client Components

export default function PostError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <div className="text-center py-12">
      <h2>Failed to load post</h2>
      <p className="text-gray-500">{error.message}</p>
      <button onClick={reset}>Try again</button>
    </div>
  )
}

// ===== not-found.tsx — 404 page =====
// app/not-found.tsx — shown when notFound() is called

export default function NotFound() {
  return (
    <div className="text-center py-20">
      <h1 className="text-4xl font-bold">404</h1>
      <p className="text-gray-500">Page not found</p>
    </div>
  )
}

Middleware Migration — Same Concept, New Location

Middleware in the Pages Router lives at pages/_middleware.js (older versions) or middleware.ts at the project root (Next.js 12+). In the App Router, middleware still lives at the project root — the location is the same. The API and behaviour are also similar, with minor differences.

Both routers share the same middleware file: middleware.ts at the project root. The middleware runs on every request, before the router determines whether the Pages Router or App Router handles it. Middleware cannot know which router will handle the request — it operates at the URL level.

The migration concern: if your middleware modifies the URL (rewrites, redirects, adding headers), it affects both routers equally — there is no 'Pages Router middleware' vs 'App Router middleware'. If your middleware references Pages Router-specific patterns (like checking for __nextLocale query params), those may behave differently when the App Router handles the request.

// middleware.ts — SAME FILE for both routers
// Located at project root, NOT inside pages/ or app/

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl

  // Example: redirect old blog URLs (affects both routers)
  if (pathname.startsWith('/old-blog')) {
    const slug = pathname.replace('/old-blog/', '')
    return NextResponse.redirect(
      new URL(`/blog/${slug}`, request.url)
    )
  }

  // Example: add security headers (affects both routers)
  const response = NextResponse.next()
  response.headers.set('X-Robots-Tag', 'index, follow')

  return response
}

// Matcher config — applies to both routers
export const config = {
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico).*)',
  ],
}

Testing the Mixed Router State — CI Must Check Both

During migration, your CI must test both the Pages Router routes and the App Router routes independently. A test that passes on a Pages Router route does not guarantee the App Router equivalent will work — different data fetching, different error handling, different rendering behaviour.

The testing strategy during migration: (1) Unit tests for data fetching — test that fetch with cache: 'no-store' returns the same data as getServerSideProps. (2) Integration tests for routes — for every migrated route, assert the App Router version returns the same HTTP status, content, and headers as the Pages Router version. (3) Route conflict checks — a script that detects overlapping routes (described in the first section) must pass before every deploy. (4) Full build — next build must succeed. A successful build guarantees no route conflicts (they cause build errors).

The end state: when all routes are migrated, remove the pages/ directory entirely. Verify that the App Router handles all routes by running the same test suite against the migrated app. Only then can you delete _app.tsx, _document.tsx, and any Pages Router-specific code.

// Integration test: verify both routers serve the same content
// Run during migration period to catch regressions

async function fetchFromRouter(path: string) {
  const res = await fetch(`http://localhost:3000${path}`)
  return {
    status: res.status,
    body: await res.text(),
    headers: Object.fromEntries(res.headers.entries()),
  }
}

describe('Migration parity', () => {
  const routes = [
    '/',
    '/blog',
    '/blog/first-post',
    '/about',
    '/api/users',
    '/api/posts',
  ]

  for (const route of routes) {
    it(`${route} returns 200`, async () => {
      const { status } = await fetchFromRouter(route)
      expect(status).toBe(200)
    })

    it(`${route} contains expected content`, async () => {
      const { body } = await fetchFromRouter(route)
      // Assert content exists (not empty 404 page)
      expect(body.length).toBeGreaterThan(100)
    })
  }

  // Special test for API routes — check all methods
  it('API routes handle POST', async () => {
    const res = await fetch('http://localhost:3000/api/users', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ name: 'test' }),
    })
    expect(res.status).not.toBe(404)
    // 4xx is acceptable (validation error) — 404 is not
  })
})

The Final State — Cleaning Up After Migration

When every route has been migrated to the App Router, the final step is cleanup. The pages/ directory can be deleted. Remove Pages Router-specific dependencies (getInitialProps, getServerSideProps, getStaticProps wrappers, next/router, _app.tsx, _document.tsx).

The confirmation step: run next build after removing pages/. A successful build with no 'Route' entries from the old pages directory confirms the migration is complete. The next build output should show all routes under ○ (Static) or λ (Dynamic) with app/ prefix — no pages/-prefixed routes.

Common leftover issues: (1) Imports from next/router in migrated components — useRouter must be replaced with useSelectedLayoutSegment or usePathname from next/navigation. (2) _app.tsx providers not moved to root layout — if migrated pages lack styling or context. (3) Pages Router API route patterns (req.query, res.status) still used in migrated route handlers — the App Router uses Web Request/Response objects.

Final verification: all routes return 200, all API endpoints handle all methods, all layouts render correctly, and styles are consistent.

# Step 1: Verify no routes remain in pages/
# Run this after removing pages/ directory
next build 2>&1 | grep -E 'Route|pages/' | head -20
# If this shows 'pages/' anywhere, you missed some routes

# Step 2: Check for Pages Router imports in the App Router
# These imports indicate incomplete migration

grep -rn "from 'next/router'\|"from 'next/router'" app/ --include='*.{tsx,ts}' || echo "✅ No next/router imports"
grep -rn "getServerSideProps\|getStaticProps" app/ --include='*.{tsx,ts}' || echo "✅ No getServerSideProps/getStaticProps"
grep -rn "useRouter\|withRouter" app/ --include='*.{tsx,ts}' || echo "✅ No useRouter"

# Step 3: Check for Pages Router API patterns in app/api/
grep -rn "req\.query\|res\.status\|res\.json" app/api/ --include='*.{ts,tsx}' || echo "✅ No Pages Router API patterns"

# Step 4: Final verification
# Run the full test suite and check all routes return 200
npm run build && npm run test