إعدادات TypeScript: دليل شامل لملف tsconfig.json

تايب سكريبت (TypeScript)، وهي مجموعة شاملة من جافا سكريبت (JavaScript)، تجلب الكتابة الثابتة (static typing) إلى عالم تطوير الويب الديناميكي. يعد ملف tsconfig.json المُعد جيدًا أمرًا بالغ الأهمية لتسخير القوة الكاملة لـ TypeScript. يقدم هذا الدليل نظرة شاملة على tsconfig.json، ويغطي خيارات المترجم الأساسية، وإعداد المشاريع، والتكوينات المتقدمة.

ما هو ملف tsconfig.json؟

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

إنشاء ملف tsconfig.json

لإنشاء ملف tsconfig.json، انتقل إلى الدليل الجذر لمشروعك في الطرفية (terminal) وقم بتشغيل الأمر التالي:

tsc --init

ينشئ هذا الأمر ملف tsconfig.json أساسيًا مع خيارات المترجم شائعة الاستخدام. يمكنك بعد ذلك تخصيص الملف ليناسب المتطلبات المحددة لمشروعك. سيتضمن ملف tsconfig.json النموذجي خيارات مثل compilerOptions و include و exclude.

خيارات المترجم الأساسية

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

target

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

مثال:

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

module

يحدد خيار module نمط توليد كود الوحدات (modules). تشمل القيم الشائعة CommonJS و AMD و System و UMD و ES6 (ES2015) و ES2020 و ESNext. يعتمد اختيار نظام الوحدات على البيئة المستهدفة ومُجمِّع الوحدات المستخدم (مثل Webpack، Rollup، Parcel). بالنسبة لـ Node.js، غالبًا ما يتم استخدام CommonJS، بينما بالنسبة لتطبيقات الويب الحديثة، يُفضل استخدام ES6 أو ESNext مع مُجمِّع وحدات. يتيح استخدام ESNext للمطورين الاستفادة من أحدث الميزات والتحسينات، مع الاعتماد على المُجمِّع للتعامل مع تنسيق الوحدة النهائي.

مثال:

{
  "compilerOptions": {
    "module": "ESNext"
  }
}

lib

يحدد خيار lib قائمة بملفات المكتبات التي سيتم تضمينها في عملية الترجمة. توفر ملفات المكتبات هذه تعريفات الأنواع (type definitions) لواجهات برمجة التطبيقات (APIs) المدمجة في JavaScript وواجهات برمجة تطبيقات المتصفح. تشمل القيم الشائعة ES5, ES6, ES2015, ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext, DOM, WebWorker, ScriptHost, ES2015.Core, ES2015.Collection, ES2015.Iterable, ES2015.Promise, ES2015.Proxy, ES2015.Reflect, ES2015.Generator, ES2015.Symbol, ES2015.Symbol.WellKnown, ES2016.Array.Include, ES2017.object, ES2017.Intl, ES2017.SharedMemory, ES2017.String, ES2017.TypedArrays, ES2018.Intl, ES2018.Promise, ES2018.RegExp, ES2019.Array, ES2019.Object, ES2019.String, ES2019.Symbol, ES2020.BigInt, ES2020.Promise, ES2020.String, ES2020.Symbol.WellKnown, ES2021.Promise, ES2021.String, ES2021.WeakRef, ES2022.Error, ES2022.Object, ES2022.String, وغيرها الكثير. يضمن تحديد المكتبات المناسبة أن مترجم TypeScript لديه معلومات النوع اللازمة للبيئة المستهدفة. يتيح استخدام مكتبة DOM للمشروع ترجمة الكود الذي يستخدم واجهات برمجة التطبيقات الخاصة بالمتصفح دون أخطاء في النوع.

مثال:

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

allowJs

يسمح خيار allowJs لمترجم TypeScript بترجمة ملفات JavaScript إلى جانب ملفات TypeScript. هذا مفيد للترحيل التدريجي لمشاريع JavaScript الحالية إلى TypeScript. يؤدي تعيين هذا الخيار إلى true إلى تمكين المترجم من معالجة ملفات .js، مما يسمح بالتبني التدريجي لـ TypeScript داخل المشروع.

مثال:

{
  "compilerOptions": {
    "allowJs": true
  }
}

jsx

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

مثال:

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

declaration

يُنشئ خيار declaration ملفات تصريح .d.ts مقابلة لكل ملف TypeScript. تحتوي ملفات التصريح على معلومات الأنواع وتستخدمها مشاريع TypeScript الأخرى لاستهلاك الكود المترجم. يعد إنشاء ملفات التصريح أمرًا ضروريًا لإنشاء مكتبات ووحدات قابلة لإعادة الاستخدام. تتيح هذه الملفات لمشاريع TypeScript الأخرى فهم الأنواع والواجهات التي تعرضها المكتبة دون الحاجة إلى ترجمة الكود المصدري الأصلي.

مثال:

{
  "compilerOptions": {
    "declaration": true
  }
}

sourceMap

يُنشئ خيار sourceMap ملفات خرائط المصدر (source map)، والتي تربط كود JavaScript المُنشأ مرة أخرى بكود TypeScript الأصلي. تعد خرائط المصدر ضرورية لتصحيح أخطاء كود TypeScript في المتصفحات والبيئات الأخرى. عند حدوث خطأ في كود JavaScript، تتيح خريطة المصدر للمطور رؤية كود TypeScript المقابل في مصحح الأخطاء (debugger)، مما يسهل تحديد المشكلة وإصلاحها.

