Next.js/data fetching

تتيح عملية إحضار البيانات في Next.js تصيير المحتوى بطرق عدة وفقًا للحالة التي تستخدم فيها التطبيق، بما في ذلك التصيير المسبق من جانب الخادم Server-Side Rendering أو التوليد الساكن للشيفرة Static Generation أو تحديث المحتوى أو إنشائه أثناء تشغيل التطبيق من خلال التوليد الساكن التدريجي Incremental Static Regeneration.

الدالة غير المتزامنة getInitialProps

نصيحة هامة: يتيح لك استخدام إحدى الدالتين getStaticProps أو getServerSideProps بدلًا من getInitialProps في إحضار البيانات أسلوبًا يجمع بين التوليد الساكن والتصيير من جانب الخادم.

تُمكّنك الدالة getInitialProps من تصيير المحتوى من جانب الخادم في الصفحة، وتسمح لك بنقل البيانات بشكل أولي، أي إرسال الصفحة بالبيانات التي أنتجها الخادم، وهذا مفيد خصوصًا في تحسين محركات البحث SEO.

ملاحظة: يُعطل استخدام الدالة getInitialProps التحسين التلقائي الساكن.

تُعد الدالة getInitialProps دالة غير متزامنة async يمكن إضافتها إلى أي صفحة كتابع ساكن static method. إليك مثالًا:

function Page({ stars }) {
  return <div>Next stars: {stars}</div>
}

Page.getInitialProps = async (ctx) => {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const json = await res.json()
  return { stars: json.stargazers_count }
}

export default Page

أو باستخدام مكوّن صنف:

import React from 'react'

class Page extends React.Component {
  static async getInitialProps(ctx) {
    const res = await fetch('https://api.github.com/repos/vercel/next.js')
    const json = await res.json()
    return { stars: json.stargazers_count }
  }

  render() {
    return <div>Next stars: {this.props.stars}</div>
  }
}

export default Page

تُستخدم الدالة getInitialProps لإحضار بعض البيانات بشكل غير متزامن لتحلل بعدها البيانات الجاهزة المعادة props من الدالة أثناء التصيير في الواجهة الخلفية بشكل مشابه لما يفعله التابع

JSON.stringify. تأكد أن الكائن الذي تعيده الدالة getInitialProps هو كائن بسيط لا يحتوي على الخاصيات Date أو Map أو Set.

تنفذ الدالة getInitialProps على الخادم فقط لتحميل الصفحة مبدئيًا، ثم تنفذ في الواجهة الأمامية عند الانتقال إلى وجهة أخرى باستخدام المكون next/link أو المكون next/router. لكن إن استخدمت الدالة getInitialProps تطبيقًا مخصصًا app.js_ وتضمنت الصفحة التي سننتقل إليها الدالة getServerSideProps عندها لن تعمل الدالة getInitialProps على الخادم.

الكائن context

تتلقى الدالة getInitialProps وسيطًا واحدًا يدعى context، وهو كائن يمتلك الخاصيات التالية:

• pathname: الوجهة الحالية، وهي مسار الصفحة ضمن المجلد pages/.
• query: قسم الاستعلام النصي من عنوان URL والمُحلَّل ككائن.
• asPath: من النوع String، يمثل المسار الفعلي (بما في ذلك الاستعلام) الظاهر في شريط عنوان المتصفح.
• req: كائن طلب HTTP (خادم فقط).
• res: كائن طلب استجابة HTTP (خادم فقط).
• err: كائن خطأ وينتج عن أي خطا يحدث أثناء التصيير.

التحفظات على استخدام الدالة في

• لا يمكن استخدام الدالة getInitialProps داخل المكوّنات الأبناء، بل فقط عند التصدير الافتراضي لكل صفحة.
• إن كنت تستخدم وحدات الواجهة الخلفية فقط داخل الدالة getInitialProps، فتأكد من إدراجها بشكل صحيح وإلا ستبطئ تطبيقك.

ملاحظة: بغض النظر عن نوع التصيير ستُمرر أية خاصية props إلى مكون الصفحة وتُستعرض في الواجهة الأمامية كجزء من صفحة HTML المبدئية. إن الغاية من ذلك هو السماح بترطيب الصفحة hydrate بالشكل الصحيح. تأكد من عدم تمرير أية معلومات حساسة لا ينبغي عرضها في الواجهة الأمامية من خلال الخاصيات props.

استخدام الدالة مع TypeScript

إن كنت تستخدم TypeScript، بإمكانك استخدام النوع NextPage من أجل مكونات الدوال:

import { NextPage } from 'next'

interface Props {
  userAgent?: string;
}

const Page: NextPage<Props> = ({ userAgent }) => (
  <main>Your user agent: {userAgent}</main>
)

