بنية ملفات مجلد مشروع React

بنية ملفات ريأكتشرح ملفات Reactدور main.jsxما هو عنصر rootمجلد src في ريأكتتعلم هيكلة كود React

جدول مرجعي سريع

تشريح بنية ملفات مجلد مشروع React وفهم دور index.html و main.jsx

الملف أو المجلد	دوره البنيوي في المعمارية	الأهمية الدلالية والتعديل البرمجي
index.html	الحاوية الرئيسية والوحيدة لصفحة الويب وبها عنصر الجذر div	لا يتم التعديل عليه غالباً ويمثل الهيكل الخارجي الذي يستقبل الواجهات الديناميكية
package.json	خريطة البيانات الكبرى للمشروع وتحتوي على أسماء المكتبات والإصدارات	يُمنع تعديلها يدوياً بعشوائية وتضمن توافق الاعتماديات مع خوادم الرفع والنشر
src/main.jsx	نقطة الانطلاق الفعلي ومحرك الربط بين ريأكت وصفحة الويب الرسمية	يقوم بحقن المكون الرئيسي وتمريره إلى عنصر الجدار الحقيقي في المتصفح
src/App.jsx	المكون الجذري والأساسي للموقع ويمثل اللوحة الأم لكافة الواجهات	هو الملف الرئيسي الذي يبدأ المطور في كتابة وتغيير الأكواد بداخله بناءً على التصميم

الشرح

عندما تقوم بفتح مشروع React الجديد الذي أنشأته باستخدام أداة Vite داخل محرر الأكواد (VS Code)، قد تشعر بالتشتت للوهلة الأولى بسبب كثرة المجلدات والملفات ذات الامتدادات الغريبة مثل .jsx.

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

1. مجلدات الهيكل الخارجي

مجلد node_modules: هو المجلد الأضخم مساحة، ويحتوي على الكود الفعلي لكافة المكتبات والاعتماديات التي قمت بتثبيتها عبر أداة npm. لا تقم بلمسه أو تعديل أي شيء داخله مطلقاً.
مجلد public: يحتوي على الملفات الثابتة التي لا تحتاج إلى معالجة برمجية من المترجمات، مثل أيقونة الموقع (favicon.ico) أو الصور الأساسية الشاملة.

2. مثلث الانطلاق السحري: كيف يظهر الموقع في المتصفح؟

السر الهندسي وراء معمارية تطبيقات الصفحة الواحدة (SPA) في React يكمن في تتابع سحري لثلاثة ملفات أساسية تتصل ببعضها بشكل خطي دقيق:

أ) المحطة الأولى: ملف index.html

هذا هو ملف HTML الوحيد واليتيم في المشروع بأكمله! لو قمت بفتحه، ستجده ملفاً عادياً جداً وقصيراً، لكنه يحتوي على سطرين هما سر المعمارية بأكملها:

وسم <div id="root"></div>: هذا هو الوعاء الفارغ الذي ستقوم ريأكت بحقن وبناء كل واجهات الموقع داخله.
وسم الـ <script type="module" src="/src/main.jsx"></script>: وهو السطر الذي يستدعي المحرك البرمجي الرئيسي ليتولى إدارة الشاشة.

ب) المحطة الثانية: ملف src/main.jsx

هذا الملف هو "جسر العبور" وعقل الربط الهيكلي. يأخذ هذا الملف المكون البرمجي الرئيسي للموقع، ويذهب إلى الـ Real DOM للمتصفح، ويبحث عن العنصر الذي يحمل الـ id="root" ويقول له: "تنحَّ جانباً، سأتولى أنا الآن إدارة وعرض كل شيء داخل هذا الـ div!".

ج) المحطة الثالثة: ملف src/App.jsx

هذا هو "المكون الأب" أو اللوحة الأم (Root Component) للموقع. كل الأزرار، القوائم، والنصوص التي تراها في المتصفح حالياً مكتوبة داخل هذا الملف. هنا تحديداً تبدأ أنت كمطور برمجيات في مسح الأكواد الافتراضية وكتابة أكواد تطبيقك الخاص.