مثال:

{
  "compilerOptions": {
    "sourceMap": true
  }
}

outDir

يحدد خيار outDir دليل الإخراج لملفات JavaScript التي تم إنشاؤها. يساعد هذا الخيار في تنظيم مخرجات بناء المشروع عن طريق فصل الكود المصدري عن الكود المترجم. يسهل استخدام outDir إدارة عملية البناء ونشر التطبيق.

مثال:

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

rootDir

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

مثال:

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

strict

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

مثال:

{
  "compilerOptions": {
    "strict": true
  }
}

esModuleInterop

يمكّن خيار esModuleInterop التشغيل البيني بين وحدات CommonJS ووحدات ES. هذا مهم للمشاريع التي تستخدم كلا النوعين من الوحدات. عند تمكين esModuleInterop، سيتعامل TypeScript تلقائيًا مع الاختلافات بين وحدات CommonJS و ES، مما يسهل استيراد وتصدير الوحدات بين النظامين. هذا الخيار مفيد بشكل خاص عند العمل مع مكتبات خارجية قد تستخدم أنظمة وحدات مختلفة.

مثال:

{
  "compilerOptions": {
    "esModuleInterop": true
  }
}

moduleResolution

يحدد خيار moduleResolution كيفية حل TypeScript لعمليات استيراد الوحدات. تشمل القيم الشائعة Node و Classic. استراتيجية حل الوحدات Node هي الافتراضية وتستند إلى خوارزمية حل الوحدات في Node.js. استراتيجية حل الوحدات Classic أقدم وأقل استخدامًا. يضمن استخدام استراتيجية حل الوحدات Node أن TypeScript يمكنه حل استيراد الوحدات بشكل صحيح في بيئة Node.js.

مثال:

{
  "compilerOptions": {
    "moduleResolution": "Node"
  }
}

baseUrl و paths

يُستخدم خيارا baseUrl و paths لتكوين حل الوحدات لعمليات استيراد الوحدات غير النسبية. يحدد خيار baseUrl الدليل الأساسي لحل أسماء الوحدات غير النسبية. يسمح لك خيار paths بربط أسماء الوحدات بمواقع محددة على نظام الملفات. هذه الخيارات مفيدة بشكل خاص للمشاريع ذات الهيكل الدليلي المعقد ولتبسيط عمليات استيراد الوحدات. يمكن أن يجعل استخدام baseUrl و paths الكود أكثر قابلية للقراءة والصيانة.

مثال:

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

خيارا Include و Exclude

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

مثال:

{
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

خيار Extends

يسمح لك خيار extends بوراثة خيارات المترجم من ملف tsconfig.json آخر. هذا مفيد لمشاركة إعدادات التكوين الشائعة بين مشاريع متعددة أو لإنشاء تكوينات أساسية. يعزز استخدام خيار extends إعادة استخدام الكود ويقلل من التكرار. من أفضل الممارسات إنشاء تكوينات أساسية وتوسيعها في المشاريع الفردية.

مثال:

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["src/**/*"]
}

الإعدادات المتقدمة

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

الترجمة التزايدية (Incremental Compilation)

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

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

مراجع المشروع (Project References)

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

{
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "./module1" },
    { "path": "./module2" }
  ]
}

تعريفات الأنواع المخصصة

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

// custom.d.ts
declare module 'my-library' {
  export function doSomething(x: number): string;
}

أفضل الممارسات

• استخدام الوضع الصارم (Strict Mode): قم بتمكين خيار strict لتعزيز التحقق من الأنواع.
• تحديد الهدف (Target): اختر إصدار target المناسب لبيئة التشغيل الخاصة بك.
• تنظيم المخرجات: استخدم outDir لفصل الكود المصدري عن الكود المترجم.
• إدارة التبعيات: استخدم include و exclude للتحكم في الملفات التي يتم ترجمتها.
• الاستفادة من Extends: شارك إعدادات التكوين الشائعة باستخدام خيار extends.
• إضافة ملف الإعدادات إلى نظام التحكم في الإصدارات: قم بإيداع (commit) ملف `tsconfig.json` في git للحفاظ على الاتساق عبر بيئات المطورين وخطوط أنابيب CI/CD.

استكشاف الأخطاء الشائعة وإصلاحها

قد يكون تكوين tsconfig.json صعبًا في بعض الأحيان. إليك بعض المشكلات الشائعة وحلولها:

مشاكل في حل الوحدات (Module Resolution)

إذا واجهت أخطاء في حل الوحدات، فتأكد من أن خيار moduleResolution تم تكوينه بشكل صحيح وأن خياري baseUrl و paths قد تم إعدادهما بشكل صحيح. تحقق جيدًا من المسارات المحددة في خيار paths للتأكد من صحتها. تحقق من أن جميع الوحدات الضرورية مثبتة في دليل node_modules.

أخطاء الأنواع (Type Errors)

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

أخطاء الترجمة (Compilation Errors)

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

الخاتمة

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

تذكر الرجوع إلى وثائق TypeScript الرسمية للحصول على أحدث المعلومات والشروحات التفصيلية لجميع خيارات المترجم المتاحة. تعد وثائق TypeScript مصدرًا قيمًا لفهم تعقيدات إعدادات TypeScript.