هيكل المشروع وتنظيمه

توفر هذه الصفحة نظرة عامة على جميع اصطلاحات المجلدات والملفات في Next.js، وتوصيات لتنظيم مشروعك.

اصطلاحات المجلدات والملفات

مجلدات المستوى الأعلى

تُستخدم مجلدات المستوى الأعلى لتنظيم كود التطبيق والأصول الثابتة.


`app`	موجه التطبيق (App Router)
`pages`	موجه الصفحات (Pages Router)
`public`	الأصول الثابتة التي سيتم تقديمها
`src`	مجلد مصدر التطبيق الاختياري

ملفات المستوى الأعلى

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


Next.js
`next.config.js`	ملف تكوين Next.js
`package.json`	تبعيات المشروع والنصوص البرمجية
`instrumentation.ts`	ملف OpenTelemetry والأدوات (Instrumentation)
`middleware.ts`	وسيط طلبات Next.js
`.env`	متغيرات البيئة
`.env.local`	متغيرات البيئة المحلية
`.env.production`	متغيرات بيئة الإنتاج
`.env.development`	متغيرات بيئة التطوير
`.eslintrc.json`	ملف تكوين ESLint
`.gitignore`	ملفات ومجلدات Git لتجاهلها
`next-env.d.ts`	ملف تعريف TypeScript لـ Next.js
`tsconfig.json`	ملف تكوين TypeScript
`jsconfig.json`	ملف تكوين JavaScript

ملفات التوجيه (Routing)


`layout`	`.js` `.jsx` `.tsx`	التخطيط (Layout)
`page`	`.js` `.jsx` `.tsx`	الصفحة (Page)
`loading`	`.js` `.jsx` `.tsx`	واجهة التحميل (Loading UI)
`not-found`	`.js` `.jsx` `.tsx`	واجهة غير موجود (Not found UI)
`error`	`.js` `.jsx` `.tsx`	واجهة الخطأ (Error UI)
`global-error`	`.js` `.jsx` `.tsx`	واجهة الخطأ العامة (Global error UI)
`route`	`.js` `.ts`	نقطة نهاية API
`template`	`.js` `.jsx` `.tsx`	التخطيط المعاد تصييره
`default`	`.js` `.jsx` `.tsx`	صفحة الاحتياطي للطرق المتوازية

الطرق المتداخلة (Nested routes)


`folder`	مقطع الطريق (Route segment)
`folder/folder`	مقطع طريق متداخل (Nested route segment)

الطرق الديناميكية (Dynamic routes)


`[folder]`	مقطع طريق ديناميكي
`[...folder]`	مقطع طريق شامل (Catch-all)
`[[...folder]]`	مقطع طريق شامل اختياري

مجموعات الطرق والمجلدات الخاصة


`(folder)`	تجميع الطرق دون التأثير على التوجيه
`_folder`	استبعاد المجلد وجميع المقاطع الفرعية من التوجيه

الطرق المتوازية والمقاطعة (Parallel and Intercepted Routes)


`@folder`	فتحة مسماة (Named slot)
`(.)folder`	اعتراض نفس المستوى
`(..)folder`	اعتراض مستوى واحد أعلى
`(..)(..)folder`	اعتراض مستويين أعلى
`(...)folder`	اعتراض من الجذر (root)

اصطلاحات ملفات البيانات الوصفية (Metadata)

أيقونات التطبيق


`favicon`	`.ico`	ملف الأيقونة المفضلة (Favicon)
`icon`	`.ico` `.jpg` `.jpeg` `.png` `.svg`	ملف أيقونة التطبيق
`icon`	`.js` `.ts` `.tsx`	أيقونة التطبيق المولدة
`apple-icon`	`.jpg` `.jpeg`, `.png`	ملف أيقونة Apple
`apple-icon`	`.js` `.ts` `.tsx`	أيقونة Apple المولدة

صور Open Graph و Twitter


`opengraph-image`	`.jpg` `.jpeg` `.png` `.gif`	ملف صورة Open Graph
`opengraph-image`	`.js` `.ts` `.tsx`	صورة Open Graph المولدة
`twitter-image`	`.jpg` `.jpeg` `.png` `.gif`	ملف صورة Twitter
`twitter-image`	`.js` `.ts` `.tsx`	صورة Twitter المولدة

تحسين محركات البحث (SEO)


`sitemap`	`.xml`	ملف خريطة الموقع (Sitemap)
`sitemap`	`.js` `.ts`	خريطة الموقع المولدة
`robots`	`.txt`	ملف robots.txt
`robots`	`.js` `.ts`	ملف robots المولد

تنظيم مشروعك

Next.js غير متحيز بشأن كيفية تنظيم وترتيب ملفات مشروعك. ولكنه يوفر عدة ميزات لمساعدتك في تنظيم مشروعك.

