How We Migrated a Production Next.js App from Pages to App Router: Next.js 15 Architecture and Real-World Gotchas

# Scan for legacy router and document dependencies
grep -rn "from 'next/router'" pages/ components/ lib/
grep -rn "from 'next/head'" pages/ components/
grep -rn "getStaticPaths" pages/
grep -rn "getInitialProps" pages/ _app.tsx _document.tsx
grep -rln "window\.\|document\." components/ pages/

import { GetServerSideProps } from 'next';

interface ProductProps {
  product: { id: string; name: string; price: number };
}

export default function ProductPage({ product }: ProductProps) {
  return (
    <div className="product-box">
      <h1>{product.name}</h1>
      <p>${product.price}</p>
    </div>
  );
}

export const getServerSideProps: GetServerSideProps = async (context) => {
  const { id } = context.params || {};
  const res = await fetch(`https://api.example.com/products/${id}`);
  const product = await res.json();
  return { props: { product } };
};

import { Suspense } from 'react';
import { notFound } from 'next/navigation';
import { RefreshButton } from './RefreshButton';
import { refreshProductAction } from './actions';

interface PageProps {
  params: Promise<{ id: string }>; // Next.js 15 Promise type
}

async function getProduct(id: string) {
  const res = await fetch(`https://api.example.com/products/${id}`, {
    // Explicit cache tagging for surgical updates
    next: { tags: [`product-${id}`, 'products'] }
  });
  
  if (!res.ok) return null;
  return res.json();
}

export default async function ProductPage({ params }: PageProps) {
  const { id } = await params; // Must await in Next.js 15
  const product = await getProduct(id);

  if (!product) {
    notFound();
  }

  return (
    <main className="max-w-4xl mx-auto p-6 space-y-6">
      <div>
        <h1 className="text-3xl font-bold text-slate-900">{product.name}</h1>
        <p className="text-xl text-slate-700">${product.price}</p>
      </div>

      {/* Progressive enhancement via Server Action */}
      <form action={refreshProductAction.bind(null, id)}>
        <RefreshButton />
      </form>

      {/* Suspense streaming for slower secondary data */}
      <Suspense fallback={<div className="p-4 border rounded animate-pulse">Loading reviews...</div>}>
        <AsyncReviewsSection productId={id} />
      </Suspense>
    </main>
  );
}

async function AsyncReviewsSection({ productId }: { productId: string }) {
  const res = await fetch(`https://api.example.com/products/${productId}/reviews`, {
    next: { revalidate: 1800 }
  });
  const reviews = await res.json();

  return (
    <section className="border-t pt-4">
      <h2 className="text-xl font-semibold mb-3">Verified Feedback</h2>
      <div className="space-y-2">
        {reviews.map((item: { id: string; author: string; comment: string }) => (
          <div key={item.id} className="p-3 bg-slate-50 rounded">
            <span className="font-medium text-slate-800">{item.author}:</span>
            <p className="text-slate-600 text-sm mt-1">{item.comment}</p>
          </div>
        ))}
      </div>
    </section>
  );
}

// /app/products/[id]/actions.ts
'use server';

import { revalidateTag } from 'next/cache';

export async function refreshProductAction(id: string) {
  // Purges only cached queries matching this specific product tag
  revalidateTag(`product-${id}`);
}

// /app/products/[id]/RefreshButton.tsx
'use client';

import { useFormStatus } from 'react-dom';

export function RefreshButton() {
  const { pending } = useFormStatus();

  return (
    <button
      type="submit"
      disabled={pending}
      className="px-4 py-2 bg-indigo-600 hover:bg-indigo-700 text-white rounded text-sm font-medium disabled:opacity-50"
    >
      {pending ? 'Refreshing cache...' : 'Sync Latest Price'}
    </button>
  );
}

[Phase 1: Root Layout]
  ├── Create app/layout.tsx and app/globals.css
  └── Verify hybrid routing (existing /pages routes still work)
          │
[Phase 2: Static Leaf Pages]
  ├── Migrate /pages/about.tsx and marketing pages
  └── Switch to export const metadata
          │
[Phase 3: Dynamic Data Routes]
  ├── Migrate /pages/products/[id].tsx -> /app/products/[id]/page.tsx
  ├── Refactor getServerSideProps to async Server Components
  └── Wire up tag-based revalidation with Server Actions
          │
[Phase 4: Route Handlers and Cleanup]
  ├── Move /pages/api endpoints to /app/api/*/route.ts
  └── Remove _document.tsx and _app.tsx