Streaming و Suspense في Next.js 16: دلي…

دعني أبدأ بسؤال صريح: هل سبق وأن انتظرت 4 ثوانٍ كاملة لتظهر صفحة لوحة التحكم بسبب استعلام واحد بطيء؟ أنا شخصياً عشت هذا الكابوس مرات لا تُحصى قبل أن أتعمق في التدفق (Streaming) في Next.js. والصراحة، بعد أن استوعبت هذا المفهوم، تغيّرت طريقة بنائي للتطبيقات تماماً.

في Next.js 16، لم يعد التدفق ميزة جانبية - إنه ركيزة أساسية. بدلاً من انتظار اكتمال جميع عمليات جلب البيانات قبل عرض الصفحة، يسمح لك التدفق بإرسال أجزاء من واجهة المستخدم إلى المتصفح فور جاهزيتها. في هذا الدليل العملي، سنستكشف كيفية استخدام loading.tsx و <Suspense> معاً لتحقيق أداء استثنائي مع توفير تجربة مستخدم سلسة.

سنركز على الأنماط المعتمدة في Next.js 16.2 (الإصدار الحالي في أبريل 2026) ونوضح كيف يتكامل التدفق مع التخزين المؤقت و Cache Components التي تناولناها سابقاً.

ما هو التدفق ولماذا يهم؟

في النموذج التقليدي للعرض من جانب الخادم (SSR)، يجب أن تكتمل جميع عمليات جلب البيانات على الخادم قبل إرسال HTML إلى المتصفح. والنتيجة؟ أبطأ استعلام قاعدة بيانات يحدد سرعة ظهور الصفحة بالكامل. مزعج، أليس كذلك؟

التدفق يحل هذه المشكلة جذرياً:

القشرة الثابتة (Static Shell): يتم إرسال التخطيط والتنقل وحدود Suspense فوراً.
المحتوى الديناميكي: يُبَث تدريجياً عبر نفس استجابة HTTP بمجرد جاهزيته.
زمن وصول البايت الأول (TTFB): ينخفض دراماتيكياً، حيث يبدأ المستخدم برؤية المحتوى في أقل من 200 مللي ثانية حتى مع استعلامات قاعدة بيانات بطيئة.

في Next.js 16، أصبح كل الكود ديناميكياً افتراضياً، ويمكنك إدخال أجزاء معينة في التخزين المؤقت باستخدام توجيه "use cache". وهذا التحول يجعل التدفق أكثر أهمية من أي وقت مضى - إنه الآلية الرئيسية التي ستعتمد عليها لتحسين الأداء.

طريقتان لتنفيذ التدفق في Next.js 16

هناك طريقتان رئيسيتان، وكل واحدة منهما لها حالات استخدام مختلفة:

على مستوى الصفحة: باستخدام ملف loading.tsx الذي ينشئ حد <Suspense> تلقائياً حول محتوى الصفحة.
على مستوى المكون: باستخدام <Suspense> يدوياً لتحكم دقيق في أي جزء يبث بشكل مستقل.

نصيحتي الشخصية: ابدأ بالطريقة الأولى لأنها أبسط، ثم تدرج إلى الثانية عندما تحتاج تحكماً أدق.

استخدام loading.tsx: الطريقة الأبسط للتدفق

أبسط طريقة لإضافة التدفق هي إنشاء ملف loading.tsx بجوار ملف page.tsx. سيقوم Next.js تلقائياً بلف محتوى الصفحة في حد <Suspense> ويستخدم مكون التحميل كـ fallback:

// app/dashboard/loading.tsx
export default function Loading() {
  return (
    <div className="space-y-4 p-6">
      <div className="h-8 w-1/3 bg-gray-200 rounded animate-pulse" />
      <div className="grid grid-cols-3 gap-4">
        {[...Array(6)].map((_, i) => (
          <div key={i} className="h-32 bg-gray-200 rounded animate-pulse" />
        ))}
      </div>
    </div>
  );
}

كيف يعمل loading.tsx تحت الغطاء؟

عندما يضع Next.js ملف loading.tsx في مسار، فإنه يلف محتوى page.tsx تلقائياً كالتالي:

// تخيل ما يفعله Next.js داخلياً
<Layout>
  <Suspense fallback={<Loading />}>
    <Page />
  </Suspense>
</Layout>

يعني هذا أن التخطيط والتنقل يظهران فوراً، بينما يُعرض هيكل التحميل (skeleton) في مكان محتوى الصفحة حتى تكتمل عمليات جلب البيانات. بساطة قاتلة، لكنها فعّالة.

استخدام Suspense على مستوى المكون: التحكم الدقيق

على الرغم من أن loading.tsx يعمل بشكل جيد للهياكل العامة، إلا أن استخدام <Suspense> بشكل دقيق يمنحك تحكماً أفضل بكثير. القاعدة الذهبية التي تعلمتها بالطريقة الصعبة: كل مكون غير متزامن يجلب بياناته الخاصة يجب أن يكون داخل حد Suspense منفصل.

// app/dashboard/page.tsx
import { Suspense } from 'react';
import { UserStats } from './user-stats';
import { RecentOrders } from './recent-orders';
import { Analytics } from './analytics';
import { StatsSkeleton, OrdersSkeleton, AnalyticsSkeleton } from './skeletons';

export default function DashboardPage() {
  return (
    <div className="grid grid-cols-1 lg:grid-cols-3 gap-6 p-6">
      <h1 className="col-span-3 text-2xl font-bold">لوحة التحكم</h1>

      <Suspense fallback={<StatsSkeleton />}>
        <UserStats />
      </Suspense>

      <Suspense fallback={<OrdersSkeleton />}>
        <RecentOrders />
      </Suspense>

      <Suspense fallback={<AnalyticsSkeleton />}>
        <Analytics />
      </Suspense>
    </div>
  );
}

كل من UserStats و RecentOrders و Analytics يجلب بياناته بشكل مستقل ويبث إلى المتصفح بمجرد جاهزيته، دون انتظار الآخرين. تخيل السيناريو: إذا استغرق Analytics 3 ثوانٍ بينما UserStats يحتاج 200 مللي ثانية فقط، فسيرى المستخدم الإحصائيات فوراً. هذا فرق ملموس في تجربة المستخدم.

نقل جلب البيانات إلى المكون نفسه

للاستفادة الكاملة من Suspense، انقل عمليات جلب البيانات داخل المكونات التي تحتاجها بدلاً من جلبها على مستوى الصفحة:

// app/dashboard/user-stats.tsx
import { db } from '@/lib/db';

export async function UserStats() {
  // محاكاة استعلام قاعدة بيانات بطيء
  const stats = await db.users.aggregate({
    _count: { id: true },
    _avg: { lifetimeValue: true },
  });

  return (
    <div className="bg-white p-6 rounded-lg shadow">
      <h3 className="text-lg font-semibold mb-4">إحصائيات المستخدمين</h3>
      <p>إجمالي المستخدمين: {stats._count.id}</p>
      <p>متوسط القيمة الدائمة: {stats._avg.lifetimeValue}</p>
    </div>
  );
}

تصميم هياكل التحميل (Skeletons) الفعالة

الـ skeleton السيئ يدمر تجربة المستخدم تماماً، حتى لو كان التدفق يعمل بشكل مثالي. صدقني، رأيت تطبيقات بأداء ممتاز تقنياً لكن بـ skeletons كارثية تجعل المستخدمين يهربون. اتبع هذه القواعد لتصميم skeletons احترافية:

1. مطابقة الأبعاد بدقة

يجب أن تطابق أبعاد الـ skeleton أبعاد المحتوى النهائي بدقة لمنع تحول التخطيط التراكمي (CLS). إذا كان لديك بطاقة بارتفاع 200 بكسل، يجب أن يكون الـ skeleton بنفس الارتفاع تماماً:

// app/components/skeletons.tsx
export function ProductCardSkeleton() {
  return (
    <div className="border rounded-lg overflow-hidden">
      {/* صورة بنفس نسبة العرض إلى الارتفاع للمنتج */}
      <div className="aspect-square bg-gray-200 animate-pulse" />
      <div className="p-4 space-y-2">
        <div className="h-5 w-3/4 bg-gray-200 rounded animate-pulse" />
        <div className="h-4 w-1/2 bg-gray-200 rounded animate-pulse" />
        <div className="h-6 w-1/3 bg-gray-300 rounded animate-pulse" />
      </div>
    </div>
  );
}

