دليل التبني التدريجي لموجه التطبيق (App Router)

سيساعدك هذا الدليل في:

تحديث تطبيق Next.js من الإصدار 12 إلى الإصدار 13
ترقية الميزات التي تعمل في كل من دليل pages ودليل app
هجرة تطبيقك الحالي تدريجيًا من pages إلى app

الترقية

إصدار Node.js

أصبح الحد الأدنى لإصدار Node.js الآن v16.14. راجع توثيق Node.js لمزيد من المعلومات.

إصدار Next.js

لتحديث Next.js إلى الإصدار 13، قم بتشغيل الأمر التالي باستخدام مدير الحزم المفضل لديك:

Terminal

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

إصدار ESLint

إذا كنت تستخدم ESLint، فستحتاج إلى تحديث إصدار ESLint:

Terminal

npm install -D eslint-config-next@latest

معلومة مفيدة: قد تحتاج إلى إعادة تشغيل خادم ESLint في VS Code لتفعيل تغييرات ESLint. افتح لوحة الأوامر (cmd+shift+p على Mac؛ ctrl+shift+p على Windows) وابحث عن ESLint: Restart ESLint Server.

الخطوات التالية

بعد التحديث، راجع الأقسام التالية للخطوات التالية:

ترقية الميزات الجديدة: دليل لمساعدتك في الترقية إلى ميزات جديدة مثل مكونات الصورة والرابط المحسنة.
الهجرة من دليل pages إلى app: دليل خطوة بخطوة لمساعدتك في الهجرة التدريجية من دليل pages إلى app.

ترقية الميزات الجديدة

أدخل Next.js 13 موجه التطبيق الجديد (App Router) بميزات واتفاقيات جديدة. يتوفر الموجه الجديد في دليل app ويتعايش مع دليل pages.

لا تتطلب الترقية إلى Next.js 13 استخدام موجه التطبيق الجديد (App Router). يمكنك الاستمرار في استخدام pages مع ميزات جديدة تعمل في كلا الدليلين، مثل مكون الصورة المحدث، مكون الرابط، مكون النص البرمجي، وتحسين الخطوط.

قدم Next.js 12 تحسينات جديدة لمكون الصورة باستخدام استيراد مؤقت: next/future/image. شملت هذه التحسينات كمية أقل من JavaScript على جانب العميل، طرق أسهل لتوسيع وتصميم الصور، تحسين إمكانية الوصول، وتحميل كسول متصفح أصلي.

في الإصدار 13، أصبح هذا السلوك الجديد هو الافتراضي لـ next/image.

هناك اثنان من أدوات التعديل التلقائي (codemods) لمساعدتك في الهجرة إلى مكون الصورة الجديد:

أداة next-image-to-legacy-image التلقائية: تعيد تسمية استيرادات next/image إلى next/legacy/image بأمان وتلقائيًا. سيحافظ المكونات الحالية على نفس السلوك.
أداة next-image-experimental التلقائية: تضيف أنماط مضمنة بشكل خطير وتزيل الخصائص غير المستخدمة. سيغير هذا سلوك المكونات الحالية لتتوافق مع الإعدادات الافتراضية الجديدة. لاستخدام هذه الأداة، تحتاج إلى تشغيل أداة next-image-to-legacy-image أولاً.

مكون `<Link>`

لم يعد مكون <Link> يتطلب إضافة علامة <a> يدويًا كطفل. تمت إضافة هذا السلوك كخيار تجريبي في الإصدار 12.2 وأصبح الآن الافتراضي. في Next.js 13، يقوم <Link> دائمًا بعرض <a> ويسمح لك بإعادة توجيه الخصائص إلى العلامة الأساسية.

على سبيل المثال:

import Link from 'next/link'

// Next.js 12: يجب تداخل `<a>` وإلا سيتم استبعادها
<Link href="/about">
  <a>About</a>
</Link>

// Next.js 13: يقوم `<Link>` دائمًا بعرض `<a>` في الخلفية
<Link href="/about">
  About
</Link>

لترقية روابطك إلى Next.js 13، يمكنك استخدام أداة new-link التلقائية.

مكون `<Script>`

تم تحديث سلوك next/script لدعم كل من pages وapp، ولكن هناك بعض التغييرات التي يجب إجراؤها لضمان هجرة سلسة:

انقل أي نصوص برمجية beforeInteractive قمت بتضمينها سابقًا في _document.js إلى ملف التخطيط الجذري (app/layout.tsx).
لا تعمل استراتيجية worker التجريبية بعد في app وسيتعين إزالة النصوص البرمجية المحددة بهذه الاستراتيجية أو تعديلها لاستخدام استراتيجية مختلفة (مثل lazyOnload).
لن تعمل معالجات onLoad وonReady وonError في مكونات الخادم، لذا تأكد من نقلها إلى مكون العميل (Client Component) أو إزالتها تمامًا.

تحسين الخطوط

سابقًا، ساعدك Next.js في تحسين الخطوط عن طريق تضمين CSS الخطوط. يقدم الإصدار 13 وحدة next/font الجديدة التي تمنحك القدرة على تخصيص تجربة تحميل الخطوط مع ضمان أداء وخصوصية رائعين. يدعم next/font كل من دليل pages وapp.

بينما لا يزال تضمين CSS يعمل في pages، إلا أنه لا يعمل في app. يجب عليك استخدام next/font بدلاً من ذلك.

راجع صفحة تحسين الخطوط لتعلم كيفية استخدام next/font.

الهجرة من `pages` إلى `app`

🎥 شاهد: تعلم كيفية تبني موجه التطبيق تدريجيًا → YouTube (16 دقيقة).

قد تكون الانتقال إلى موجه التطبيق هي المرة الأولى التي تستخدم فيها ميزات React التي يبني عليها Next.js مثل مكونات الخادم (Server Components)، Suspense، والمزيد. عند دمجها مع ميزات Next.js الجديدة مثل الملفات الخاصة والتخطيطات (layouts)، تعني الهجرة تعلم مفاهيم ونماذج عقلية وسلوكيات جديدة.

نوصي بتقليل تعقيد هذه التحديثات المجتمعة عن طريق تقسيم هجرتك إلى خطوات أصغر. تم تصميم دليل app عمدًا للعمل بالتزامن مع دليل pages للسماح بالهجرة صفحة بصفحة.

