تهيئة TypeScript: إتقان خيارات مُصرّف TSConfig

ملف tsconfig.json هو قلب أي مشروع TypeScript. فهو يملي كيف يقوم مُصرّف TypeScript (tsc) بتحويل ملفات .ts إلى JavaScript. إن ملف tsconfig.json المهيأ بشكل جيد أمر بالغ الأهمية للحفاظ على جودة التعليمات البرمجية، وضمان التوافق عبر البيئات المختلفة، وتحسين عملية البناء. يتعمق هذا الدليل الشامل في خيارات tsconfig.json المتقدمة، مما يمكّنك من تحسين مشاريع TypeScript الخاصة بك لتحقيق ذروة الأداء وقابلية الصيانة.

فهم الأساسيات: لماذا يهم TSConfig

قبل أن نتعمق في الخيارات المتقدمة، دعنا نلخص سبب أهمية tsconfig.json:

• التحكم في الترجمة: فهو يحدد الملفات التي يجب تضمينها في مشروعك وكيف ينبغي ترجمتها.
• التحقق من النوع: فهو يحدد قواعد ودقة التحقق من النوع، مما يساعدك على اكتشاف الأخطاء مبكرًا في دورة التطوير.
• التحكم في الإخراج: فهو يحدد إصدار JavaScript المستهدف ونظام الوحدات ودليل الإخراج.
• تكامل IDE: فهو يوفر معلومات قيمة لبيئات التطوير المتكاملة (مثل VS Code و WebStorm وما إلى ذلك) لميزات مثل إكمال التعليمات البرمجية وتمييز الأخطاء وإعادة البناء.

بدون ملف tsconfig.json، سيستخدم مُصرّف TypeScript الإعدادات الافتراضية، والتي قد لا تكون مناسبة لجميع المشاريع. يمكن أن يؤدي هذا إلى سلوك غير متوقع ومشاكل في التوافق وتجربة تطوير أقل من مثالية.

إنشاء TSConfig الخاص بك: بداية سريعة

لإنشاء ملف tsconfig.json، ما عليك سوى تشغيل الأمر التالي في الدليل الجذر لمشروعك:

            tsc --init
            

              
                Copy
              
            
          

سيؤدي هذا إلى إنشاء ملف tsconfig.json أساسي مع بعض الخيارات الشائعة. يمكنك بعد ذلك تخصيص هذا الملف لتلبية المتطلبات المحددة لمشروعك.

خيارات المصرّف الرئيسية: نظرة عامة مفصلة

يحتوي ملف tsconfig.json على كائن compilerOptions، وهو المكان الذي تقوم فيه بتهيئة مُصرّف TypeScript. دعنا نستكشف بعض الخيارات الأكثر أهمية والأكثر استخدامًا:

target

يحدد هذا الخيار إصدار ECMAScript المستهدف لتعليمات JavaScript البرمجية المترجمة. فهو يحدد ميزات JavaScript التي سيستخدمها المُصرّف، مما يضمن التوافق مع البيئة المستهدفة (مثل المتصفحات و Node.js). تتضمن القيم الشائعة ES5 و ES6 (ES2015) و ES2017 و ES2018 و ES2019 و ES2020 و ES2021 و ES2022 و ESNext. سيستهدف استخدام ESNext أحدث ميزات ECMAScript المدعومة.

مثال:

            "compilerOptions": {
  "target": "ES2020"
}
            

              
                Copy
              
            
          

سيوجه هذا التكوين المُصرّف لإنشاء تعليمات JavaScript البرمجية المتوافقة مع ECMAScript 2020.

module

يحدد هذا الخيار نظام الوحدات المراد استخدامه في تعليمات JavaScript البرمجية المترجمة. تتضمن القيم الشائعة CommonJS و AMD و System و UMD و ES6 (ES2015) و ES2020 و ESNext. يعتمد اختيار نظام الوحدات على البيئة المستهدفة ومحمّل الوحدات المستخدم (مثل Node.js و Webpack و Browserify).

مثال:

            "compilerOptions": {
  "module": "CommonJS"
}
            

              
                Copy
              
            
          

هذا التكوين مناسب لمشاريع Node.js، والتي تستخدم عادةً نظام وحدات CommonJS.

lib

يحدد هذا الخيار مجموعة ملفات المكتبة المراد تضمينها في عملية الترجمة. توفر ملفات المكتبة هذه تعريفات النوع لواجهات برمجة تطبيقات JavaScript المضمنة وواجهات برمجة تطبيقات المتصفح. تتضمن القيم الشائعة ES5 و ES6 و ES7 و DOM و WebWorker و ScriptHost والمزيد.