2. استخدم hooks لتحديد الأبعاد بناءً على البيانات المعروفة

إذا كنت تعرف عدد العناصر المتوقعة (مثلاً من معامل limit في URL)، اعرض نفس العدد في الـ skeleton:

export function ProductGridSkeleton({ count = 12 }: { count?: number }) {
  return (
    <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
      {[...Array(count)].map((_, i) => (
        <ProductCardSkeleton key={i} />
      ))}
    </div>
  );
}

المسارات الديناميكية: حل مشكلة الـ key

هذه واحدة من أكثر المشاكل المحيرة في Next.js - وأنا اعترف أنني قضيت ساعات أحاول فهم سببها قبل أن أصل إلى الحل. عند الانتقال بين معاملات ديناميكية (مثل /products/1 إلى /products/2)، قد لا يظهر loading.tsx مرة أخرى. السبب؟ React يرى أن نوع المكون لم يتغير، فيعيد استخدام نفس النسخة ويحدّث الـ props فقط، دون تشغيل Suspense.

الحل: استخدام prop الـ key

أضف key إلى Suspense يحتوي على المعامل الديناميكي:

// app/products/[id]/page.tsx
import { Suspense } from 'react';
import { ProductDetails } from './product-details';
import { ProductSkeleton } from './skeleton';

export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;

  return (
    <Suspense key={id} fallback={<ProductSkeleton />}>
      <ProductDetails id={id} />
    </Suspense>
  );
}

الآن في كل مرة يتغير فيها معرف المنتج، سيُعاد إنشاء Suspense ويظهر الـ skeleton أثناء جلب بيانات المنتج الجديد. نفس النمط ينطبق على searchParams:

const params = await searchParams;
const queryKey = JSON.stringify(params);

return (
  <Suspense key={queryKey} fallback={<SearchSkeleton />}>
    <SearchResults filters={params} />
  </Suspense>
);

التدفق المتوازي مقابل التسلسلي

هنا تكمن أحد أكبر مكاسب الأداء، ومن المؤسف أن كثيرين يخطئون فيه. الحالة الأولى (سيئة): جلب متسلسل يلغي فائدة التدفق:

// ❌ سيئ: انتظار متسلسل
async function Dashboard() {
  const user = await getUser();
  const orders = await getOrders(user.id);
  const recommendations = await getRecommendations(user.id);

  return <DashboardView {...{ user, orders, recommendations }} />;
}

الحالة الثانية (جيدة): مكونات منفصلة، كل منها مع حد Suspense خاص به:

// ✅ جيد: تدفق متوازي حقيقي
export default function Dashboard() {
  return (
    <>
      <Suspense fallback={<UserSkeleton />}>
        <UserSection />
      </Suspense>
      <Suspense fallback={<OrdersSkeleton />}>
        <OrdersSection />
      </Suspense>
      <Suspense fallback={<RecommendationsSkeleton />}>
        <RecommendationsSection />
      </Suspense>
    </>
  );
}

كل قسم يبدأ جلب بياناته بشكل مستقل، ويبث إلى المتصفح بمجرد جاهزيته. هذا هو التحسين الحقيقي للأداء - وليس مجرد وعد تسويقي.

دمج Suspense مع Error Boundaries

التدفق وحده لا يكفي - تحتاج إلى التعامل مع الأخطاء بأناقة. اجمع <Suspense> مع error.tsx أو Error Boundary مخصص:

// app/dashboard/error.tsx
'use client';

export default function Error({
  error,
  reset,
}: {
  error: Error;
  reset: () => void;
}) {
  return (
    <div className="p-6 bg-red-50 border border-red-200 rounded-lg">
      <h2 className="text-red-800 font-semibold">حدث خطأ</h2>
      <p className="text-red-600 mt-2">{error.message}</p>
      <button
        onClick={reset}
        className="mt-4 px-4 py-2 bg-red-600 text-white rounded"
      >
        إعادة المحاولة
      </button>
    </div>
  );
}