Page.getInitialProps = async ({ req }) => {
  const userAgent = req ? req.headers['user-agent'] : navigator.userAgent
  return { userAgent }
}

export default Page

ويمكنك استخدام NextPageContext من أجل React.Component :

import React from 'react'
import { NextPageContext } from 'next'

interface Props {
  userAgent?: string;
}

export default class Page extends React.Component<Props> {
  static async getInitialProps({ req }: NextPageContext) {
    const userAgent = req ? req.headers['user-agent'] : navigator.userAgent
    return { userAgent }
  }

  render() {
    const { userAgent } = this.props
    return <main>Your user agent: {userAgent}</main>
  }
}

التصيير من جانب الخادم باستخدام الدالة getServerSideProps

عندما تُصدِّر دالة تُدعى getServerSideProps (التصيير من جانب الخادم SSR) من صفحتك، تُصدَّر الصفحة مسبقًا عند كل طلب باستخدام البيانات التي تعيدها الدالة getServerSideProps:

export async function getServerSideProps(context) {
  return {
    props: {}, // تمرر إلى مكوّن الصفحة على شكل خصائص
  }
}

ملاحظة: بغض النظر عن نوع التصيير، أي شيء يُمرر إلى مكون الصفحة page ضمن الخاصيات props يُعرَض في طرف العميل ضمن صفحة HTML، وصحيح هذا يساعد على ترطيب الصفحة وتغذيها بالبيانات والمعلومات، ولكن كن حذرًا من تمرير أي بيانات حساسة لا يجب أن تُمرر إلى طرف العميل.

تنفيذ الدالة getServerSideProps

تُنفَّذ هذه الدالة من جانب الخادم ولا يمكن تنفيذها من قبل المتصفح، وما يحدث عندما تستخدمها الصفحة أنه:

• عندما تطلب الصفحة مباشرة، ستُنفَّذ الدالة getServerSideProps وستُصيّر مسبقًا مع الخاصيات التي تعيدها الدالة.
• عندما تطلب الصفحة من جانب العميل من خلال next/link أو next/router، سترسل Next.js طلبًا من خلال واجهة برمحية API إلى الخادم لكي ينفِّذ الدالة getServerSideProps.

تعيد الدالة getServerSideProps النتيجة على شكل بيانات بصيغة JSON تُستخدم في تصيير الصفحة، وستنجز Next.js كل هذه الأعمال تلقائيًا دون أن تفعل أي شيء إضافي عندما تُعرّف هذه الدالة.

يمكنك استخدام الأداة next-code-elimination tool للتحقق من شيفرة Next.js التي تُحذف عندما تُجمّع للعمل من ناحية العميل.

تُصدَّر الدالة getServerSideProps من الصفحات فقط، ولا يمكن تصديرها من ملفات لا تُعدُّ صفحاتٍ. وينبغي الانتباه إلى تصديرها كدالة قائمة بحد ذاتها standalone، فلن تعمل إن أضفتها كخاصية من خواص مكوّن الصفحة.

يمكنك معرفة جميع المعاملات والخاصيات التي تُستخدم مع getServerSideProps، بالاطلاع على مرجع الواجهة البرمجية API reference.

حالات استخدام الدالة getServerSideProps

استخدم هذه الدالة إن أردت أن تصيّر صفحة من المفترض إحضار بياناتها عند طلب هذه الصفحة. وقد يكون السبب هو طبيعة البيانات أو خصائص الطلب (مثل ترويسات الاستيثاق authorization أو الموقع الجغرافي). ستُصيّر الصفحات التي تستخدم getServerSideProps من جانب الخادم أثناء الطلب ولن تُخزَّن مؤقتًا ما لم تُهيَّأ ترويسات التحكم بالتخزين المؤقت.

إن لم تشأ أن تصير البيانات أثناء الطلب، فقد تفكّر في إحضارها من ناحية العميل أو باستخدام الدالة getStaticProps.

استخدام الدالة getServerSideProps مقابل مسارات الواجهة البرمجية API Route

قد يكون تلجأ إلى أسلوب إنشاء مسار API لإحضار البيانات من الخادم ثم استدعاء هذا المسار من خلال الدالة getServerSideProps لكن هذا الأسلوب غير ضروري وغير مجدٍ، لأنه سينفِّذ طلبًا إضافيًا نظرًا لتنفيذ الدالة getServerSideProps مع مسار الواجهة API معًا على الخادم.

لنفترض مثلًا وجود مسار API يُستخدم في إحضار بيانات من منظومة إدارة المحتوى CMS. يُستدعى هذا المسار عندها من قبل الدالة getServerSideProps مباشرة، وسينتج عن ذلك استدعاءً إضافيًا يخفض الأداء. بدلًا من ذلك أدرج تعليمات المنطق الذي يعتمده مسار API ضمن الدالة مباشرة، وقد يكون هذا المنطق استدعاءً لمنظومة إدارة المحتوى أو قاعدة بيانات أو مسارات API أخرى.

