موارد المطوّرين في قوالب Next.js: الأنواع والمكوّنات والأنماط والتوثيق

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

يستعرض هذا الدليل موارد المطوّرين والمزايا التقنية التي تأتي مع كل قالب مميز من Aniq UI، مستعينًا بـ Food Studio، قالب المطاعم المتكامل (full-stack) مثالًا تطبيقيًا. كل رقم في هذا المقال أُحصي مباشرةً من شيفرته المصدرية. وفي النهاية تجد قائمة تحقق يمكنك تطبيقها على أي قالب Next.js قبل شرائه.

المورد	ما تتضمنه الشيفرة	لماذا يوفّر الوقت
أنواع وواجهات TypeScript	TypeScript بالوضع الصارم، و600+ نوع مُصدَّر في الموقع ولوحة التحكم، واستجابة API مُعرَّفة النوع	تظهر الأخطاء في المحرّر لا في بيئة الإنتاج
بنية المكوّنات	مجلد لكل ميزة، يضم بداخله المكوّنات والـ hooks والأنواع والثوابت والدوال المساعدة	تعدّل شاشة واحدة دون المساس ببقية المشروع
أنماط الشيفرة	طريقة واحدة لجلب البيانات، وطريقة واحدة لبناء النماذج، وطريقة واحدة لحماية المسارات	تنسخ الشاشات الجديدة نمطًا مُجرَّبًا بدل أن تخترع نمطًا جديدًا
البدء السريع والتوثيق	دليل بدء سريع وملف .env.example لكل تطبيق، إضافةً إلى توثيق الميزات	يعمل المشروع محليًا من اليوم الأول
التصميم المتجاوب	تخطيطات للهاتف والجهاز اللوحي وسطح المكتب من مجموعة مكوّنات واحدة، وقائمة مخصّصة للهاتف، ومساحات لمس بحجم 44px	لا حاجة إلى صيانة نسخة منفصلة للهاتف
إمكانية الوصول	HTML دلالي، ونحو 670 سمة ARIA، وإطار تركيز واضح للوحة المفاتيح، ودعم تقليل الحركة	يستطيع مستخدمو لوحة المفاتيح وقارئات الشاشة الشراء واستخدام المنتج
الأداء	صور وخطوط محسّنة، وبيانات مخزّنة مؤقتًا، وبيانات وصفية (metadata) في كل مسار	صفحات سريعة تتصدّر نتائج البحث وتحقّق التحويلات

أنواع وواجهات TypeScript

كل تطبيق في القالب المميز مكتوب بلغة TypeScript مع "strict": true في ملف tsconfig.json الخاص به. يُفعّل الوضع الصارم الفحوص التي تلتقط الأخطاء المكلفة: القيم التي قد تكون null، والمعاملات التي لا نوع لها، والدوال التي لا تُرجع ما تَعِد به. (typescriptlang.org)

في Food Studio، يُصدِّر موقع الطلبات ولوحة تحكم الموظفين معًا أكثر من 600 نوع وواجهة: قائمة الطعام، والطبق وإضافاته، والسلة، والطلب وسجل حالاته، والعميل، والمطبخ، وإحصاءات لوحة التحكم. وتوجد هذه الأنواع بجوار الميزة التي تستخدمها، داخل مجلد types/، فيكون نوع نموذج إتمام الطلب بجانب النموذج نفسه.

وأكثرها فائدة هو شكل الاستجابة الذي يُرجعه كل استدعاء للـ API. يُكتب مرة واحدة ويُعاد استخدامه في كل استدعاء داخل التطبيق:

export interface ApiResponse<T = unknown> {
    success: boolean;
    data?: T;
    message?: string;
    errors?: Record<string, string[]>;
}

ولأن الاستجابة عامة (generic)، فإن استدعاء قائمة الطلبات يُرجع ApiResponse<Order[]>، واستدعاء طبق واحد يُرجع ApiResponse<Dish>. وعندما تضيف حقلًا إلى الطلب في الـ API، يُريك المحرّر كل شاشة تقرأ هذا الحقل. هذا هو المعنى العملي لعبارة «نماذج مُعرَّفة الأنواع، واستجابات API، وواجهات قابلة لإعادة الاستخدام»: عندما تغيّر الـ API، يُريك مدقق الأنواع كل شاشة يمسّها التغيير قبل أن يكتشفها أحد العملاء.

