Next.js App Router Migration: 47 Things That Break When You Migrate

Product search started returning 404s after migrating. Turns out next/router doesn't exist anymore. Vercel deleted the entire fucking package in Next.js 13.4.0. Not deprecated - gone.

// This worked fine yesterday
import { useRouter } from 'next/router'

const router = useRouter()
const { productId, category } = router.query // RIP

Now you need three different imports to do what one hook used to do:

'use client'
import { useRouter, useSearchParams, useParams } from 'next/navigation'

// useRouter() only pushes routes now
// useSearchParams() for ?category=shoes
// useParams() for /products/[id]

The router.isReady property? Gone. No replacement. Delete every router.isReady check because it doesn't exist anymore.

Middleware Stops Working (Zero Error Messages)

Spent 4 hours debugging why auth stopped working. No error messages. No console logs. Middleware just... stopped running.

Turns out you can't put middleware inside app/ anymore. Has to be in project root:

project/
├── app/
├── middleware.ts  ← Only works here, nowhere else
└── package.json

In Pages Router, middleware ran on everything by default. App Router middleware needs explicit path matching or it won't run at all:

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

This broke our auth routes silently. Users could access protected pages without logging in. Production was fucked for 2 hours before I realized middleware wasn't running at all. Zero logs. Zero errors. Just silently failing.

Error Pages Are Now Error... Hierarchies?

Your simple 404.js file doesn't work anymore. App Router uses multiple error files:

• error.tsx for component crashes
• not-found.tsx for 404s
• global-error.tsx for root layout errors

Server component errors happen during rendering and show generic production error pages. Error boundaries only catch client component errors. Learned this when our dashboard crashed and users saw "Application error: a client-side exception has occurred" instead of our custom error page.

Auth Libraries Had to Start Over

NextAuth.js v4 doesn't work with App Router. At all. v5 rewrote the entire API. Every authentication pattern we had needed rewriting.

Session handling split into multiple APIs. Server components use auth(), client components use useSession(), middleware gets sessions differently. Nothing from v4 works anymore.

Clerk, Auth0, and Supabase all have separate App Router guides now because their old patterns broke too.

Development Lies to You

Everything works in next dev, then production breaks. Development and production behave completely differently in App Router.

Our dashboard worked fine locally, then 404'd in production. Took 2 hours to realize it was trying to fetch from localhost:3000 during the build process. Dynamic routes get statically generated at build time unless you tell them not to.

Always run npm run build && npm start before deploying. The development server uses different rendering strategies than production. I learned this the hard way when our client's site went down on launch day. Took 3 hours to roll back and another 4 hours to figure out what the hell happened.

Here's what actually matters if you don't want to spend your entire weekend debugging this bullshit like I did.

Get the Router Imports Right

Don't try to fix all your router imports at once. Pick one component that breaks and learn the pattern. Took me 3 attempts to understand what replaces what:

// Your old code everywhere
const router = useRouter()
const { productId } = router.query
const category = router.query.category

The replacement isn't obvious:

'use client'
import { useSearchParams, useParams } from 'next/navigation'

const searchParams = useSearchParams()
const params = useParams()

const category = searchParams.get('category')    // For ?category=shoes
const productId = params.productId               // For /products/[productId]

Copy this pattern to every fucking component using router imports. There's no automated migration tool - each import needs manual replacement. I had to fix 47 components by hand over two days. My wrist still hurts.

The router.isReady check everywhere? Delete it. App Router doesn't need it and it doesn't exist anymore.

Fix Your Middleware Before You Deploy

Middleware breaks silently when moved from Pages Router. The file must be in your project root, not inside app/:

your-project/
├── app/
├── middleware.ts  ← Here, not anywhere else
└── package.json

Add this matcher config or middleware runs on every static file and absolutely fucks up your build:

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

Test auth routes after moving the file. I deployed without testing and our entire auth system stopped working. Took 30 minutes to figure out why.

Dynamic Routes Need Folders Now

Dynamic routing changed from files to folders. Your pages/products/[id].js file becomes a nested folder structure:

app/
└── products/
    └── [id]/
        └── page.tsx

