مهاجرت از Pages Router به App Router در Next.js – راهنمای گام‌به‌گام برای توسعه مدرن

App Router در Next.js 13 معرفی شد و جایگزینی مدرن و قدرتمند برای Pages Router است. این مقاله، فرآیند مهاجرت را به‌صورت مرحله‌به‌مرحله توضیح می‌دهد: از به‌روزرسانی نسخه‌ها و ساختار پوشه‌ها تا انتقال کامپوننت‌ها، مسیرها، APIها و استایل‌ها — همه با کمترین تغییرات و بیشترین اطمینان.

App RouterPages RouterNext.js MigrationServer ComponentsCodemods

چرا به App Router مهاجرت کنیم؟

App Router امکاناتی مدرن برای توسعه وب فراهم می‌کند:

کامپوننت‌های سرور: کاهش جاوااسکریپت سمت کلاینت
Streaming: بارگذاری سریع‌تر با React Suspense
کش هوشمند: کش داده، کش مسیر، کش رندر
واکشی ساده‌تر: بدون نیاز به getStaticProps یا getServerSideProps
Layout طبیعی: بدون نیاز به الگوهای پیچیده getLayout

نکته طلایی: App Router و Pages Router می‌توانند همزمان استفاده شوند — مهاجرت تدریجی ممکن است.

مرحله ۱: به‌روزرسانی نسخه‌ها

npm install next@latest react@latest react-dom@latest
npm install -D eslint-config-next@latest

در VS Code: Ctrl+Shift+P → "ESLint: Restart ESLint Server"

مرحله ۲: به‌روزرسانی کامپوننت‌های کلیدی

<Image>: استفاده از next/image به‌جای next/future/image
<Link>: دیگر نیازی به تگ <a> داخل <Link> نیست
<Script>: اسکریپت‌های beforeInteractive را به app/layout.tsx منتقل کنید
فونت‌ها: استفاده از next/font برای بهینه‌سازی داخلی

مرحله ۳: ساخت پوشه app

project-root/
├── app/
├── pages/
└── ...

مرحله ۴: ساخت layout اصلی

// app/layout.tsx
export const metadata = {
  title: 'وب‌سایت من',
  description: 'ساخته‌شده با عشق و Next.js',
}

export default function RootLayout({ children }) {
  return (
    <html lang="fa">
      <body>{children}</body>
    </html>
  )
}

مرحله ۵: مهاجرت از next/head به metadata

// قبل
<Head><title>عنوان صفحه</title></Head>

// بعد
export const metadata = { title: 'عنوان صفحه' }

مرحله ۶: انتقال صفحات

Pages Router	App Router
pages/index.js	app/page.js
pages/about.js	app/about/page.js
pages/blog/[slug].js	app/blog/[slug]/page.js

مرحله ۷: مهاجرت واکشی داده

getStaticProps → fetch(..., { cache: 'force-cache' })
getServerSideProps → fetch(..., { cache: 'no-store' })
getStaticPaths → generateStaticParams()

مرحله ۸: مهاجرت API Routes

// app/api/hello/route.ts
export async function GET() {
  return Response.json({ message: 'سلام دنیا!' })
}

مرحله ۹: مهاجرت هوک‌های مسیریابی

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

const pathname = usePathname()
const searchParams = useSearchParams()

مرحله ۱۰: استایل‌دهی

CSS سراسری: در app/layout.tsx ایمپورت شود
Tailwind: پوشه app را به content در tailwind.config.js اضافه کنید

مرحله ۱۱: استفاده همزمان از دو Router

مسیریابی بین pages و app باعث بارگذاری کامل می‌شود. برای مسیریابی نرم، از router.push() در App Router استفاده کنید.

مرحله ۱۲: استفاده از Codemodها

npx next-codemod next-image-experimental ./pages
npx next-codemod new-link ./pages