ما الذي تبحث عنه في أي قالب: تفعيل الوضع الصارم، وغياب any عن طبقة البيانات، ووجود أنواع لاستجابات الـ API وليس لخصائص (props) المكوّنات فقط.

بنية المكوّنات

يتكوّن موقع الطلبات في Food Studio من 23 مجلدًا للميزات (الصفحة الرئيسية، وقائمة الطعام، والسلة، وإتمام الطلب، وتتبّع الطلب، والحساب، والفروع، وغيرها)، ولكلٍّ منها البنية الداخلية نفسها:

features/checkout/
  components/   the UI pieces of this feature, one per file
  hooks/        its state and logic, one hook per file
  types/        the shapes it works with
  constants/    its fixed values (payment methods, page sizes)
  utils/        pure helpers, one job per file
  validation/   the form's schema
  index.ts      the feature's public exports

يقتصر دور ملف المسار في app/ على التركيب: يقرأ البيانات ثم يضع مكوّنات الميزة في أماكنها. أما اللبنات المشتركة (الأزرار، وحقول الإدخال، والنوافذ الحوارية، ومكوّن الصور) فموجودة مرة واحدة في components/ui وتستخدمها كل الميزات، لذا فإن أي تغيير في تصميم الأزرار ينعكس في كل مكان دفعة واحدة.

قراران يجعلان هذه البنية صامدة في العمل الإنتاجي الفعلي. الأول: مهمة واحدة لكل ملف، فالـ hook الذي يحمّل الطلبات لا يفتح نافذة حوارية أيضًا، وبذلك تستطيع استبدال أحدهما دون قراءة الآخر. والثاني: التنسيق عبر الرموز التصميمية (tokens) والخصائص المنطقية، فالألوان تأتي من متغيرات سمة معرّفة للسمتين الداكنة والفاتحة معًا، والمسافات تستخدم ms-* وme-* بدل اليسار واليمين، ولهذا يعمل التخطيط العربي من اليمين إلى اليسار دون ملف أنماط ثانٍ. يترك Next.js تنظيم المشروع لك، فهذه البنية قرار اتخذه القالب نيابةً عنك. (nextjs.org)

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

مقتطفات الشيفرة والأنماط

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

جلب البيانات

يمرّ كل استدعاء للخادم عبر سلسلة واحدة. استدعاء نقطة النهاية (endpoint) موجود في lib/api ويُرجع ApiResponse، ثم يغلّفه hook من TanStack Query داخل services/ بالتخزين المؤقت وحالتي التحميل والخطأ، ثم تستهلك الميزة هذا الـ hook. لا تستدعي أي شاشة fetch بنفسها. في Food Studio، يستخدم نحو 140 ملفًا طبقة الاستعلامات والتعديلات (mutations) هذه، لذا يتصرّف التحميل وإعادة الجلب وإبطال التخزين المؤقت بالطريقة نفسها في كل صفحة. (tanstack.com)

النماذج والتحقق من صحتها

تُبنى النماذج باستخدام React Hook Form ويُتحقَّق منها بمخطط Zod، وتأتي رسائل الخطأ في المخطط من ملفات الترجمة، فيتحدث التحقق بالإنجليزية أو بالعربية مثل بقية الصفحة. وتحمل الحقول الإلزامية علامة نجمة حمراء يرسمها حقل الإدخال المشترك، وتبقى متوافقة دائمًا مع المخطط. (react-hook-form.com)

المصادقة والأدوار

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

مسارات الواجهة الشائعة

هياكل التحميل (skeletons)، ونوافذ التأكيد، وترقيم الصفحات، وأشرطة التنبيه، والحالات الفارغة، لكلٍّ منها مكوّن واحد قابل لإعادة الاستخدام، لذا تبدأ أي قائمة جديدة أو أي نموذج جديد بكل حالاته، لا بالمسار المثالي وحده.

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

البدء السريع والتوثيق

