هيكل مشروع TypeScript: دليل عملي من الصفر للمبتدئين

نُشر في 2026-10-23 · آخر تحديث 2026-10-23

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

لماذا تحتاج هيكلة واضحة من اليوم الأول

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

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

الخطوة الأولى: تهيئة المشروع وإعداداته الأساسية

ابدأ دائمًا بإنشاء مجلد فارغ وتهيئته بـ npm init، ثم أضف TypeScript كاعتمادية تطوير عبر npm install typescript --save-dev. بعدها شغّل الأمر npx tsc --init لتوليد ملف tsconfig.json، وهو الملف الذي يحدد كيف يترجم TypeScript كودك إلى JavaScript.

في ملف tsconfig.json، اهتم بثلاثة إعدادات أساسية منذ البداية: rootDir ليشير إلى مجلد src حيث يوجد الكود المصدري، outDir ليشير إلى مجلد dist حيث توضع النتيجة المترجمة، و strict لتفعيل الفحص الصارم للأنواع الذي يمنع كثيرًا من الأخطاء قبل أن تصل إلى الإنتاج.

• rootDir: "./src" لتحديد مصدر الكود
• outDir: "./dist" لمخرجات الترجمة
• strict: true لتفعيل فحص الأنواع الصارم
• include: ["src/**/*"] لتحديد الملفات المشمولة بالترجمة

الخطوة الثانية: شكل المجلدات الذي ننصح به

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

• src/ — كل الكود المصدري بصيغة TypeScript
• dist/ — المخرجات المترجمة، ولا يُعدَّل يدويًا أبدًا
• tests/ — ملفات الاختبارات منفصلة عن الكود الفعلي
• config/ — ملفات الإعدادات مثل متغيرات البيئة وإعدادات قواعد البيانات
• package.json و tsconfig.json — في جذر المشروع دائمًا
• .gitignore — يستثني dist و node_modules من المستودع

الخطوة الثالثة: تنظيم الكود داخل src حسب الطبقات

داخل مجلد src نفسه، الخطأ الشائع هو وضع كل الملفات في مستوى واحد. الأفضل تقسيمها إلى طبقات واضحة المسؤولية، بحيث يعرف أي مطور جديد أين يضع كود جديد دون تردد.

مثال عملي لمشروع خدمة ويب بسيطة: مجلد routes يحتوي نقاط الدخول (endpoints)، ومجلد services يحتوي المنطق البرمجي الفعلي، ومجلد models يحتوي تعريفات البيانات والأنواع، ومجلد utils يحتوي الدوال المساعدة العامة. هذا الفصل يجعل كل ملف صغيرًا ومحددَ الغرض، وهو ما يسهّل الاختبار والصيانة.

• src/routes — نقاط الدخول وربطها بالخدمات
• src/services — المنطق البرمجي والعمليات الأساسية
• src/models — تعريفات البيانات وواجهات الأنواع (interfaces)
• src/utils — دوال مساعدة عامة يُعاد استخدامها
• src/index.ts — نقطة تشغيل المشروع فقط، بلا منطق معقّد بداخلها

إدارة البيانات والإعدادات بدون فوضى

أي مشروع حقيقي سيحتاج التعامل مع بيانات، سواء كانت قاعدة بيانات أو ملفات إعداد أو متغيرات بيئة حساسة مثل مفاتيح API. القاعدة الأساسية هنا: لا تخلط منطق الوصول للبيانات مع منطق العرض أو المسارات. ضع كل التفاعل مع قاعدة البيانات في طبقة services أو مجلد مستقل باسم data أو repositories، بحيث لو غيّرت قاعدة البيانات لاحقًا لا تحتاج لتعديل باقي المشروع.

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

الاختبارات وجودة الكود كجزء من الهيكل

مجلد tests ليس رفاهية، بل جزء من الهيكل نفسه منذ اليوم الأول. ضع اختبار لكل خدمة أساسية في src/services، واجعل اسم ملف الاختبار مطابقًا لاسم الملف الأصلي مع إضافة test أو spec، مثل user.service.test.ts مقابل user.service.ts.

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

من الهيكل الجيد إلى مشروع منشور فعليًا

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

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

أسئلة

ابدأ مجانًا القوالب