مثال:

            "compilerOptions": {
  "lib": ["ES2020", "DOM"]
}
            

              
                Copy
              
            
          

يتضمن هذا التكوين تعريفات النوع لـ ECMAScript 2020 و DOM API، وهو أمر ضروري للمشاريع المستندة إلى المتصفح.

allowJs

يسمح هذا الخيار لمُصرّف TypeScript بترجمة ملفات JavaScript جنبًا إلى جنب مع ملفات TypeScript. يمكن أن يكون هذا مفيدًا عند ترحيل مشروع JavaScript إلى TypeScript أو عند العمل مع قواعد تعليمات JavaScript برمجية موجودة.

مثال:

            "compilerOptions": {
  "allowJs": true
}
            

              
                Copy
              
            
          

مع تمكين هذا الخيار، سيعالج المُصرّف كلاً من ملفات .ts و .js.

checkJs

يمكّن هذا الخيار التحقق من النوع لملفات JavaScript. عند دمجه مع allowJs، فإنه يسمح لـ TypeScript بتحديد أخطاء النوع المحتملة في تعليمات JavaScript البرمجية الخاصة بك.

مثال:

            "compilerOptions": {
  "allowJs": true,
  "checkJs": true
}
            

              
                Copy
              
            
          

يوفر هذا التكوين التحقق من النوع لكل من ملفات TypeScript و JavaScript.

jsx

يحدد هذا الخيار كيفية تحويل بناء جملة JSX (المستخدم في React والأطر الأخرى). تتضمن القيم الشائعة preserve و react و react-native و react-jsx. يترك preserve بناء جملة JSX كما هو، ويحوله react إلى استدعاءات React.createElement، و react-native مخصص لتطوير React Native، ويحوله react-jsx إلى وظائف مصنع JSX. react-jsxdev مخصص لأغراض التطوير.

مثال:

            "compilerOptions": {
  "jsx": "react"
}
            

              
                Copy
              
            
          

هذا التكوين مناسب لمشاريع React، حيث يحول JSX إلى استدعاءات React.createElement.

declaration

يقوم هذا الخيار بإنشاء ملفات إعلان (.d.ts) لتعليمات TypeScript البرمجية الخاصة بك. توفر ملفات الإعلان معلومات النوع لتعليماتك البرمجية، مما يسمح لمشاريع TypeScript الأخرى أو مشاريع JavaScript باستخدام تعليماتك البرمجية مع التحقق المناسب من النوع.

مثال:

            "compilerOptions": {
  "declaration": true
}
            

              
                Copy
              
            
          

سينشئ هذا التكوين ملفات .d.ts جنبًا إلى جنب مع ملفات JavaScript المترجمة.

declarationMap

يقوم هذا الخيار بإنشاء ملفات خريطة المصدر (.d.ts.map) لملفات الإعلان التي تم إنشاؤها. تسمح خرائط المصدر لأدوات تصحيح الأخطاء والأدوات الأخرى بالرجوع إلى تعليمات TypeScript البرمجية المصدر الأصلية عند العمل مع ملفات الإعلان.

مثال:

            "compilerOptions": {
  "declaration": true,
  "declarationMap": true
}
            

              
                Copy
              
            
          

sourceMap

يقوم هذا الخيار بإنشاء ملفات خريطة المصدر (.js.map) لتعليمات JavaScript البرمجية المترجمة. تسمح خرائط المصدر لأدوات تصحيح الأخطاء والأدوات الأخرى بالرجوع إلى تعليمات TypeScript البرمجية المصدر الأصلية عند تصحيح الأخطاء في المتصفح أو البيئات الأخرى.

مثال:

            "compilerOptions": {
  "sourceMap": true
}
            

              
                Copy
              
            
          

outFile

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

مثال:

            "compilerOptions": {
  "outFile": "dist/bundle.js"
}
            

              
                Copy
              
            
          

outDir

يحدد هذا الخيار دليل الإخراج لملفات JavaScript المترجمة. إذا لم يتم تحديده، فسيضع المُصرّف ملفات الإخراج في نفس دليل ملفات المصدر.

مثال:

            "compilerOptions": {
  "outDir": "dist"
}
            

              
                Copy
              
            
          

سيضع هذا التكوين ملفات JavaScript المترجمة في دليل dist.

rootDir

يحدد هذا الخيار الدليل الجذر لمشروع TypeScript. يستخدم المُصرّف هذا الدليل لحل أسماء الوحدات وإنشاء مسارات ملفات الإخراج. هذا مفيد بشكل خاص للهياكل المعقدة للمشاريع.

مثال:

            "compilerOptions": {
  "rootDir": "src"
}
            

              
                Copy
              
            
          