يأتي كل قالب مميز مع دليل بدء سريع للمشروع كله، ودليل آخر لكل تطبيق بداخله. في Food Studio أربعة أدلة: واحد في جذر المشروع، وواحد لكلٍّ من موقع الطلبات ولوحة تحكم الموظفين والـ API. يسرد كل دليل المتطلبات المسبقة (Node.js 24 وYarn 4)، والمنافذ التي تعمل عليها التطبيقات، وأوامر التثبيت وتعبئة البيانات الأولية والتشغيل، ومتغيرات البيئة التي يجب أن تتطابق بين التطبيقات.

ويأتي كل تطبيق أيضًا بملف .env.example يضم كل متغير يقرؤه، مع تعليق يوضّح الغرض منه، فتنسخ ملفًا واحدًا وتملأ مفاتيحك الخاصة بدل قراءة الشيفرة المصدرية للعثور عليها. ونسخة الـ API توثّق المدفوعات والبريد الإلكتروني ومزوّدي الذكاء الاصطناعي وقاعدة البيانات في مكان واحد.

وإلى جانب أدلة الإعداد، يضم القالب توثيقًا للميزات: ملف README لكل تطبيق يصف بنيته، ودليلًا للهوية البصرية لتغيير الشعار والألوان والخطوط، وتوثيقًا لوحدات الـ API. وتأتي الـ API مع أداة تعبئة (seeder) تعمل بأمر واحد وتملأ قاعدة البيانات بمطعم تجريبي متكامل، فتُفتح لوحة التحكم على بيانات تبدو حقيقية منذ أول تشغيل.

ما الذي تبحث عنه في أي قالب: انسخ المستودع (clone) وقِس الوقت اللازم لرؤية لوحة التحكم ببياناتها. إن كانت الإجابة تتوقف على قراءة الشيفرة المصدرية، فالتوثيق لم يكتمل بعد.

التصميم المتجاوب

تُبنى كل شاشة في القالب المميز مرة واحدة وتتكيّف مع العرض الذي تظهر عليه: الهاتف والجهاز اللوحي وسطح المكتب. في موقع الطلبات في Food Studio، تحدّد نحو 450 فئة متجاوبة (responsive classes) من Tailwind CSS (sm: وmd: وlg:) كيف يتغيّر التخطيط كلما اتسعت الشاشة، فتنتقل قائمة الطعام من عمود واحد على الهاتف إلى شبكة على سطح المكتب دون مجموعة ثانية من المكوّنات. (tailwindcss.com)

تحت نقطة التوقف (breakpoint) الخاصة بسطح المكتب، يتحوّل شريط التنقل إلى زر قائمة يفتح قائمة كاملة ويُعلن حالته عبر aria-expanded. وتنزلق الأدراج الجانبية من الحافة التي يبدأ منها اتجاه القراءة، فتنعكس في العربية. وعلى الشاشات اللمسية، لا يقل ارتفاع الأزرار والروابط عن 44 بكسل، وتترك العناصر المثبّتة أسفل الشاشة مساحة لمؤشر الشاشة الرئيسية في الهاتف عبر env(safe-area-inset-bottom).

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

إمكانية الوصول

إمكانية الوصول مدمجة في المكوّنات المشتركة، فترثها كل شاشة تستخدمها. وفي موقع Food Studio ولوحة تحكمه معًا نحو 670 سمة ARIA و146 دورًا صريحًا (role): أزرار أيقونات ذات تسميات، وقوائم تُعلن ما إذا كانت مفتوحة، ومناطق حيّة (live regions) تقرأ رسائل الحالة بصوت مسموع.

يحصل مستخدمو لوحة المفاتيح على إطار تركيز واحد واضح ترسمه قاعدة عامة واحدة هي :focus-visible، فيظهر عند التنقل بمفتاح Tab ولا يظهر أبدًا عند النقر بالفأرة. وتحمل الحقول الإلزامية علامة نجمة حمراء مخفية عن قارئات الشاشة، لأن ما تُعلنه هذه القارئات هو سمة required في الحقل نفسه، ويُوسَم الحقل الذي يحتوي على خطأ بـ aria-invalid ويُشير إلى رسالة الخطأ الخاصة به. وتضبط الصفحة سمتي lang وdir وفق اللغة النشطة، وتحترم الحركات إعداد تقليل الحركة. (w3.org)

ما الذي تبحث عنه في أي قالب: ضع الفأرة جانبًا وأنجز مهمة حقيقية واحدة، مثل تسجيل الدخول أو تقديم طلب، باستخدام لوحة المفاتيح وحدها.