Every dynamic route needs its own folder with a page.tsx inside. Nested dynamic routes become nested folders. Parameters come through props instead of router.query:

export default function ProductPage({ params }: { params: { id: string } }) {
  return <div>Product {params.id}</div>
}

Actually Test Production Builds

Development and production behave differently in App Router. Always run this before deploying:

npm run build && npm start

If npm run build fails, production deployment fails. If routes work after npm start but fail after deploying, your hosting platform doesn't support some App Router feature.

Static generation can break routes that work in development. I pushed to production without testing locally and spent 3 hours debugging why routes that worked fine in dev were 404ing in prod. Client was not happy. Neither was I.

App Router development doesn't catch production issues. Development and production use completely different rendering strategies, so shit breaks after you deploy. Every fucking time.

Static Generation Fails in Stupid Ways

Pages work in development but fail during npm run build with fetch errors. App Router pre-renders everything at build time when possible.

API routes don't exist during the build process. This breaks routes that fetch from internal APIs:

// This works in dev, breaks in production build
export default async function HomePage() {
  const posts = await fetch('http://localhost:3000/api/posts')  // Build fails here
  return <div>Posts</div>
}

Call your database directly or force dynamic rendering:

export const dynamic = 'force-dynamic'  // Skip static generation

export default async function HomePage() {
  const posts = await fetch('http://localhost:3000/api/posts')  // Now it works
  return <div>Posts</div>
}

Spent 2 hours figuring out why our homepage wouldn't build. The fetch worked perfectly in development. Build process kept failing with "ECONNREFUSED" errors that made zero sense.

Error Pages Don't Work Like You Think

App Router error boundaries work differently than expected. Server component crashes show generic error pages in production, even with proper error.tsx files.

Client component errors trigger error boundaries. Server component errors don't trigger error.tsx files and show minimal information.

Create an error.tsx file in each route folder:

// app/dashboard/error.tsx
'use client'

export default function Error({ error, reset }: { error: Error, reset: () => void }) {
  console.error('Dashboard broke:', error)
  return (
    <div>
      <h2>Dashboard Error</h2>
      <button onClick={reset}>Try Again</button>
    </div>
  )
}

Test error boundaries by throwing test errors. Don't assume they work. Our error pages looked great in development, then showed "Application error: a client-side exception has occurred" in production.

The Build Process Lies

npm run build succeeds even with broken routes. It only fails for build-time errors, not runtime routing problems.

Always test the production server locally:

npm run build && npm start

If routes work after npm start but fail on Vercel/Netlify, your hosting platform doesn't support some App Router feature. Took me 4 deployments to figure this out.

Memory Usage Doubles

App Router uses more memory during builds than Pages Router. Build processes can run out of memory on smaller servers.

If build processes get killed without errors, increase memory allocation:

NODE_OPTIONS="--max-old-space-size=4096" npm run build

Our builds kept failing on the CI server with no error message. Build would just die. Took 3 tries to realize it was running out of memory. GitHub Actions default runners apparently can't handle App Router builds.

Caching Breaks in Production

Routes get cached aggressively in production while showing fresh data in development. Add dynamic rendering config to routes that need current data:

export const revalidate = 0  // Don't cache this route
export const dynamic = 'force-dynamic'  // Render at request time

Without these configs, production apps serve stale data from the cache for extended periods. Our admin dashboard showed data from 3 days ago in production while displaying live data in development.

Authentication Breaks Silently

NextAuth.js session handling changed completely for App Router. Server components get session data differently than client components:

// Server component
import { auth } from '@/lib/auth'

export default async function Dashboard() {
  const session = await auth()  // Server-side session
  return <div>Hello {session?.user?.name}</div>
}

// Client component
'use client'
import { useSession } from 'next-auth/react'

export default function ClientDashboard() {
  const { data: session } = useSession()  // Client-side session
  return <div>Hello {session?.user?.name}</div>
}

Test auth flows in production mode. Session cookies behave differently between development and production. Spent half a day figuring out why users kept getting logged out after deployment. Session cookies weren't persisting. Turns out NextAuth.js v5 changed how cookies work in production mode.