للتحكم الأدق، يمكنك لف مكونات معينة بـ Error Boundary مخصص:

import { ErrorBoundary } from 'react-error-boundary';

<ErrorBoundary fallback={<OrdersErrorState />}>
  <Suspense fallback={<OrdersSkeleton />}>
    <RecentOrders />
  </Suspense>
</ErrorBoundary>

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

notFound() و رموز حالة HTTP الصحيحة

هناك تفصيل مهم يفوته كثير من المطورين (وأنا أيضاً وقعت فيه في البداية): بمجرد أن يبدأ التدفق - أي بمجرد عرض fallback - لا يمكن لـ Next.js تغيير رمز حالة HTTP. يعني هذا أن استدعاء notFound() بعد عرض Suspense سيعطي 200 OK بدلاً من 404. كارثة لـ SEO!

القاعدة: ضع notFound() دائماً قبل أي await أو حد Suspense:

import { notFound } from 'next/navigation';

export default async function ProductPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;

  // ✅ تحقق صحة الإدخال أولاً
  if (!isValidSlug(slug)) {
    notFound();
  }

  // ✅ تحقق وجود المورد قبل التدفق
  const exists = await checkProductExists(slug);
  if (!exists) {
    notFound();
  }

  // الآن ابدأ التدفق
  return (
    <Suspense fallback={<ProductSkeleton />}>
      <ProductDetails slug={slug} />
    </Suspense>
  );
}

التكامل مع Cache Components في Next.js 16

التدفق يصبح أقوى بكثير عندما يقترن بـ Cache Components. يمكنك خلط محتوى مخزّن مؤقتاً (سريع) مع محتوى ديناميكي (يبث) في نفس الصفحة:

// app/products/[id]/page.tsx
import { Suspense } from 'react';

// مكون مخزّن مؤقتاً - يُقدَّم فوراً
async function ProductDescription({ id }: { id: string }) {
  'use cache';
  const product = await fetchProduct(id);
  return (
    <div>
      <h1>{product.title}</h1>
      <p>{product.description}</p>
    </div>
  );
}

// مكون ديناميكي - يبث للمستخدم الحالي
async function PersonalizedRecommendations({ id }: { id: string }) {
  const recs = await fetchRecommendations(id);
  return <RecommendationsList items={recs} />;
}

export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;

  return (
    <>
      {/* محتوى ثابت يُقدَّم فوراً */}
      <ProductDescription id={id} />

      {/* محتوى ديناميكي يبث */}
      <Suspense fallback={<RecommendationsSkeleton />}>
        <PersonalizedRecommendations id={id} />
      </Suspense>
    </>
  );
}

هذا النمط يجمع بين سرعة الصفحات الثابتة وحيوية المحتوى الشخصي. وهذا، بصراحة، هو جوهر Partial Prerendering في Next.js 16 - أحد أكثر الأشياء التي أحبها في الإصدار الجديد.

قياس تأثير الأداء

كيف تتأكد أن التدفق يعمل فعلاً؟ المقاييس التالية، باستخدام Chrome DevTools و Web Vitals، ستجيب على هذا السؤال:

TTFB (Time to First Byte): يجب أن يكون أقل من 200 مللي ثانية. التدفق لا يحسن TTFB مباشرة، لكنه يقلل وقت ظهور أول محتوى ذي معنى.
FCP (First Contentful Paint): يجب أن يحدث بسرعة بمجرد وصول قشرة HTML الثابتة.
LCP (Largest Contentful Paint): يعتمد على ما إذا كان أكبر عنصر داخل أو خارج حد Suspense.
CLS (Cumulative Layout Shift): يجب أن يكون صفر إذا كانت skeletons لديك بأبعاد صحيحة.

افتح علامة تبويب Network في DevTools واضبط Throttling على "Slow 3G". يجب أن ترى الـ HTML يصل بشكل تدريجي - وليس كقطعة واحدة. إذا لم تر هذا التدفق التدريجي، فأنت أمام مشكلة في التكوين.