يدعم دليل app المسارات المتداخلة و التخطيطات. تعلم المزيد.
استخدم المجلدات المتداخلة لتحديد المسارات وملف page.js الخاص لجعل جزء المسار متاحًا للجمهور. تعلم المزيد.
تُستخدم الاتفاقيات الخاصة للملفات لإنشاء واجهة مستخدم لكل جزء مسار. أكثر الملفات الخاصة شيوعًا هي page.js وlayout.js.
- استخدم page.js لتعريف واجهة مستخدم فريدة لمسار.
- استخدم layout.js لتعريف واجهة مستخدم مشتركة عبر مسارات متعددة.
- يمكن استخدام امتدادات الملفات .js أو .jsx أو .tsx للملفات الخاصة.
يمكنك وضع ملفات أخرى داخل دليل app مثل المكونات والأنماط والاختبارات والمزيد. تعلم المزيد.
تم استبدال وظائف جلب البيانات مثل getServerSideProps وgetStaticProps بـ واجهة برمجة تطبيقات جديدة داخل app. تم استبدال getStaticPaths بـ generateStaticParams.
تم استبدال pages/_app.js وpages/_document.js بتخطيط جذري واحد app/layout.js. تعلم المزيد.
تم استبدال pages/_error.js بملفات error.js خاصة أكثر دقة. تعلم المزيد.
تم استبدال pages/404.js بملف not-found.js.
لا يزال pages/api/* موجودًا داخل دليل pages.

الخطوة 1: إنشاء دليل `app`

قم بتحديث إلى أحدث إصدار من Next.js (يتطلب الإصدار 13.4 أو أحدث):

npm install next@latest

ثم، أنشئ دليل app جديد في جذر مشروعك (أو دليل src/).

الخطوة 2: إنشاء تخطيط جذري

أنشئ ملف app/layout.tsx جديد داخل دليل app. هذا هو التخطيط الجذري الذي سيتم تطبيقه على جميع المسارات داخل app.

export default function RootLayout({
  // يجب أن تقبل التخطيطات خاصية children.
  // سيتم ملؤها بالتخطيطات أو الصفحات المتداخلة
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

export default function RootLayout({
  // يجب أن تقبل التخطيطات خاصية children.
  // سيتم ملؤها بالتخطيطات أو الصفحات المتداخلة
  children,
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

يجب أن يتضمن دليل app تخطيطًا جذريًا.
يجب أن يحدد التخطيط الجذري علامات <html> و<body> لأن Next.js لا ينشئها تلقائيًا
يحل التخطيط الجذري محل ملفات pages/_app.tsx وpages/_document.tsx.
يمكن استخدام امتدادات الملفات .js أو .jsx أو .tsx لملفات التخطيط.

لإدارة عناصر <head> HTML، يمكنك استخدام دعم SEO المدمج:

import { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'Home',
  description: 'Welcome to Next.js',
}

export const metadata = {
  title: 'Home',
  description: 'Welcome to Next.js',
}

هجرة `_document.js` و`_app.js`

إذا كان لديك ملف _app أو _document موجود، يمكنك نسخ المحتويات (مثل الأنماط العامة) إلى التخطيط الجذري (app/layout.tsx). لن تنطبق الأنماط في app/layout.tsx على pages/*. يجب أن تحتفظ بـ _app/_document أثناء الهجرة لمنع تعطل مسارات pages/*. بمجرد اكتمال الهجرة، يمكنك حذفها بأمان.

إذا كنت تستخدم أي موفري سياق React، فسيتعين نقلهم إلى مكون عميل (Client Component).

هجرة نمط `getLayout()` إلى التخطيطات (اختياري)

أوصى Next.js بإضافة خاصية إلى مكونات الصفحة لتحقيق تخطيطات لكل صفحة في دليل pages. يمكن استبدال هذا النمط بدعم أصلي لـالتخطيطات المتداخلة في دليل app.

راجع مثال قبل وبعد

قبل

components/DashboardLayout.js

export default function DashboardLayout({ children }) {
  return (
    <div>
      <h2>My Dashboard</h2>
      {children}
    </div>
  )
}

pages/dashboard/index.js

import DashboardLayout from '../components/DashboardLayout'

export default function Page() {
  return <p>My Page</p>
}

Page.getLayout = function getLayout(page) {
  return <DashboardLayout>{page}</DashboardLayout>
}

بعد

أزل خاصية Page.getLayout من pages/dashboard/index.js واتبع خطوات هجرة الصفحات إلى دليل app.
app/dashboard/page.js
```
export default function Page() {
  return <p>My Page</p>
}
```

انقل محتويات DashboardLayout إلى مكون عميل (Client Component) جديد للاحتفاظ بسلوك دليل pages.

app/dashboard/DashboardLayout.js

'use client' // يجب أن تكون هذه التوجيه في أعلى الملف، قبل أي استيرادات.

// هذا مكون عميل
export default function DashboardLayout({ children }) {
  return (
    <div>
      <h2>My Dashboard</h2>
      {children}
    </div>
  )
}

استورد DashboardLayout إلى ملف layout.js جديد داخل دليل app.

app/dashboard/layout.js

import DashboardLayout from './DashboardLayout'

// هذا مكون خادم
export default function Layout({ children }) {
  return <DashboardLayout>{children}</DashboardLayout>
}

يمكنك نقل الأجزاء غير التفاعلية من DashboardLayout.js (مكون العميل) إلى layout.js (مكون الخادم) تدريجيًا لتقليل كمية JavaScript المكون التي ترسلها إلى العميل.

الخطوة 3: هجرة `next/head`

في دليل pages، يتم استخدام مكون React next/head لإدارة عناصر <head> HTML مثل title وmeta. في دليل app، تم استبدال next/head بـدعم SEO المدمج الجديد.

قبل:

import Head from 'next/head'

export default function Page() {
  return (
    <>
      <Head>
        <title>My page title</title>
      </Head>
    </>
  )
}

import Head from 'next/head'

export default function Page() {
  return (
    <>
      <Head>
        <title>My page title</title>
      </Head>
    </>
  )
}

بعد:

import { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'My Page Title',
}

export default function Page() {
  return '...'
}

export const metadata = {
  title: 'My Page Title',
}

export default function Page() {
  return '...'
}

راجع جميع خيارات البيانات الوصفية.

الخطوة 4: ترحيل الصفحات

الصفحات في دليل app هي مكونات خادم (Server Components) افتراضيًا. هذا يختلف عن دليل pages حيث تكون الصفحات مكونات عميل (Client Components).
جلب البيانات (Data fetching) قد تغير في app. تم استبدال getServerSideProps و getStaticProps و getInitialProps بواجهة برمجة تطبيقات أبسط.
يستخدم دليل app مجلدات متداخلة لـتحديد المسارات (defining routes) وملف page.js خاص لجعل جزء المسار متاحًا للجمهور.
دليل pages دليل app المسار
index.js page.js /
about.js about/page.js /about
blog/[slug].js blog/[slug]/page.js /blog/post-1

دليل `pages`	دليل `app`	المسار
`index.js`	`page.js`	`/`
`about.js`	`about/page.js`	`/about`
`blog/[slug].js`	`blog/[slug]/page.js`	`/blog/post-1`

نوصي بتقسيم ترحيل الصفحة إلى خطوتين رئيسيتين:

الخطوة 1: نقل مكون الصفحة المُصدَّر افتراضيًا إلى مكون عميل جديد.
الخطوة 2: استيراد مكون العميل الجديد إلى ملف page.js جديد داخل دليل app.

معلومة مفيدة: هذا هو أسهل مسار للترحيل لأنه الأكثر تشابهًا مع سلوك دليل pages.

الخطوة 1: إنشاء مكون عميل جديد

أنشئ ملفًا منفصلًا جديدًا داخل دليل app (مثل app/home-page.tsx أو ما شابه) يُصدِّر مكون عميل. لتحديد مكونات العميل، أضف توجيه 'use client' في أعلى الملف (قبل أي استيرادات).
انقل مكون الصفحة المُصدَّر افتراضيًا من pages/index.js إلى app/home-page.tsx.

'use client'

// هذا مكون عميل. يستقبل البيانات كخصائص (props)
// وله إمكانية الوصول إلى الحالة والتأثيرات تمامًا مثل مكونات الصفحة
// في دليل `pages`.
export default function HomePage({ recentPosts }) {
  return (
    <div>
      {recentPosts.map((post) => (
        <div key={post.id}>{post.title}</div>
      ))}
    </div>
  )
}

'use client'

// هذا مكون عميل. يستقبل البيانات كخصائص (props)
// وله إمكانية الوصول إلى الحالة والتأثيرات تمامًا مثل مكونات الصفحة
// في دليل `pages`.
export default function HomePage({ recentPosts }) {
  return (
    <div>
      {recentPosts.map((post) => (
        <div key={post.id}>{post.title}</div>
      ))}
    </div>
  )
}

الخطوة 2: إنشاء صفحة جديدة

أنشئ ملف app/page.tsx جديد داخل دليل app. هذا مكون خادم افتراضيًا.
استورد مكون العميل home-page.tsx إلى الصفحة.

إذا كنت تجلب البيانات في pages/index.js، انقل منطق جلب البيانات مباشرة إلى مكون الخادم باستخدام واجهات برمجة تطبيقات جلب البيانات الجديدة. راجع دليل ترقية جلب البيانات لمزيد من التفاصيل.

// استورد مكون العميل الخاص بك
import HomePage from './home-page'

async function getPosts() {
  const res = await fetch('https://...')
  const posts = await res.json()
  return posts
}

export default async function Page() {
  // جلب البيانات مباشرة في مكون خادم
  const recentPosts = await getPosts()
  // إعادة توجيه البيانات التي تم جلبها إلى مكون العميل الخاص بك
  return <HomePage recentPosts={recentPosts} />
}

// استورد مكون العميل الخاص بك
import HomePage from './home-page'

async function getPosts() {
  const res = await fetch('https://...')
  const posts = await res.json()
  return posts
}

export default async function Page() {
  // جلب البيانات مباشرة في مكون خادم
  const recentPosts = await getPosts()
  // إعادة توجيه البيانات التي تم جلبها إلى مكون العميل الخاص بك
  return <HomePage recentPosts={recentPosts} />
}

إذا كانت صفحتك السابقة تستخدم useRouter، فستحتاج إلى التحديث إلى خطافات التوجيه الجديدة. تعلم المزيد.
ابدأ خادم التطوير الخاص بك وقم بزيارة http://localhost:3000. يجب أن ترى مسار الفهرس الحالي الخاص بك، الذي يتم تقديمه الآن عبر دليل التطبيق.

الخطوة 5: ترحيل خطافات التوجيه

تمت إضافة موجه جديد لدعم السلوك الجديد في دليل app.

في app، يجب عليك استخدام الخطافات الثلاثة الجديدة المستوردة من next/navigation: useRouter()، usePathname()، و useSearchParams().

خطاف useRouter الجديد مستورد من next/navigation وله سلوك مختلف عن خطاف useRouter في pages المستورد من next/router.
- خطاف useRouter المستورد من next/router غير مدعوم في دليل app ولكن يمكن الاستمرار في استخدامه في دليل pages.
خطاف useRouter الجديد لا يُرجع سلسلة pathname. استخدم خطاف usePathname المنفصل بدلاً من ذلك.
خطاف useRouter الجديد لا يُرجع كائن query. استخدم خطاف useSearchParams المنفصل بدلاً من ذلك.
يمكنك استخدام useSearchParams و usePathname معًا للاستماع إلى تغييرات الصفحة. راجع قسم أحداث الموجه (Router Events) لمزيد من التفاصيل.
هذه الخطافات الجديدة مدعومة فقط في مكونات العميل. لا يمكن استخدامها في مكونات الخادم.

'use client'

import { useRouter, usePathname, useSearchParams } from 'next/navigation'

export default function ExampleClientComponent() {
  const router = useRouter()
  const pathname = usePathname()
  const searchParams = useSearchParams()

  // ...
}

'use client'

import { useRouter, usePathname, useSearchParams } from 'next/navigation'

export default function ExampleClientComponent() {
  const router = useRouter()
  const pathname = usePathname()
  const searchParams = useSearchParams()

  // ...
}

بالإضافة إلى ذلك، يحتوي خطاف useRouter الجديد على التغييرات التالية:

تمت إزالة isFallback لأن fallback قد تم استبداله.
تمت إزالة قيم locale و locales و defaultLocales و domainLocales لأن ميزات i18n المدمجة في Next.js لم تعد ضرورية في دليل app. تعلم المزيد حول i18n.
تمت إزالة basePath. البديل لن يكون جزءًا من useRouter. لم يتم تنفيذه بعد.
تمت إزالة asPath لأن مفهوم as قد تمت إزالته من الموجه الجديد.
تمت إزالة isReady لأنه لم يعد ضروريًا. أثناء التصيير الثابت (static rendering)، أي مكون يستخدم خطاف useSearchParams() سيتخطى خطوة التصيير المسبق وسيتم تصييره على العميل في وقت التشغيل بدلاً من ذلك.

عرض مرجع واجهة برمجة تطبيقات useRouter().

الخطوة 6: ترحيل طرق جلب البيانات

يستخدم دليل pages الدالتين getServerSideProps و getStaticProps لجلب البيانات للصفحات. داخل دليل app، تم استبدال دوال جلب البيانات السابقة هذه بـواجهة برمجة تطبيقات أبسط مبنية على fetch() ومكونات خادم React غير المتزامنة.

export default async function Page() {
  // يجب تخزين هذا الطلب مؤقتًا حتى يتم إبطاله يدويًا.
  // مشابه لـ `getStaticProps`.
  // `force-cache` هو الافتراضي ويمكن حذفه.
  const staticData = await fetch(`https://...`, { cache: 'force-cache' })

  // يجب إعادة جلب هذا الطلب في كل طلب.
  // مشابه لـ `getServerSideProps`.
  const dynamicData = await fetch(`https://...`, { cache: 'no-store' })

  // يجب تخزين هذا الطلب مؤقتًا بعمر افتراضي 10 ثوانٍ.
  // مشابه لـ `getStaticProps` مع خيار `revalidate`.
  const revalidatedData = await fetch(`https://...`, {
    next: { revalidate: 10 },
  })

  return <div>...</div>
}

export default async function Page() {
  // يجب تخزين هذا الطلب مؤقتًا حتى يتم إبطاله يدويًا.
  // مشابه لـ `getStaticProps`.
  // `force-cache` هو الافتراضي ويمكن حذفه.
  const staticData = await fetch(`https://...`, { cache: 'force-cache' })

  // يجب إعادة جلب هذا الطلب في كل طلب.
  // مشابه لـ `getServerSideProps`.
  const dynamicData = await fetch(`https://...`, { cache: 'no-store' })

  // يجب تخزين هذا الطلب مؤقتًا بعمر افتراضي 10 ثوانٍ.
  // مشابه لـ `getStaticProps` مع خيار `revalidate`.
  const revalidatedData = await fetch(`https://...`, {
    next: { revalidate: 10 },
  })

  return <div>...</div>
}

تصيير جانب الخادم (`getServerSideProps`)

في دليل pages، يُستخدم getServerSideProps لجلب البيانات على الخادم وإعادة توجيه الخصائص إلى مكون React المُصدَّر افتراضيًا في الملف. يتم تصيير HTML الأولي للصفحة من الخادم، يليه "ترطيب" الصفحة في المتصفح (جعلها تفاعلية).

pages/dashboard.js

// دليل `pages`

export async function getServerSideProps() {
  const res = await fetch(`https://...`)
  const projects = await res.json()

  return { props: { projects } }
}

export default function Dashboard({ projects }) {
  return (
    <ul>
      {projects.map((project) => (
        <li key={project.id}>{project.name}</li>
      ))}
    </ul>
  )
}

في دليل app، يمكننا وضع جلب البيانات داخل مكونات React الخاصة بنا باستخدام مكونات الخادم (Server Components). هذا يسمح لنا بإرسال كمية أقل من JavaScript إلى العميل، مع الحفاظ على HTML المُصيَّر من الخادم.

عن طريق تعيين خيار cache إلى no-store، يمكننا الإشارة إلى أنه لا يجب تخزين البيانات التي تم جلبها مطلقًا. هذا مشابه لـ getServerSideProps في دليل pages.

// دليل `app`

// يمكن تسمية هذه الدالة بأي شيء
async function getProjects() {
  const res = await fetch(`https://...`, { cache: 'no-store' })
  const projects = await res.json()

  return projects
}

export default async function Dashboard() {
  const projects = await getProjects()

  return (
    <ul>
      {projects.map((project) => (
        <li key={project.id}>{project.name}</li>
      ))}
    </ul>
  )
}

// دليل `app`

// يمكن تسمية هذه الدالة بأي شيء
async function getProjects() {
  const res = await fetch(`https://...`, { cache: 'no-store' })
  const projects = await res.json()

  return projects
}

export default async function Dashboard() {
  const projects = await getProjects()

  return (
    <ul>
      {projects.map((project) => (
        <li key={project.id}>{project.name}</li>
      ))}
    </ul>
  )
}

الوصول إلى كائن الطلب

في دليل pages، يمكنك استرداد البيانات المستندة إلى الطلب بناءً على واجهة برمجة تطبيقات HTTP لـ Node.js.

على سبيل المثال، يمكنك استرداد كائن req من getServerSideProps واستخدامه لاسترداد ملفات تعريف الارتباط (cookies) ورؤوس (headers) الطلب.

pages/index.js

// دليل `pages`

export async function getServerSideProps({ req, query }) {
  const authHeader = req.getHeaders()['authorization'];
  const theme = req.cookies['theme'];

  return { props: { ... }}
}

export default function Page(props) {
  return ...
}

يكشف دليل app عن دوال جديدة للقراءة فقط لاسترداد بيانات الطلب:

headers(): مبنية على واجهة برمجة تطبيقات رؤوس الويب، ويمكن استخدامها داخل مكونات الخادم (Server Components) لاسترداد رؤوس الطلب.
cookies(): مبنية على واجهة برمجة تطبيقات ملفات تعريف الارتباط للويب، ويمكن استخدامها داخل مكونات الخادم (Server Components) لاسترداد ملفات تعريف الارتباط.

// دليل `app`
import { cookies, headers } from 'next/headers'

async function getData() {
  const authHeader = headers().get('authorization')

  return '...'
}

export default async function Page() {
  // يمكنك استخدام `cookies()` أو `headers()` داخل مكونات الخادم
  // مباشرة أو في دالة جلب البيانات الخاصة بك
  const theme = cookies().get('theme')
  const data = await getData()
  return '...'
}

// دليل `app`
import { cookies, headers } from 'next/headers'

async function getData() {
  const authHeader = headers().get('authorization')

  return '...'
}

export default async function Page() {
  // يمكنك استخدام `cookies()` أو `headers()` داخل مكونات الخادم
  // مباشرة أو في دالة جلب البيانات الخاصة بك
  const theme = cookies().get('theme')
  const data = await getData()
  return '...'
}

توليد الموقع الثابت (`getStaticProps`)

في دليل pages، تُستخدم الدالة getStaticProps لتصيير صفحة مسبقًا في وقت البناء. يمكن استخدام هذه الدالة لجلب البيانات من واجهة برمجة تطبيقات خارجية أو مباشرة من قاعدة بيانات، وتمرير هذه البيانات إلى الصفحة بأكملها أثناء إنشائها أثناء البناء.

pages/index.js

// دليل `pages`

export async function getStaticProps() {
  const res = await fetch(`https://...`)
  const projects = await res.json()

  return { props: { projects } }
}

export default function Index({ projects }) {
  return projects.map((project) => <div>{project.name}</div>)
}

في دليل app، سيكون جلب البيانات باستخدام fetch() افتراضيًا إلى cache: 'force-cache'، والذي سيخزن بيانات الطلب مؤقتًا حتى يتم إبطالها يدويًا. هذا مشابه لـ getStaticProps في دليل pages.

app/page.js

// دليل `app`

// يمكن تسمية هذه الدالة بأي شيء
async function getProjects() {
  const res = await fetch(`https://...`)
  const projects = await res.json()

  return projects
}

export default async function Index() {
  const projects = await getProjects()

  return projects.map((project) => <div>{project.name}</div>)
}

المسارات الديناميكية (`getStaticPaths`)

في دليل pages، تُستخدم الدالة getStaticPaths لتحديد المسارات الديناميكية التي يجب تقديمها مسبقًا أثناء وقت البناء.

pages/posts/[id].js

// دليل `pages`
import PostLayout from '@/components/post-layout'

export async function getStaticPaths() {
  return {
    paths: [{ params: { id: '1' } }, { params: { id: '2' } }],
  }
}

export async function getStaticProps({ params }) {
  const res = await fetch(`https://.../posts/${params.id}`)
  const post = await res.json()

  return { props: { post } }
}

export default function Post({ post }) {
  return <PostLayout post={post} />
}

في دليل app، يتم استبدال getStaticPaths بـ generateStaticParams.

تتصرف generateStaticParams بشكل مشابه لـ getStaticPaths، ولكن لديها واجهة برمجة تطبيقات مبسطة لإرجاع معلمات المسار ويمكن استخدامها داخل التخطيطات (layouts). الشكل الذي تُرجعه generateStaticParams هو مصفوفة من الأجزاء بدلاً من مصفوفة من كائنات param متداخلة أو سلسلة من المسارات المحلولة.

app/posts/[id]/page.js

// دليل `app`
import PostLayout from '@/components/post-layout'

export async function generateStaticParams() {
  return [{ id: '1' }, { id: '2' }]
}

async function getPost(params) {
  const res = await fetch(`https://.../posts/${params.id}`)
  const post = await res.json()

  return post
}

export default async function Post({ params }) {
  const post = await getPost(params)

  return <PostLayout post={post} />
}

استخدام الاسم generateStaticParams أكثر ملاءمة من getStaticPaths للنموذج الجديد في دليل app. يتم استبدال البادئة get بـ generate الأكثر وصفية، والتي تتناسب بشكل أفضل الآن بعد أن لم تعد getStaticProps و getServerSideProps ضرورية. يتم استبدال اللاحقة Paths بـ Params، وهي أكثر ملاءمة للتوجيه المتداخل مع أجزاء ديناميكية متعددة.

استبدال `fallback`

في دليل pages، تُستخدم الخاصية fallback التي تُرجعها getStaticPaths لتحديد سلوك الصفحة التي لم يتم تقديمها مسبقًا أثناء وقت البناء. يمكن تعيين هذه الخاصية إلى true لعرض صفحة احتياطية أثناء إنشاء الصفحة، أو false لعرض صفحة 404، أو blocking لإنشاء الصفحة عند وقت الطلب.

pages/posts/[id].js

// دليل `pages`

export async function getStaticPaths() {
  return {
    paths: [],
    fallback: 'blocking'
  };
}

export async function getStaticProps({ params }) {
  ...
}

export default function Post({ post }) {
  return ...
}

في دليل app، تتحكم خاصية config.dynamicParams في كيفية التعامل مع المعلمات خارج generateStaticParams:

true: (الافتراضي) يتم إنشاء الأجزاء الديناميكية غير المضمنة في generateStaticParams عند الطلب.
false: ستعيد الأجزاء الديناميكية غير المضمنة في generateStaticParams خطأ 404.

هذا يحل محل خيار fallback: true | false | 'blocking' لـ getStaticPaths في دليل pages. لا يتم تضمين خيار fallback: 'blocking' في dynamicParams لأن الفرق بين 'blocking' و true ضئيل مع البث (streaming).

app/posts/[id]/page.js

// دليل `app`

export const dynamicParams = true;

export async function generateStaticParams() {
  return [...]
}

async function getPost(params) {
  ...
}

export default async function Post({ params }) {
  const post = await getPost(params);

  return ...
}

عند تعيين dynamicParams إلى true (الافتراضي)، عند طلب جزء مسار لم يتم إنشاؤه، سيتم عرضه من جانب الخادم (server-rendered) وتخزينه مؤقتًا.

التجديد الثابت التدريجي (`getStaticProps` مع `revalidate`)

في دليل pages، تسمح لك الدالة getStaticProps بإضافة حقل revalidate لإعادة إنشاء الصفحة تلقائيًا بعد فترة زمنية معينة.

pages/index.js

// دليل `pages`

export async function getStaticProps() {
  const res = await fetch(`https://.../posts`)
  const posts = await res.json()

  return {
    props: { posts },
    revalidate: 60,
  }
}

export default function Index({ posts }) {
  return (
    <Layout>
      <PostList posts={posts} />
    </Layout>
  )
}

في دليل app، يمكن لجلب البيانات باستخدام fetch() استخدام revalidate، والتي ستخزن الطلب مؤقتًا للعدد المحدد من الثواني.

app/page.js

// دليل `app`

async function getPosts() {
  const res = await fetch(`https://.../posts`, { next: { revalidate: 60 } })
  const data = await res.json()

  return data.posts
}

export default async function PostList() {
  const posts = await getPosts()

  return posts.map((post) => <div>{post.name}</div>)
}

مسارات API

تستمر مسارات API في العمل في دليل pages/api دون أي تغييرات. ومع ذلك، تم استبدالها بـ معالجات المسار (Route Handlers) في دليل app.

تسمح لك معالجات المسار بإنشاء معالجات طلب مخصصة لمسار معين باستخدام واجهات برمجة تطبيقات الويب Request و Response.

export async function GET(request: Request) {}

export async function GET(request) {}

معلومة جيدة: إذا كنت تستخدم مسارات API سابقًا لاستدعاء API خارجي من العميل، يمكنك الآن استخدام مكونات الخادم (Server Components) بدلاً من ذلك لجلب البيانات بأمان. تعلم المزيد حول جلب البيانات.

الخطوة 7: التنسيق

في دليل pages، كانت أوراق الأنماط العالمية مقصورة على pages/_app.js فقط. مع دليل app، تم رفع هذا القيد. يمكن إضافة الأنماط العالمية إلى أي تخطيط أو صفحة أو مكون.

Tailwind CSS

إذا كنت تستخدم Tailwind CSS، فستحتاج إلى إضافة دليل app إلى ملف tailwind.config.js الخاص بك:

tailwind.config.js

module.exports = {
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}', // <-- أضف هذا السطر
    './pages/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
  ],
}

ستحتاج أيضًا إلى استيراد أنماطك العالمية في ملف app/layout.js الخاص بك:

app/layout.js

import '../styles/globals.css'

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

تعلم المزيد حول التنسيق باستخدام Tailwind CSS

Codemods

يوفر Next.js تحويلات Codemod لمساعدتك في ترقية قاعدة التعليمات البرمجية الخاصة بك عند إهمال ميزة ما. راجع Codemods لمزيد من المعلومات.

دليل التبني التدريجي لموجه التطبيق (App Router)

الترقية

إصدار Node.js

إصدار Next.js

إصدار ESLint

الخطوات التالية

ترقية الميزات الجديدة

مكون `<Image/>`

مكون `<Link>`

مكون `<Script>`

تحسين الخطوط

الهجرة من `pages` إلى `app`

الخطوة 1: إنشاء دليل `app`

الخطوة 2: إنشاء تخطيط جذري

هجرة `_document.js` و`_app.js`

هجرة نمط `getLayout()` إلى التخطيطات (اختياري)

الخطوة 3: هجرة `next/head`

الخطوة 4: ترحيل الصفحات

الخطوة 5: ترحيل خطافات التوجيه

الخطوة 6: ترحيل طرق جلب البيانات

تصيير جانب الخادم (`getServerSideProps`)

الوصول إلى كائن الطلب

توليد الموقع الثابت (`getStaticProps`)

المسارات الديناميكية (`getStaticPaths`)

استبدال `fallback`

التجديد الثابت التدريجي (`getStaticProps` مع `revalidate`)

مسارات API

الخطوة 7: التنسيق

Tailwind CSS

Codemods

On this page