إحضار البيانات من جانب العميل

إن احتوت صفحتك على بيانات تُحدَث باستمرار ولا حاجة لتصييرها مسبقًا، بإمكانك عندها إحضار البيانات من جانب العميل وكمثال على سيناريوهات كهذه إحضار بيانات خاصة بالعميل:

• أظهر بداية صفحتك دون بيانات، إذ يمكن تصيير بعض أجزاء الصفحة باستخدام نمط التوليد الساكن وأن تُظهِر تقدم تنزيل البيانات المفقودة.
• أحضر بعد ذلك البيانات انطلاقًا من جانب العميل ثم أعرضها عندما تجهز.

تعمل هذه المقاربة جيدًا مع الصفحات التي تمثل لوحة تحكم أو إعدادات لانها صفحات خاصة بالمستخدم لا حاجة لتطبيق قواعد تحسين محركات البحث عليها، ولا حاجة لتصييرها مسبقًا. تُحدَّث هذه البيانات باستمرار ويتطلب ذلك إحضار هذه البيانات عند الطلب فقط.

استخدام الدالة getServerSideProps لإحضار البيانات عند الطلب

يعرض المثال التالي كيفية إحضار البيانات عند الطلب ثم تصيير البيانات مسبقًا قبل عرضها:

function Page({ data }) {
  // تصيير البيانات
}

// تُستدعى هذه الشيفرة عند كل طلب
export async function getServerSideProps() {
  // أحضر البيانات من وصلة برمجية خارجية
  const res = await fetch(`https://.../data`)
  const data = await res.json()

  // تمرير البيانات إلى الصفحة عن طريق الخاصيات
  return { props: { data } }
}

export default Page

التخزين المؤقت أثناء التصيير من جانب الخادم SSR

بإمكانك استخدام ترويسات التخزين المؤقت Cache-Control ضمن الدالة getServerSideProps لتخزين الاستجابات الديناميكية مؤقتًا. استخدم القيمة stale-while-revalidate مثلًا:

// (s-maxage=10)تُعد هذه القيمة جديدة مدة عشر ثوان.
// إن أعيد الطلب ضمن هذه الثواني العشرة ستبقى هذه القيمة حديثة
// بينما إن أعيد الطلب قبل 59 ثانية ستُصيّر القيمة على الرغم من كونها قديمة
// (stale-while-revalidate=59).
// سيجري طلب خلف الستار لتحديث  هذه القيمة في الذاكرة المؤقتة 
// سترى هذه القيمة الجديدة إن حدّثت الصفحة 
export async function getServerSideProps({ req, res }) {
  res.setHeader(
    'Cache-Control',
    'public, s-maxage=10, stale-while-revalidate=59'
  )

  return {
    props: {},
  }
}

تصيير الأخطاء عند استخدام الدالة getServerSideProps

إن ظهر خطأ داخل الدالة getServerSideProps فستعرض الملف pages/500.js. راجع توثيق الصفحة 500 لتتعلم طريقة إنشائها. لن يُستخدم هذا الملف في مرحلة التطوير وستُعرض الصفحة الخاصة بهذه المرحلة بدلًا منه.

التوليد الساكن للمسارات باستخدام الدالة getStaticPaths

عندما تمتلك الصفحة مسارات ديناميكية وتستخدم في الوقت نفسه الدالة getStaticProps، لا بد حينها من تعريف قائمة بالمسارات التي ينبغي توليدها بشكل ساكن، وعند تصدير الدالة التي تُدعى getStaticPaths (في آلية توليد الساكن للشيفرة) من صفحة تعتمد على مسارات ديناميكية، فستعمل Next.js آلية التصيير المسبق pre-render لتصيير جميع المسارات المعرفة عبر هذه الدالة.

// pages/posts/[id].js

// ‫يولد المسار `/posts/1` والمسار `/posts/2`
export async function getStaticPaths() {
  return {
    paths: [{ params: { id: '1' } }, { params: { id: '2' } }],
    fallback: false, // can also be true or 'blocking'
  }
}

// ‫`getStaticPaths` يتطلب استعمال الدالة `getStaticProps`
export async function getStaticProps(context) {
  return {
    // Passed to the page component as props
    props: { post: {} },
  }
}

export default function Post({ post }) {
  // Render post...
}

يمكنك معرفة جميع المعاملات والخاصيات التي تُستخدم مع getStaticPaths، بالاطلاع على مرجع الواجهة البرمجية API reference.

حالات استخدام الدالة getStaticPaths

ينبغي استخدام هذه الدالة إن كنت ستصيّر مسبقًا صفحات تحتوي على مسارات ديناميكية وكان:

• مصدر البيانات هو منظومة إدارة محتوى دون واجهة headless CMS.
• مصدر البيانات هو قاعدة بيانات.
• مصدر البيانات هو نظام إدارة ملفات.
• بالإمكان التخزين المؤقت للبيانات للعموم (غير مخصصة لمستخدم محدد).
• لا بدّ من تصيير الصفحة مسبقًا (لأغراض تحسين محركات البحث "سيو") وأن يجري ذلك بسرعة. تولّد getStaticProps ملفات HTML و JSON التي يمكن تخزينها مؤقتًا من قبل منظومة توصيل محتوى CDN لرفع الأداء.

تنفيذ الدالة getStaticPaths

تُنفَّذ هذه الدالة عند بناء التطبيق في وضع الإنتاج فقط. يمكنك التحقق من أن الشيفرة المكتوبة داخل الدالة getStaticPaths ستُزال من الشيفرة المجمّعة من ناحية العميل باستخدام الأداة next-code-elimination tool.

تنفيذ الدالة getStaticProps يتعلق بتنفيذ الدالة getStaticPaths وفق ما يلي:

• تُنفَّذ الدالة getStaticProps عند تنفيذ الأمر next build لكل مسار paths يُعاد أثناء البناء.
• تُنفَّذ الدالة getStaticProps في الخلفية عند استخدام التوجيه fallback: true.
• تُستدعى الدالة getStaticProps قبل التصيير الأولي عند استخدام التوجيه fallback: blocking.

أماكن استخدام الدالة getStaticPaths

يمكن استخدام الدالة getStaticPaths في المواضع التالية:

• تُستخدم مع الدالة .
• لا يمكن استخدامها مع الدالة .
• يمكن تصديرها من صفحة ذات مسارات ديناميكية تستخدم أيضًا الدالة .
• لا يمكن تصديرها من ملف غير موجود ضمن مجلد الصفحات pages (مثلًا من مجلد المكونات components).
• يجب تصديرها كدالة قائمة بحد ذاتها standalone، فلن تعمل إن أضفتها كخاصية من خواص مكوّن الصفحة.ملاحظة: تُستدعى الدالة عند كل استدعاء خلال مرحلة التطوير (next dev).

توليد المسارات عند الطلب

تتيح الدالة getStaticPaths إمكانية التحكم بأي صفحة تُولَّد أثناء عملية البناء بدلًا من توليدها عند الطلب on-demand مع الخيار fallback، إذ سيودي توليد الكثير من الصفحات إلى حدوث بطء في عملية البناء.

يمكنك تأجيل عملية توليد كل الصفحات عند الطلب بإعادة مصفوفة فارغة مع paths، وتبرز فائدة ذلك عند نشر تطبيق Next.js على أكثر من بيئة، إذ تصبح عملية البناء سريعة آنذاك في حال كنا نريد ذلك مثل تجربة التطبيق (أثناء التطوير وليس في بيئة الإنتاج)، وعلى أي حال هذا مفيد أيضًا في المواقع التي تتألف من مئات أو آلاف الصفحات الساكنة.

// pages/posts/[id].js

export async function getStaticPaths() {
  // في حال كنا نريد تجربة التطبيق في وضع الاستعراض، فلا يجري تصيير أي
  // صفحة ساكنة تصييرًا مسبقًا. وهذا يُسرع عملية البناء
  // ولكن تصبح عملية تحميل الصفحة الابتدائية بطيئة
  if (process.env.SKIP_BUILD_STATIC_GENERATION) {
    return {
      paths: [],
      fallback: 'blocking',
    }
  }

  // جلب جميع المنشورات عبر وصلة خارجية
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // جلب جميع المسارات التي نريد تصييرها مسبقًا لما يقابل كل منشور
  // وصير كل الصفحات مسبقًا في بيئة الإنتاج، وهذا يُبطئ عملية البناء
  // ولكن يسرع من عملية تحميل الصفحة الابتدائية
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))

  // يعني أن بقية المسارات الأخرى تتوجه إلى الصفحة 404 { fallback: false }
  return { paths, fallback: false }
}

التوليد الساكن للصفحات باستخدام الدالة getStaticProps

عندما تُصدِّر دالة تُدعى getStaticProps (توليد ساكن للموقع) من صفحة، تُصيِّر Next.js هذه الصفحة أثناء بناء التطبيق باستخدام الخاصيات props التي تُعيدها هذه الدالة.

export async function getStaticProps(context) {
  return {
    props: {}, // تُمرر إلى مكوِّن الصفحة على شكل خاصيات
  }
}

ملاحظة: بغض النظر عن نوع التصيير، أي شيء يُمرر إلى مكون الصفحة page ضمن الخاصيات props يُعرَض في طرف العميل ضمن صفحة HTML، وصحيح هذا يساعد على ترطيب الصفحة وتغذيها بالبيانات والمعلومات، ولكن كن حذرًا من تمرير أي بيانات حساسة لا يجب أن تُمرر إلى طرف العميل.