أخطاء شائعة يجب تجنبها

1. وضع await قبل Suspense

إذا كانت الصفحة تنتظر بيانات قبل عرض أي شيء، فالتدفق لا يحدث - بكل بساطة:

// ❌ سيئ: التدفق معطّل
export default async function Page() {
  const data = await slowFetch(); // الصفحة تنتظر هذا قبل أي شيء

  return (
    <Suspense fallback={<Loading />}>
      <Content data={data} />
    </Suspense>
  );
}

الحل: انقل الـ await داخل المكون المغلف بـ Suspense.

2. وضع Suspense منخفضاً جداً في الشجرة

إذا كان كل شيء داخل Suspense واحد كبير، فأنت لا تحصل على فائدة التدفق المتوازي. قسّم إلى حدود متعددة - كلما زاد التقسيم، كلما تحسنت تجربة المستخدم.

3. تجاهل CLS عند تصميم skeletons

skeleton صغير ينفجر إلى محتوى كبير = تجربة مستخدم سيئة و CLS أعلى من 0.1 (يفشل Core Web Vitals). أحد أصعب الدروس التي تعلمتها.

4. نسيان key على Suspense للمسارات الديناميكية

كما ذكرنا أعلاه، هذا يسبب انتقالات بطيئة بين المسارات الديناميكية بدون عرض حالة التحميل.

متى لا تستخدم التدفق؟

التدفق ليس الحل لكل شيء (وأي شخص يقول لك العكس فهو يبالغ). تجنبه في هذه الحالات:

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

الأسئلة الشائعة (FAQ)

ما الفرق بين loading.tsx و Suspense؟

loading.tsx ملف اتفاقي (convention) يلف صفحتك تلقائياً بحد <Suspense> واحد على مستوى المسار. أما <Suspense> فيمكنك استخدامه يدوياً حول أي مكون لتحكم دقيق. استخدم loading.tsx للهيكل العام، و <Suspense> للأقسام الفردية.

هل التدفق يعمل مع Server Components فقط؟

نعم، التدفق في Next.js مصمم أساساً لـ React Server Components غير المتزامنة. مكونات العميل (Client Components) لا تستخدم Suspense بنفس الطريقة لأنها تعمل في المتصفح. لكن يمكنك دمج كليهما: مكون خادم ديناميكي داخل Suspense يُبث ثم يُهَدرت كأي مكون آخر.

كيف أتعامل مع 404 عند استخدام التدفق؟

استدعِ notFound() دائماً قبل أي await أو حد <Suspense> في الصفحة. بمجرد بدء التدفق، يصبح من المستحيل إرسال رمز حالة 404 إلى المتصفح، وستحصل على 200 OK مع صفحة فارغة.

هل التدفق يحسّن SEO؟

نعم بشكل عام. Googlebot يرى المحتوى المُدفق بشكل صحيح ويفهرسه. الأهم أن التدفق يحسّن Core Web Vitals (خاصة LCP) التي تؤثر على ترتيب البحث. تأكد فقط من أن المحتوى المهم لـ SEO (مثل العنوان والوصف الميتا) موجود في القشرة الثابتة وليس داخل Suspense.

هل أحتاج إلى تكوين خاص لتفعيل التدفق في Next.js 16؟

لا. التدفق مفعّل افتراضياً في Next.js 13+ مع App Router. لا حاجة لأي إعداد في next.config.ts. كل ما عليك فعله هو استخدام loading.tsx أو <Suspense> حول مكوناتك غير المتزامنة. لاحظ أن Next.js 16 جعل كل الكود ديناميكياً افتراضياً، مما يجعل التدفق أكثر أهمية من أي وقت مضى.

الخلاصة

التدفق و Suspense ليسا مجرد ميزات متقدمة - إنهما الأساس الذي يُبنى عليه الأداء العالي في Next.js 16. ابدأ بإضافة loading.tsx لكل مسار مهم، ثم تدرج إلى حدود <Suspense> الدقيقة لكل مكون يجلب بيانات. اقرن هذا مع Cache Components للحصول على أفضل ما في العالمين: محتوى ثابت سريع ومحتوى ديناميكي حي.

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