تسلسل المكونات (Component hierarchy)

يتم عرض المكونات المحددة في الملفات الخاصة بتسلسل محدد:

layout.js
template.js
error.js (حدود خطأ React)
loading.js (حدود تعليق React)
not-found.js (حدود خطأ React)
page.js أو layout.js متداخل

Component Hierarchy for File Conventions

يتم عرض المكونات بشكل متكرر في الطرق المتداخلة، مما يعني أن مكونات مقطع الطريق ستكون متداخلة داخل مكونات المقطع الأب.

Nested File Conventions Component Hierarchy

التنسيق المكاني (Colocation)

في دليل app، تحدد المجلدات المتداخلة بنية المسار (route). كل مجلد يمثل جزءًا من المسار (route segment) يتم تعيينه إلى جزء مقابل في مسار URL.

ومع ذلك، على الرغم من أن بنية المسار تُحدد من خلال المجلدات، إلا أن المسار غير متاح للجمهور حتى يتم إضافة ملف page.js أو route.js إلى جزء المسار.

مخطط يوضح كيف أن المسار غير متاح للجمهور حتى يتم إضافة ملف page.js أو route.js إلى جزء المسار.

وحتى عندما يصبح المسار متاحًا للجمهور، فإن المحتوى المُعاد فقط من خلال page.js أو route.js هو الذي يتم إرساله إلى العميل.

مخطط يوضح كيف أن ملفات page.js و route.js تجعل المسارات متاحة للجمهور.

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

مخطط يوضح أن ملفات المشروع المنسقة مكانيًا ليست قابلة للتوجيه حتى عندما يحتوي الجزء على ملف page.js أو route.js.

معلومة مفيدة: بينما يمكنك تنسيق ملفات مشروعك في app، إلا أنك لست مضطرًا لذلك. إذا كنت تفضل، يمكنك إبقاؤها خارج دليل app.

المجلدات الخاصة (Private Folders)

يمكن إنشاء مجلدات خاصة عن طريق إضافة شرطة سفلية كبادئة لاسم المجلد: _folderName

هذا يشير إلى أن المجلد هو تفاصيل تنفيذ خاصة ولا يجب أن تؤخذ بعين الاعتبار من قبل نظام التوجيه، مما يستثني المجلد وجميع مجلداته الفرعية من التوجيه.

مثال على هيكل مجلدات باستخدام المجلدات الخاصة

بما أن الملفات في دليل app يمكن تنسيقها بأمان افتراضيًا، فإن المجلدات الخاصة ليست مطلوبة للتنسيق المكاني. ومع ذلك، يمكن أن تكون مفيدة لـ:

فصل منطق واجهة المستخدم عن منطق التوجيه.
تنظيم الملفات الداخلية بشكل متسق عبر المشروع وبيئة Next.js.
فرز وتجميع الملفات في محررات الأكواد.
تجنب التعارضات المحتملة في التسمية مع اصطلاحات ملفات Next.js المستقبلية.

معلومة مفيدة:

على الرغم من أنها ليست اصطلاحًا في الإطار، يمكنك أيضًا التفكير في تمييز الملفات خارج المجلدات الخاصة كـ "خاصة" باستخدام نفس نمط الشرطة السفلية.

يمكنك إنشاء أجزاء URL تبدأ بشرطة سفلية عن طريق إضافة %5F (الشكل المشفر لـ URL للشرطة السفلية) كبادئة لاسم المجلد: %5FfolderName.

إذا كنت لا تستخدم المجلدات الخاصة، سيكون من المفهم معرفة اصطلاحات الملفات الخاصة بـ Next.js لتجنب تعارضات التسمية غير المتوقعة.

مجموعات المسارات (Route Groups)

يمكن إنشاء مجموعات المسارات عن طريق لف مجلد بين قوسين: (folderName)

هذا يشير إلى أن المجلد هو لأغراض تنظيمية ويجب ألا يُدرج في مسار URL.

مثال على هيكل مجلدات باستخدام مجموعات المسارات

مجموعات المسارات مفيدة لـ:

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

مجلد `src`

يدعم Next.js تخزين كود التطبيق (بما في ذلك app) داخل مجلد src اختياري. هذا يفصل كود التطبيق عن ملفات تكوين المشروع التي تعيش غالبًا في جذر المشروع.

أمثلة

يُدرج القسم التالي نظرة عامة عالية المستوى على الاستراتيجيات الشائعة. النصيحة الأساسية هي اختيار استراتيجية تناسبك وفريقك والالتزام بها عبر المشروع.

معلومة مفيدة: في الأمثلة أدناه، نستخدم مجلدات components و lib كعناصر نائبة عامة، تسمياتها ليس لها أهمية خاصة في الإطار وقد تستخدم مشاريعك مجلدات أخرى مثل ui، utils، hooks، styles، إلخ.