حالات استخدام الدالة getStaticProps

عليك استخدام هذه الدالة في الحالات التالية:

• البيانات التي ستستخدمها لتصيير الصفحة أثناء بناء التطبيق متوفرة مسبقًا قبل أن يطلبها المستخدم.
• مصدر البيانات هو نظام إدارة محتوى دون واجهة headless CMS.
• لا بدّ من تصيير الصفحة مسبقًا (لأغراض تحسين محركات البحث "سيو") وأن يجري ذلك بسرعة. تولّد getStaticProps ملفات HTML و JSON التي يمكن تخزينها مؤقتًا من قبل منظومة توصيل محتوى CDN لرفع الأداء.
• عند إمكانية التخزين المؤقت للبيانات للعموم (غير مخصصة لمستخدم محدد). يمكن تجاوز هذا الشرط في بعض الحالات الخاصة من خلال استخدام برمجيات وسطية Middleware لإعادة كتابة المسار.

تنفيذ الدالة getStaticProps

تُنفَّذ هذه الدالة دائمًا من جانب الخادم وليس من جانب العميل ويمكنك التحقق من أن الشيفرة المكتوبة داخل الدالة getStaticProps ستُزال من الشيفرة المجمّعة من ناحية العميل باستخدام الأداة next-code-elimination tool:

• تُنفَّذ getStaticProps دائمًا أثناء تنفيذ الأمر next build.
• تُنفّذ getStaticProps في الخلفية عند استخدام التوجيه revalidate.
• تُنفّذ getStaticProps في الخلفية عند الطلب عند استخدام revalidate()‎.

عندما تُستخدم الدالة getStaticProps مع نمط التجديد الساكن التدريجي للصفحات Incremental Static Regeneration، ستُنفَّذ في الخلفية أثناء إعادة تقييم الصفحة القديمة ومن ثم تُقدّم الصفحة المحدّثة إلى المتصفح.

لا يمكن للدالة getStaticProps أن تلج إلى الطلبات الواردة (كمعاملات الاستعلام أو ترويسات HTTP) لأنها تولّد ملف HTML ساكن، لكن إن أردت الوصول إلى هذه الطلبات فكِّر باستخدام برمجيات وسطية إضافة إلى هذه الدالة.

استخدام الدالة لإحضار البيانات من منظومة إدارة محتوى CMS

تعرض الشيفرة التالية طريقة إحضار قائمة بالمنشورات من منظومة إدارة محتوى:

// getStaticProps() تُعرض المنشورات أثناء بناء التطبيق باستخدام 
function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}
// تُستدعى هذه الدالة أثناء بناء التطبيق من جانب الخادم
// لن تُستدعى من جانب العميل لذلك بالإمكان الاستعلام من قاعدة بيانات مباشرة

export async function getStaticProps() {
  //خارجية API تستدعى وصلة 
  // يمكن استدعاء أية مكتبة لإحضار البيانات
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // المنشورات كخاصيات أثناء بناء التطبيق Blog يتلقى المكوّن 
  // { props: { posts } } بإعادة
  return {
    props: {
      posts,
    },
  }
}

export default Blog

يمكنك معرفة جميع المعاملات والخاصيات التي تُستخدم مع getStaticProps، بالاطلاع على مرجع الواجهة البرمجية API reference.

كتابة شيفرة تعمل من جانب الخادم مباشرة

لن تُنفَّذ الدالة getStaticProps إلا من ناحية الخادم فقط ولا يمكن تنفيذها من ناحية العميل وبالتالي لن تجدها ضمن شيفرة جافا سكربت الخاصة بالمتصفح وستتمكن من كتابة استعلامات مباشرة من قاعدة البيانات دون إرسالها إلى المتصفحات. وهكذا يمكنك كتابة شيفرة تُنفَّذ من جانب الخادم مباشرة ضمن الدالة getStaticProps بدلًا من كتابة مسار واجهة API أي API route ليحضر تلك البيانات من واجهة خارجية عند استدعائها.

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

// lib/fetch-posts.js
// تُشارك الدالة التالية
// API routes و getStaticProps مع 
// `lib/` من المجلد
export async function loadPosts() {
  //لخارجية للحصول على المنشورات API تستدعى وصلة 
  const res = await fetch('https://.../posts/')
  const data = await res.json()

  return data
}

// pages/blog.js
import { loadPosts } from '../lib/load-posts'

// تُنفَّذ الدالة من جانب الخادم فقط
export async function getStaticProps() {
  //بالإمكان استدعاء نفس الدالة مباشرة `/api`  بدلًا من إحضار المسار 
  const posts = await loadPosts()

   // تُمرر إلى مكوِّن الصفحة على شكل خاصيات
  return { props: { posts } }
}