removeComments

يزيل هذا الخيار التعليقات من تعليمات JavaScript البرمجية المترجمة. يمكن أن يساعد هذا في تقليل حجم ملفات الإخراج.

مثال:

            "compilerOptions": {
  "removeComments": true
}
            

              
                Copy
              
            
          

noEmitOnError

يمنع هذا الخيار المُصرّف من إخراج ملفات JavaScript إذا تم اكتشاف أي أخطاء في النوع. يضمن هذا إنشاء تعليمات برمجية صالحة فقط.

مثال:

            "compilerOptions": {
  "noEmitOnError": true
}
            

              
                Copy
              
            
          

strict

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

مثال:

            "compilerOptions": {
  "strict": true
}
            

              
                Copy
              
            
          

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

• noImplicitAny
• noImplicitThis
• alwaysStrict
• strictNullChecks
• strictFunctionTypes
• strictBindCallApply
• noImplicitReturns
• noFallthroughCasesInSwitch

esModuleInterop

يمكّن هذا الخيار إمكانية التشغيل البيني بين وحدات CommonJS ووحدات ES. فهو يسمح لك باستيراد وحدات CommonJS في وحدات ES والعكس صحيح.

مثال:

            "compilerOptions": {
  "esModuleInterop": true
}
            

              
                Copy
              
            
          

forceConsistentCasingInFileNames

يفرض هذا الخيار اتساق حالة الأحرف في أسماء الملفات. هذا مهم للتوافق عبر الأنظمة الأساسية، حيث أن بعض أنظمة التشغيل حساسة لحالة الأحرف بينما البعض الآخر ليس كذلك.

مثال:

            "compilerOptions": {
  "forceConsistentCasingInFileNames": true
}
            

              
                Copy
              
            
          

baseUrl و paths

تسمح لك هذه الخيارات بتهيئة حل الوحدة. يحدد baseUrl الدليل الأساسي لحل أسماء الوحدات غير النسبية، ويسمح لك paths بتحديد أسماء مستعارة مخصصة للوحدات.

مثال:

            "compilerOptions": {
  "baseUrl": ".",
  "paths": {
    "@components/*": ["src/components/*"],
    "@utils/*": ["src/utils/*"]
  }
}
            

              
                Copy
              
            
          

يسمح لك هذا التكوين باستيراد الوحدات باستخدام الأسماء المستعارة مثل @components/MyComponent و @utils/myFunction.

التكوين المتقدم: ما وراء الأساسيات

الآن، دعنا نستكشف بعض خيارات tsconfig.json المتقدمة التي يمكن أن تزيد من تحسين تجربة تطوير TypeScript الخاصة بك.

الترجمة التزايدية

يدعم TypeScript الترجمة التزايدية، والتي يمكن أن تسرع بشكل كبير عملية البناء للمشاريع الكبيرة. لتمكين الترجمة التزايدية، قم بتعيين الخيار incremental على true وحدد الخيار tsBuildInfoFile.

مثال:

            "compilerOptions": {
  "incremental": true,
  "tsBuildInfoFile": ".tsbuildinfo"
}
            

              
                Copy
              
            
          

يحدد الخيار tsBuildInfoFile الملف الذي سيخزن فيه المُصرّف معلومات البناء. تُستخدم هذه المعلومات لتحديد الملفات التي تحتاج إلى إعادة ترجمتها أثناء عمليات البناء اللاحقة.

مراجع المشروع

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

لاستخدام مراجع المشروع، تحتاج إلى إنشاء ملف tsconfig.json منفصل لكل مشروع. ثم، في ملف tsconfig.json الرئيسي، يمكنك تحديد المشاريع التي يجب الرجوع إليها باستخدام الخيار references.

مثال:

            {
  "compilerOptions": {
    ...
  },
  "references": [
    { "path": "./project1" },
    { "path": "./project2" }
  ]
}
            

              
                Copy
              
            
          

يحدد هذا التكوين أن المشروع الحالي يعتمد على المشاريع الموجودة في الدليلين ./project1 و ./project2.

المحولات المخصصة

تسمح لك المحولات المخصصة بتعديل إخراج مُصرّف TypeScript. يمكن استخدام هذا لمجموعة متنوعة من الأغراض، مثل إضافة تحويلات التعليمات البرمجية المخصصة أو إزالة التعليمات البرمجية غير المستخدمة أو تحسين الإخراج لبيئات معينة. تُستخدم بشكل شائع لمهام تدويل i18n وتحديد الموقع.

لاستخدام المحولات المخصصة، تحتاج إلى إنشاء ملف JavaScript منفصل يصدر وظيفة سيتم استدعاؤها بواسطة المُصرّف. ثم، يمكنك تحديد ملف المحول باستخدام الخيار plugins في ملف tsconfig.json.