الأداء

تأتي سرعة القالب من بضعة قرارات مطبّقة في كل مكان. تُحمَّل الخطوط عبر next/font، فيظهر النص دون وميض بخط غير صحيح. وتمرّ الصور عبر next/image في 45 ملفًا، يُعرّف 30 منها الخاصية sizes، فيُنزّل الهاتف صورة بحجم الهاتف بدل صورة مخصّصة لسطح المكتب. (nextjs.org)

تُخزَّن البيانات مؤقتًا عبر TanStack Query، مع مدة صلاحية (stale time) محدّدة لكل استعلام في طبقة الخدمات، فيُعاد استخدام ما حُمِّل سابقًا عند التنقل بين الصفحات بدل جلبه من جديد. ويُصدّر كل مسار بياناته الوصفية الخاصة (العنوان والوصف وصورة المشاركة على الشبكات الاجتماعية)، ويأتي الموقع مع ملف sitemap وملف robots مُولَّدين، فتكون الصفحات السريعة التحميل هي نفسها الصفحات التي تستطيع محركات البحث قراءتها.

ما الذي تبحث عنه في أي قالب: شغّل Lighthouse على أثقل صفحة في العرض التجريبي، وغالبًا ما تكون صفحة منتج أو صفحة في لوحة التحكم، لا على الصفحة الرئيسية، وانظر إلى أحجام الصور التي يُبلغ عنها. (developer.chrome.com)

كيف تفحص موارد المطوّرين في أي قالب قبل شرائه

1. شغّل مدقق الأنواع. يجب أن ينجح tsc --noEmit مع تفعيل الوضع الصارم.
2. افتح طبقة البيانات. ابحث عن شكل استجابة واحد مُعرَّف النوع، ومكان واحد تنطلق منه الاستدعاءات إلى الخادم.
3. قارن ثلاث ميزات. يجب أن تشترك في بنية المجلدات نفسها.
4. اقرأ نموذجًا واحدًا. يجب أن يأتي التحقق من مخطط، لا من فحوص مكتوبة يدويًا.
5. ابحث عن ملف مثال البيئة. يجب أن يكون كل متغير يقرؤه التطبيق مُدرجًا ومشروحًا.
6. اتبع دليل البدء السريع. يجب أن تصل إلى لوحة تحكم تعمل ببياناتها دون الحاجة إلى سؤال المؤلف.
7. تحقّق من اللغة الثانية. إن كنت تحتاج إلى العربية أو إلى لغة أخرى تُكتب من اليمين إلى اليسار، فيجب أن ينعكس التخطيط دون ملف أنماط منفصل.

الأسئلة الشائعة

هل تتضمن جميع قوالب Aniq UI موارد المطوّرين هذه؟

كل قالب مميز مكتوب بـ TypeScript في الوضع الصارم، بالبنية نفسها القائمة على مجلدات الميزات، والأنماط نفسها للبيانات والنماذج، ومع دليل بدء سريع وأمثلة لمتغيرات البيئة. وتضيف القوالب المتكاملة (full-stack) توثيق الـ API وأداة لتعبئة قاعدة البيانات. يتناول هذا الدليل القوالب المميزة، أما القوالب المجانية فمفتوحة المصدر، ويصف ملف README في مستودع كلٍّ منها ما يتضمنه.

هل توجد مكتبة مقتطفات منفصلة للتنزيل؟

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

هل يمكنني استخدام الواجهة الأمامية دون الواجهة الخلفية؟

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

ما إصدار Next.js الذي تستخدمه القوالب؟

القوالب المميزة الحالية مبنية على Next.js 16 مع App Router، وReact 19، وTailwind CSS 4، وTypeScript 5.9.

هل القوالب جاهزة للعربية وللتخطيطات من اليمين إلى اليسار؟

نعم. تأتي القوالب بالإنجليزية والعربية، ولأن المسافات تستخدم الخصائص المنطقية، ينعكس التخطيط العربي تلقائيًا.

الخاتمة

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

تصفّح قوالب Next.js المتكاملة مع الواجهة الخلفية لترى هذه الموارد في منتجات كاملة، أو قارن جميع القوالب في صفحة القوالب.