إن لم تستخدم مسارات API لإحضار البيانات بإمكانك استخدام الدالة ()fetch ضمن الدالة getStaticProps.

يمكنك التحقق مما سيُزال من الشيفرة المجمّعة من ناحية العميل باستخدام الأداة next-code-elimination tool.

التوليد التلقائي لشيفرة HTML و JSON

عندما تُصيَّر صفحة تحتوي على الدالة getStaticProps أثناء بناء التطبيق، ستولّد Next.js ملف JSON بالإضافة إلى ملف HTML وذلك لاحتواء نتيجة تنفيذ تلك الدالة.

يُستخدم ملف JSON ذاك للتوجيه من جانب العميل عبر next/link أو next/router. فعندما ننتقل إلى الصفحة التي صُيِّرت مسبقًا باستخدام الدالة getStaticProps، ستحضر Next.js ملف JSON (الذي بني مُسبقًا أثناء بناء التطبيق) ثم تسنده إلى خصائص مكوِّن الصفحة. وبالتالي لن تستدعي عمليات التنقل بين صفحات التطبيق من ناحية العميل استدعاء الدالة getStaticProps لأن ما سيُستخدم فعلًا هو ملف JSON المُصدَّر.

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

أماكن استخدام الدالة getStaticProps

يمكن تصدير الدالة getStaticProps من صفحة Next.js (مكوّن صفحة) فقط ولا يمكن تصديرها من ملفات لا تمثل صفحات. ومن أهم الأسباب الكامنة وراء هذا التقييد هو أن رياكت تحتاج إلى جميع البيانات قبل تصيير الصفحة.

لا بد أن تُصدّر أيضًا الدالة getStaticProps لتكون دالة قائمة بذاتها، فلن تعمل إن أضفتها كخاصية إلى مكوِّن الصفحة.

ملاحظة: إن أنشأت تطبيقًا مخصصًا فتأكد من تمرير pageProps إلى مكون الصفحة وإلا ستكون الخاصيات props فارغة.

تُستدعى الدالة عند كل استدعاء خلال مرحلة التطوير (next dev).

نمط الاستعراض

بإمكانك أن تتجاوز التوليد التلقائي مؤقتًا وتصيِّر الصفحة عند الطلب بدلًا من تصييرها أثناء بناء التطبيق باستخدام نمط الاستعراض Preview Mode. فقد تستخدم مثلًا منظومة إدارة محتوى بلا واجهة، وتريد أن تستعرض مسودة للموقع قبل نشره.

التجديد التدريجي الساكن

تتيح لك Next.js أن تنشئ أو تُحدِّث الصفحات الساكنة بعد أن تنهي بناء الموقع من خلال التجديد التدريجي الساكن Incremental Static Regeneration (واختصارًا ISR) الذي يمكِّنك من استخدام التجديد الساكن للصفحات منفردةً دون الحاجة إلى إعادة بناء الموقع بأكمله، وهكذا ستحتفظ بميزات الصفحات الساكنة مع توسيع إمكانات ملايين الصفحات.

لاستخدام ISR أضف الخاصية revalidate إلى الدالة getStaticProps:

function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

// تُستدعى هذه الدالة أثناء البناء من جانب الخادم
// يمكن استدعاؤها مجددًا من قبل دالة لا تعمل على الخادم 
// عندما تُفعّل خاصية إعادة التحقق ويصل طلب جديد
export async function getStaticProps() {
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  return {
    props: {
      posts,
    },
    //إعادة تجديد الصفحة Next.js تحاول
    // عندما يصل الطلب
    // مرة كل 10 ثوان على الأكثر
    revalidate: 10, // بالثواني
  }
}

// تُستدعى هذه الدالة أثناء البناء من جانب الخادم
// يمكن استدعاؤها مجددًا من قبل دالة لا تعمل على الخادم 
// إن لم يُحدّث المسار
export async function getStaticPaths() {
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // الحصول على المسارات التي نريد إعادة تصييرها وفقًا للمنشورات المطلوبة
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))

  // سنصير هذه المسارت فقط مسبقًا أثناء البناء
  // { fallback: blocking }
  // سيصير الخادم هذه الصفحات في حال لم تكن المسارات موجودة
  return { paths, fallback: 'blocking' }
}

export default Blog

عندما تُطلب صفحة مصيّرة مسبقًا أثناء بناء التطبيق فستعرض مبدئيًا البيانات الموجودة في الذاكرة المؤقتة:

• عندما تُطلب الصفحة مجددًا ضمن مدة الثواني العشرة بعد الطلب الأساسي ستُعرض الصفحة ذاتها مباشرة من بيانات الذاكرة المؤقتة.
• بعد الثواني العشرة أيضًا ستُعرض الصفحة المخزنة نفسها أيضًا (الصفحة القديمة).
• لكن ما يحدث حينها أنّ Next.js ستطلب تجديد الصفحة في الخلفية.
• عندما تجدد الصفحة بنجاح، تتحقق من بيانات الذاكرة المؤقتة للصفحة وتحدث ما يجب تحديثه، وستبقى الصفحة القديمة نفسها إن فشل التجديد.

عندما يُطلب مسار محدد لم يُحدّث بعد، ستصيِّر الصفحة من جانب الخادم عند أول طلب، بينما ستُخدَّم الصفحة الساكنة عند ورود أية طلبات جديدة من الذاكرة المؤقتة.

إعادة التحقق حين الطلب

عندما تضبط قيمة الخاصية revalidate على 60 ثانية، سيرى كل زوار صفحتك النسخة الموّلدة عن موقعك مدة دقيقة كاملة، والطريقة الوحيدة للتأكد من صحة بيانات الذاكرة المؤقتة هو زيارة الصفحة بعد مضي دقيقة.

تدعم Next.js بدءًا من النسخة v12.2.0 التجديد التدريجي للصفحات حين الطلب، وذلك للتحقق اليدوي من بيانات الذاكرة المؤقتة الخاصة بهذه الصفحة. سيسهّل ذلك تحديث الموقع عندما:

• تُنشأ أو تُحدث بيانات ضمن منظومة إدارة المحتوى.
• تتغير البيانات الوصفية المتعلقة بالتجارة الإلكترونية (سعر، وصف، فئات، مراجعات، الخ.)

لا حاجة للخاصية revalidate داخل الدالة getStaticProps لاستخدام ميزة إعادة التحقق حين الطلب. فإن لم تحدد قيمة الخاصية revalidate في شيفرتك، تستخدم Next.js القيمة الافتراضية وهي false (لا إعادة للتحقق) وبالتالي لن يُعاد التحقق من بيانات الصفحة المخزنة إلا حين الطلب وذلك باستدعاء الدالة revalidate()‎.

استخدام إعادة التحقق عند الطلب

استخدم بدايةً مفتاح استيثاق token يميزه تطبيقك وذلك لمنع الدخول غير المصرح به إلى مسار API الذي ستستخدمه لإعادة التحقق. يمكن الوصول إلى المسار (يدويًا أو عن طريق خُطافات Hook) من خلال هيكلة عنوان URL على الشكل التالي:

https://<your-site.com>/api/revalidate?secret=<token>

أضف المفتاح تاليًا على شكل متغير بيئة Environment Variable ثم أنشئ مسار API لإعادة التحقق:

// pages/api/revalidate.js

export default async function handler(req, res) {
  // التحقق من المفتاح للتأكد من صحة الطلب
  if (req.query.secret !== process.env.MY_SECRET_TOKEN) {
    return res.status(401).json({ message: 'Invalid token' })
  }

  try {
    await res.revalidate('/path-to-revalidate')
    return res.json({ revalidated: true })
  } catch (err) {
    // في حال حدث خطأ، ستتابع في عرض آخر صفحة ولِّدت بشكل صحيح
   
    return res.status(500).send('Error revalidating')
  }
}

انظر هذا المثال.

اختبار التجديد التدريجي الساكن ISR حين الطلب في نمط التطوير

عندما تشغل التطبيق محليًا من خلال الأمر next dev، تُستدعى الدالة مع كل طلب. وللتحقق من صحة إعدادات ISR حين الطلب، لا بد من إنشاء نسخة إنتاج وتشغيل خادم الإنتاج:

$ next build
$ next start

عندها ستتأكد من صحة إعادة التحقق من بيانات الصفحات الساكنة.

معالجة الأخطاء وإعادة التحقق

إن حصل خطأ ما داخل الدالة getStaticProps عندما تُجدَّد البيانات في الخلفية أو عندما توقف التنفيذ من خلال الشيفرة يدويًا (في حال التقطت خطأً)، فإن ما يُعرض هو آخر توليد ناجح للصفحة. ستحاول Next.js خلال الطلبات الفرعية اللاحقة استدعاء الدالة getStaticProps:

export async function getStaticProps() {
  //من بيانات الصفحة Next.js إن تسبب الطلب في وقوع خطأ غير متوقع، لن تتحقق 
  //عند الطلب التالي getStaticProps وستحاول استدعاء الدالة 
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  if (!res.ok) {
  // قد ترغب عند وقوع خطأ من جانب الخادم أن تظهر الخطأ بدلًا
  // من إعادته وبالتالي لن تُحدث بيانات الذاكرة المؤقتة
  // حتى الطلب الناجح التالي
     
    throw new Error(`Failed to fetch posts, received status ${res.status}`)
  }

  // إن نجح الطلب، أعد المنشور
  // ثم أعد التحقق بعد 10 ثوان
  return {
    props: {
      posts,
    },
    revalidate: 10,
  }
}