مثال:

            {
  "compilerOptions": {
    ...
    "plugins": [
      { "transform": "./transformer.js" }
    ]
  }
}
            

              
                Copy
              
            
          

يحدد هذا التكوين أنه يجب استخدام الملف ./transformer.js كمحول مخصص.

الملفات والتضمين والاستبعاد

بالإضافة إلى compilerOptions، تتحكم الخيارات الأخرى ذات المستوى الجذر في tsconfig.json في الملفات التي يتم تضمينها في عملية الترجمة:

• files: مصفوفة من مسارات الملفات المراد تضمينها في الترجمة.
• include: مصفوفة من أنماط glob تحدد الملفات المراد تضمينها.
• exclude: مصفوفة من أنماط glob تحدد الملفات المراد استبعادها.

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

مثال:

            {
  "compilerOptions": { ... },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.spec.ts"]
}
            

              
                Copy
              
            
          

يتضمن هذا التكوين جميع الملفات الموجودة في الدليل src والأدلة الفرعية الخاصة به، مع استبعاد الملفات الموجودة في الدليلين node_modules و dist، بالإضافة إلى أي ملفات بامتداد .spec.ts (تستخدم عادةً للاختبارات الوحدة).

خيارات المصرّف لسيناريوهات معينة

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

تطوير تطبيقات الويب

لتطوير تطبيقات الويب، سترغب عادةً في استخدام إعدادات المُصرّف التالية:

            {
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Node",
    "jsx": "react-jsx",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "sourceMap": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
            

              
                Copy
              
            
          

هذه الإعدادات مناسبة لتطبيقات الويب الحديثة التي تستخدم React أو أطر عمل مماثلة أخرى. إنها تستهدف أحدث ميزات ECMAScript، وتستخدم وحدات ES، وتمكّن التحقق الصارم من النوع.

تطوير الواجهة الخلفية Node.js

لتطوير الواجهة الخلفية Node.js، سترغب عادةً في استخدام إعدادات المُصرّف التالية:

            {
  "compilerOptions": {
    "target": "ESNext",
    "module": "CommonJS",
    "esModuleInterop": true,
    "strict": true,
    "sourceMap": true,
    "outDir": "dist",
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
            

              
                Copy
              
            
          

هذه الإعدادات مناسبة لتطبيقات Node.js التي تستخدم نظام وحدات CommonJS. إنها تستهدف أحدث ميزات ECMAScript، وتمكّن التحقق الصارم من النوع، وتسمح لك باستيراد ملفات JSON كوحدات.

تطوير المكتبة

لتطوير المكتبة، سترغب عادةً في استخدام إعدادات المُصرّف التالية:

            {
  "compilerOptions": {
    "target": "ES5",
    "module": "UMD",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}
            

              
                Copy
              
            
          

هذه الإعدادات مناسبة لإنشاء مكتبات يمكن استخدامها في كل من بيئات المستعرض و Node.js. إنها تنشئ ملفات إعلان وخرائط مصدر لتحسين تجربة المطور.

أفضل الممارسات لإدارة TSConfig

فيما يلي بعض أفضل الممارسات التي يجب وضعها في الاعتبار عند إدارة ملفات tsconfig.json الخاصة بك:

• ابدأ بتكوين أساسي: قم بإنشاء ملف tsconfig.json أساسي بإعدادات شائعة ثم قم بتوسيعه في مشاريع أخرى باستخدام الخيار extends.
• استخدم الوضع الصارم: قم بتمكين الوضع الصارم لاكتشاف الأخطاء المحتملة وفرض أفضل الممارسات.
• قم بتهيئة حل الوحدة: قم بتهيئة حل الوحدة بشكل صحيح لتجنب أخطاء الاستيراد.
• استخدم مراجع المشروع: قم بهيكلة التعليمات البرمجية الخاصة بك في مشاريع أصغر وأكثر قابلية للإدارة باستخدام مراجع المشروع.
• حافظ على تحديث ملف tsconfig.json الخاص بك: راجع ملف tsconfig.json الخاص بك بانتظام وقم بتحديثه مع تطور مشروعك.
• تحكم في إصدار ملف tsconfig.json الخاص بك: قم بتثبيت ملف tsconfig.json الخاص بك في التحكم في الإصدار جنبًا إلى جنب مع تعليماتك البرمجية المصدر الأخرى.
• وثّق التكوين الخاص بك: أضف تعليقات إلى ملف tsconfig.json الخاص بك لشرح الغرض من كل خيار.

الخلاصة: إتقان تهيئة TypeScript

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