Next.js 15 App Router vs Pages Router: The Complete Migration Guide

Why the App Router? A Paradigm Shift

1. React Server Components by Default

2. Deeply Nested Layouts and State Persistence

tsx
// app/dashboard/layout.tsx
export default function DashboardLayout({ children }: { children: React.ReactNode }) {
  return (
    <div className="flex h-screen">
      <Sidebar /> {/* This never re-renders during navigation! */}
      <main className="flex-1">{children}</main>
    </div>
  );
}

3. Native Streaming & Suspense Boundaries

Step-by-Step Migration Blueprint

Step 1: Prepare Your Dependencies

bash
npm install next@latest react@latest react-dom@latest

Step 2: Create the App Directory

Step 3: Migrate Leaf Pages (The Easiest First)

1. Create app/about/page.tsx.
2. Move the JSX over.
3. If it used getStaticProps, delete it. In the App Router, data fetching is just a standard async/await fetch inside your component. Next.js automatically caches fetch calls by default to emulate SSG.

tsx
// OLD: pages/about.tsx
export async function getStaticProps() {
  const res = await fetch('https://api.example.com/company');
  const data = await res.json();
  return { props: { data } };
}

export default function About({ data }) {
  return <div>{data.name}</div>;
}

// NEW: app/about/page.tsx
export default async function AboutPage() {
  const res = await fetch('https://api.example.com/company');
  const data = await res.json();
  
  return <div>{data.name}</div>;
}

Step 4: Handle Client Interactivity

tsx
// app/products/page.tsx (Server Component)
import AddToCartButton from './AddToCartButton';
import db from '@/lib/db';

export default async function ProductPage() {
  const product = await db.product.findFirst();
  
  return (
    <div>
      <h1>{product.name}</h1>
      {/* Extract interactivity to a child Client Component */}
      <AddToCartButton productId={product.id} />
    </div>
  )
}

tsx
// app/products/AddToCartButton.tsx (Client Component)
"use client";

import { useState } from 'react';

export default function AddToCartButton({ productId }) {
  const [loading, setLoading] = useState(false);
  
  const handleAdd = () => {
    setLoading(true);
    // Add logic
  }
  
  return <button onClick={handleAdd}>{loading ? 'Adding...' : 'Add to Cart'}</button>;
}

Step 5: SEO and the New Metadata API

tsx
// app/blog/[slug]/page.tsx
export async function generateMetadata({ params }) {
  const post = await getPost(params.slug);
  
  return {
    title: `${post.title} | My Tech Blog`,
    description: post.excerpt,
    openGraph: {
      images: [post.coverImage],
    },
  };
}

Step 6: Route Handlers (Replacing API Routes)

typescript
// app/api/hello/route.ts
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const name = searchParams.get('name') || 'World';
  
  return NextResponse.json({ message: `Hello ${name}` });
}

Conclusion: Embrace the Future of React

Share this article

Comments