الاستضافة الذاتية والتجديد التدريجي الساكن ISR

يعمل التجديد التدريجي الساكن في مواقع Next.js التي تريد أن تديرها بنفسك بطريقة مختلفة عندما تستخدم next start. وبإمكانك استخدام هذا الأسلوب عندما تنشر الموقع على منسق حاويات container orchestrator مثل Kubernetes أو HashiCorp Nomad. تُخزّن الأصول assets افتراضيًا في الذاكرة ضمن كل علبة pod، ويعني ذلك وجود نسخة عن كل ملف ساكن في كل علبة. ستُعرض البيانات القديمة حتى تُستهدف علبة محددة بطلب.

بإمكانك تعطيل ميزة التخزين المؤقت في الذاكرة لضمان الترابط بين جميع العلب، مما يدفع الخادم إلى الاستفادة من الموجودات التي ولّدها ISR ضمن نظام الملفات. كما يمكنك مشاركة مخزن على الشبكة network mount ضمن علب منسق الحاويات Kubernetes (أو أية ترتيب مشابه) لإعادة استخدام الذاكرة المؤقتة لمنظومة الملفات بين مختلف الحاويات. وبهذا الأسلوب سيُشارك المجلد next. والذي يحتوي على المخزن المؤقت next/image ويعاد استخدامه.

ولتعطيل ذاكرة التخزين المؤقت، اضبط قيمة الخاصية isrMemoryCacheSize على القيمة 0 ضمن الملف next.config.js:

module.exports = {
  experimental: {
   // افتراضيًا 50 ميغا بايت 
    isrMemoryCacheSize: 0,
  },
}

ملاحظة: لا بد أن تأخذ في الحسبان السباق بين العلب المختلفة التي تحاول تحديث الذاكرة المؤقتة في الوقت ذاته، وذلك وفقًا لطريقة تهيئة المخزن المشترك.

إحضار البيانات من جانب العميل

لهذا الأسلوب أهمية خاصة عندما لا تحتاج الصفحة إلى فهرستها لتحسين محركات البحث، أو إن كنت لا تريد تصيير بياناتك مسبقًا أو إن احتاج محتوى صفحاتك للتحديث باستمرار. وعلى خلاف الواجهة البرمجية لعملية التصيير من جانب الخادم، يمكنك إحضار البيانات من جانب العميل من خلال المكوّن نفسه.

إن أحضرت البيانات من خلال الصفحة، ستجري العملية خلال زمن التشغيل، ويُحدث محتوى الصفحة عندما تتغير البيانات. بينما إن أحضرت البيانات من خلال المكوّن، ستجري العملية خلال زمن تركيب المكوّن ومن ثم يُحدّث محتوى المكوِّن عندما تتغير البيانات.

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

استخدام الخطاف useEffect في إحضار البيانات من جانب العميل

يعرض المثال التالي كيفية إحضار البيانات من جانب العميل باستخدام الخطاف useEffect:

function Profile() {
  const [data, setData] = useState(null)
  const [isLoading, setLoading] = useState(false)

  useEffect(() => {
    setLoading(true)
    fetch('api/profile-data')
      .then((res) => res.json())
      .then((data) => {
        setData(data)
        setLoading(false)
      })
  }, [])

  if (isLoading) return <p>Loading...</p>
  if (!data) return <p>No profile data</p>

  return (
    <div>
      <h1>{data.name}</h1>
      <p>{data.bio}</p>
    </div>
  )
}

إحضار البيانات من جانب العميل باستخدام المكتبة SWR

أنشأ فريق تطوير مكتبة من خطافات رياكت لإحضار البيانات تًدعى SWR، ويُنصح باستخدامها لإحضار البيانات من جانب العميل. تتعامل هذه المكتبة مع التخزين المؤقت وإعادة التحقق وتتبع تركيز الدخل وضبط الفواصل الزمنية لإعادة إحضار البيانات وغيرها الكثير.

سنستخدم في المثال التالي SWR في إحضار بيانات ملف شخصي، إذ تُخزِّن هذه المكتبة البيانات تلقائيًا وستعيد التحقق منها عندما تصبح قديمة.

import useSWR from 'swr'

const fetcher = (...args) => fetch(...args).then((res) => res.json())

function Profile() {
  const { data, error } = useSWR('/api/profile-data', fetcher)

  if (error) return <div>Failed to load</div>
  if (!data) return <div>Loading...</div>

  return (
    <div>
      <h1>{data.name}</h1>
      <p>{data.bio}</p>
    </div>
  )
}

المصادر

• صفحات Data Fetching في توثيق Next.js الرسمي.