مستودع أحادي مع TypeScript: تنظيم الكود وأفضل الممارسات

مقدمة إلى المستودعات الأحادية مع TypeScript

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

المستودع الأحادي (monorepo) هو استراتيجية يتم فيها تخزين كود عدة مشاريع في مستودع واحد. وبالاقتران مع TypeScript، يصبح المستودع الأحادي أداة قوية: فالكتابة الصارمة (strict typing) تضمن أمان التغييرات عبر المجموعة الكاملة، ونظام البناء الموحد يبسط إدارة التبعيات.

في هذه المقالة، سننظر في كيفية تنظيم مستودع أحادي مع TypeScript: من الهيكل الأساسي إلى الأدوات المتقدمة مثل Nx و Turborepo.

مزايا المستودع الأحادي لمشاريع TypeScript

قبل الانتقال إلى التطبيق العملي، دعنا نفهم لماذا يعتبر المستودع الأحادي مفيدًا بشكل خاص لمشاريع TypeScript:

• كتابة موحدة — يتيح TypeScript إعادة استخدام الواجهات (interfaces) والأنواع (types) بين الحزم دون تكرار.
• الالتزامات الذرية (Atomic commits) — يمكن إجراء تغييرات على API والمستهلكين له في التزام واحد، مما يبسط المراجعة والتراجع.
• إعادة هيكلة مبسطة — بيئة التطوير المتكاملة (IDE) (مثل VS Code) تتعامل بشكل صحيح مع إعادة التسمية ونقل الملفات عبر المستودع بأكمله.
• تخزين مؤقت للبناءات — أدوات مثل Nx تخزن نتائج التجميع مؤقتًا، مما يسرع CI/CD.

الهيكل الأساسي للمستودع الأحادي

لنبدأ بهيكل بسيط ولكنه فعال. سننشئ مشروعًا جذريًا وعدة حزم:

my-monorepo/├── packages/│   ├── shared/          # الأنواع والأدوات المساعدة المشتركة│   │   ├── src/│   │   ├── package.json│   │   └── tsconfig.json│   ├── server/          # الواجهة الخلفية (مثل Express)│   │   ├── src/│   │   ├── package.json│   │   └── tsconfig.json│   └── web/             # الواجهة الأمامية (React)│       ├── src/│       ├── package.json│       └── tsconfig.json├── package.json         # ملف package.json الجذري├── tsconfig.base.json   # tsconfig أساسي لجميع الحزم└── .gitignore

ملف package.json الجذري يجب أن يحتوي على تكوين workspace. بالنسبة لـ npm و Yarn، يبدو كالتالي:

{  "name": "my-monorepo",  "private": true,  "workspaces": [    "packages/*"  ],  "scripts": {    "build": "tsc --build",    "clean": "tsc --build --clean"  }}

ملف tsconfig.base.json الأساسي يحدد إعدادات التجميع المشتركة:

{  "compilerOptions": {    "target": "ES2020",    "module": "commonjs",    "strict": true,    "esModuleInterop": true,    "skipLibCheck": true,    "forceConsistentCasingInFileNames": true,    "declaration": true,    "declarationMap": true,    "sourceMap": true,    "composite": true  }}

كل حزمة توسع التكوين الأساسي:

{  "extends": "../../tsconfig.base.json",  "compilerOptions": {    "outDir": "./dist",    "rootDir": "./src"  },  "include": ["src"]}

إدارة التبعيات ومسارات TypeScript (paths)

إحدى المشكلات الرئيسية للمستودعات الأحادية هي الإعداد الصحيح للاستيرادات بين الحزم. بدلاً من نشر الحزم على npm، نستخدم TypeScript Project References و paths.

إعداد Project References

دعنا نضيف مراجع للمشاريع في ملف tsconfig.json الجذري:

{  "files": [],  "references": [    { "path": "./packages/shared" },    { "path": "./packages/server" },    { "path": "./packages/web" }  ]}

الآن عند تشغيل