الهيكل البرمجي والأكواد القياسية لملفات الانطلاق

دعنا نرى كيف يبدو كود ملف الربط الرئيسي src/main.jsx لنفهم كيف يقوم بحقن الأكواد داخل الـ HTML:

الصياغة (Syntax)

syntax

1	import { StrictMode } from 'react'
2	import { createRoot } from 'react-dom/client'
3	import './index.css'
4	import App from './App.jsx' // استيراد المكون الرئيسي الأب
5
6	// استهداف الـ div الذي يحمل id="root" من ملف index.html وحقن تطبيق ريأكت داخله
7	createRoot(document.getElementById('root')).render(
8	<StrictMode>
9	<App />
10	</StrictMode>,
11	)

نصائح احترافية

—ستلاحظ وجود ملف في جذر المشروع يُسمى package.json. هذا الملف هو بمثابة "بطاقة الهوية الرسمية للمشروع". يحتوي على أسماء وإصدارات كل المكتبات المستخدمة.
—التركاية هنا هي أنك عندما تريد مشاركة مشروعك مع صديقك أو رفعه على موقع مثل GitHub، إياك أن ترفع مجلد node_modules لأن حجمه عملاق وقد يستغرق ساعات! قم بمسحه تماماً وارفع بقية الملفات الصغيرة فقط؛ وعندما يقوم صديقك بتحميل المشروع، كل ما عليه فعله هو فتح الـ Terminal وكتابة الأمر القصير npm install، وسيقوم الـ npm تلقائياً بقراءة ملف package.json وإعادة تحميل كافة الحزم والمجلدات الممسوحة في ثوانٍ معدودة وبنفس الإصدارات المتوافقة!

الدرس السابق

إنشاء مشروع React باستخدام Vite

الدرس التالي

ما هي صياغة JSX وكيف يفهمها المتصفح

الملف أو المجلد

دوره البنيوي في المعمارية

الأهمية الدلالية والتعديل البرمجي

index.html

الحاوية الرئيسية والوحيدة لصفحة الويب وبها عنصر الجذر div

لا يتم التعديل عليه غالباً ويمثل الهيكل الخارجي الذي يستقبل الواجهات الديناميكية

package.json

خريطة البيانات الكبرى للمشروع وتحتوي على أسماء المكتبات والإصدارات

يُمنع تعديلها يدوياً بعشوائية وتضمن توافق الاعتماديات مع خوادم الرفع والنشر

src/main.jsx

نقطة الانطلاق الفعلي ومحرك الربط بين ريأكت وصفحة الويب الرسمية

يقوم بحقن المكون الرئيسي وتمريره إلى عنصر الجدار الحقيقي في المتصفح

src/App.jsx

المكون الجذري والأساسي للموقع ويمثل اللوحة الأم لكافة الواجهات

هو الملف الرئيسي الذي يبدأ المطور في كتابة وتغيير الأكواد بداخله بناءً على التصميم

1. مجلدات الهيكل الخارجي

مجلد node_modules: هو المجلد الأضخم مساحة، ويحتوي على الكود الفعلي لكافة المكتبات والاعتماديات التي قمت بتثبيتها عبر أداة npm. لا تقم بلمسه أو تعديل أي شيء داخله مطلقاً.

مجلد public: يحتوي على الملفات الثابتة التي لا تحتاج إلى معالجة برمجية من المترجمات، مثل أيقونة الموقع (favicon.ico) أو الصور الأساسية الشاملة.

2. مثلث الانطلاق السحري: كيف يظهر الموقع في المتصفح؟

أ) المحطة الأولى: ملف index.html

وسم <div id="root"></div>: هذا هو الوعاء الفارغ الذي ستقوم ريأكت بحقن وبناء كل واجهات الموقع داخله.

وسم الـ <script type="module" src="/src/main.jsx"></script>: وهو السطر الذي يستدعي المحرك البرمجي الرئيسي ليتولى إدارة الشاشة.

ب) المحطة الثانية: ملف src/main.jsx

ج) المحطة الثالثة: ملف src/App.jsx