بدء استخدام TypeScript

التثبيت

يوفّر Visual Studio Code دعمًا ممتازًا للغة TypeScript، لكنه لا يتضمن مصرّف TypeScript. لتثبيت مصرّف TypeScript، يمكنك استخدام مدير حزم مثل npm أو yarn:

npm install typescript --save-dev

أو

yarn add typescript --dev

تأكد من إيداع ملف القفل الناتج لضمان استخدام كل عضو في الفريق لإصدار TypeScript نفسه.

لتشغيل مصرّف TypeScript، يمكنك استخدام الأوامر التالية:

npx tsc

أو

yarn tsc

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

npx tsc

أو تثبيتها عموميًا:

npm install -g typescript

إذا كنت تستخدم Microsoft Visual Studio، فيمكنك الحصول على TypeScript بوصفها حزمة في NuGet لمشروعات MSBuild. نفّذ الأمر التالي في وحدة تحكم مدير حزم NuGet:

Install-Package Microsoft.TypeScript.MSBuild

أثناء تثبيت TypeScript، يُثبَّت ملفان تنفيذيان: “tsc” بوصفه مصرّف TypeScript و”tsserver” بوصفه خادم TypeScript المستقل. يحتوي الخادم المستقل على المصرّف وخدمات اللغة التي يمكن للمحرّرات وبيئات التطوير المتكاملة استخدامها لتوفير الإكمال الذكي للشيفرة.

إضافةً إلى ذلك، تتوفر عدة محوّلات متوافقة مع TypeScript، مثل Babel (عبر مكوّن إضافي) أو swc. ويمكن استخدام هذه المحوّلات لتحويل شيفرة TypeScript إلى لغات أو إصدارات مستهدفة أخرى.

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

يمكن ضبط بعض ميزات الأداء في TypeScript 7.0. يمكن تشغيل التحقق من الأنواع في عمليات عاملة متوازية باستخدام --checkers؛ وقد يؤدي المزيد من العمليات العاملة إلى تسريع المشروعات الكبيرة، لكنه يستهلك ذاكرة أكبر. يحسّن وضع --watch المعاد بناؤه مراقبة الملفات عبر المنصات. لا تتضمن TypeScript 7.0 حتى الآن واجهة API للمصرّف (حتى يوليو 2026)، ولذلك يمكن للأدوات التي لا تزال تحتاج إلى واجهة API في TypeScript 6.0 تشغيلها بالتوازي مع TypeScript 7.0 باستخدام @typescript/typescript6 أو الأسماء البديلة في npm.

التهيئة

يمكن تهيئة TypeScript باستخدام خيارات واجهة سطر أوامر tsc أو عبر استخدام ملف تهيئة مخصّص يُسمّى tsconfig.json ويوضع في جذر المشروع.

لإنشاء ملف tsconfig.json مجهّز مسبقًا بالإعدادات الموصى بها، يمكنك استخدام الأمر التالي:

tsc --init

عند تنفيذ الأمر tsc محليًا، ستصرّف TypeScript الشيفرة باستخدام التهيئة المحددة في أقرب ملف tsconfig.json.

فيما يلي بعض أمثلة أوامر واجهة سطر الأوامر التي تعمل بالإعدادات الافتراضية:

tsc main.ts // Compile a specific file (main.ts) to JavaScript
tsc src/*.ts // Compile any .ts files under the 'src' folder to JavaScript
tsc app.ts util.ts --outfile index.js // Compile two TypeScript files (app.ts and util.ts) into a single JavaScript file (index.js)

ملف تهيئة TypeScript

يُستخدم ملف tsconfig.json لتهيئة مصرّف TypeScript ‏(tsc). وعادةً ما يُضاف إلى جذر المشروع إلى جانب ملف package.json.

ملاحظات:

• يقبل tsconfig.json التعليقات حتى وإن كان بتنسيق json.
• يُنصح باستخدام ملف التهيئة هذا بدلًا من خيارات سطر الأوامر.

يمكنك العثور في الرابط التالي على الوثائق الكاملة والمخطط الخاص به:

https://www.typescriptlang.org/tsconfig

https://www.typescriptlang.org/tsconfig/

تمثّل القائمة التالية مجموعة من إعدادات التهيئة الشائعة والمفيدة:

target

تُستخدم الخاصية “target” لتحديد إصدار ECMAScript الذي ينبغي أن تُخرج أو تُصرّف إليه شيفرة TypeScript. وتُعد ES6 خيارًا جيدًا للمتصفحات الحديثة. ملاحظة: أُهمل دعم ES5 في TypeScript 6.0، ولم يعد مدعومًا في TypeScript 7.0.

lib

تُستخدم الخاصية “lib” لتحديد ملفات المكتبة التي يجب تضمينها في وقت التصريف. تضمّن TypeScript تلقائيًا واجهات API للميزات المحددة في الخاصية “target”، لكن يمكن استبعاد مكتبات بعينها أو اختيارها لتلبية احتياجات محددة. فإذا كنت تعمل على مشروع خادم مثلًا، يمكنك استبعاد مكتبة “DOM” التي لا تفيد إلا في بيئة المتصفح.

strict

يحسّن الخيار “strict” أمان الأنواع بتمكين عمليات تحقق أقوى. وهو مفعّل افتراضيًا بدءًا من TypeScript 6.0؛ وفي غير ذلك، ينبغي ضبطه صراحةً على true في ملف tsconfig.json. يتيح تمكين “strict” لـ TypeScript ما يلي:

• إخراج الشيفرة باستخدام “use strict” لكل ملف مصدر.
• مراعاة “null” و”undefined” في عملية التحقق من الأنواع.
• تعطيل استخدام النوع “any” عند عدم وجود تعليقات توضيحية للأنواع.
• إصدار خطأ عند استخدام التعبير “this” الذي كان سيعني خلاف ذلك النوع “any”.

module

تحدد الخاصية “module” نظام الوحدات المدعوم للبرنامج المصرّف. وفي وقت التشغيل، يُستخدم محمّل وحدات لتحديد التبعيات وتنفيذها استنادًا إلى نظام الوحدات المحدد.

أكثر محمّلات الوحدات استخدامًا في JavaScript هما CommonJS في Node.js لتطبيقات جانب الخادم وRequireJS لوحدات AMD في تطبيقات الويب القائمة على المتصفح. ويمكن لـ TypeScript إخراج شيفرة لأنظمة وحدات مختلفة، منها UMD وSystem وESNext وES2015/ES6 وES2020. وينبغي اختيار نظام الوحدات استنادًا إلى البيئة المستهدفة وآلية تحميل الوحدات المتاحة فيها.

ملاحظة: أُهمل دعم أنظمة الوحدات القديمة (AMD وUMD وSystemJS) في TypeScript 6.0، ولم تعد مدعومة في TypeScript 7.0.

moduleResolution

تحدد الخاصية “moduleResolution” استراتيجية تحليل الوحدات. استخدم “nodenext” أو “bundler” لشيفرة TypeScript الحديثة. ولا تُستخدم الاستراتيجية “classic” إلا مع الإصدارات القديمة من TypeScript (قبل 1.6).

esModuleInterop

تسمح الخاصية “esModuleInterop” بعمليات الاستيراد الافتراضية من وحدات CommonJS التي لم تُصدّر باستخدام الخاصية “default”؛ وتوفّر هذه الخاصية طبقة توافق لضمان التوافق في JavaScript الناتجة. وبعد تمكين هذا الخيار، يمكننا استخدام import MyLibrary from "my-library" بدلًا من import * as MyLibrary from "my-library".

كانت “esModuleInterop” في الأصل خيارًا صريحًا لتجنّب التغييرات الكاسرة، لكنها أصبحت منذ وقت طويل الإعداد الافتراضي الموصى به. وقد يؤدي تعطيلها إلى مشكلات دقيقة في وقت التشغيل عند استخدام CommonJS مع ESM. ملاحظة: بدءًا من TypeScript 6.0، يكون سلوك التشغيل البيني الأكثر أمانًا هذا مفعّلًا دائمًا.

في TypeScript 6.0، أُهملت بعض خيارات التهيئة وأشكال البنية القديمة أو مرّت بمرحلة انتقالية عبر السلوك القديم. وفي TypeScript 7.0، أصبحت أخطاءً مانعة أو ذات سلوك لا يُجري أي عملية.

الخيارات المهملة التي تحوّلت إلى أخطاء مانعة ذات سلوك لا يُجري أي عملية هي:

• target: es5
• downlevelIteration
• moduleResolution: node/node10
• module: amd/umd/systemjs/none
• baseUrl
• moduleResolution: classic
• تعطيل esModuleInterop أو allowSyntheticDefaultImports
• تعطيل alwaysStrict
• الكلمة المفتاحية module في تصريحات مساحة الاسم
• asserts في عمليات الاستيراد
• /// <reference no-default-lib /> ضمن skipDefaultLibCheck
• مسارات ملفات واجهة سطر الأوامر التي تحتوي محليًا على tsconfig.json ما لم يُستخدم --ignoreConfig

jsx

تنطبق الخاصية “jsx” فقط على ملفات .tsx المستخدمة في ReactJS، وتتحكم في كيفية تصريف بُنى JSX إلى JavaScript. ومن الخيارات الشائعة “preserve” الذي يصرّف إلى ملف .jsx مع إبقاء JSX من دون تغيير، بحيث يمكن تمريره إلى أدوات مختلفة مثل Babel لإجراء المزيد من التحويلات.

skipLibCheck

تمنع الخاصية “skipLibCheck” TypeScript من التحقق من أنواع حزم الجهات الخارجية المستوردة بأكملها. وتقلل هذه الخاصية وقت تصريف المشروع. وستظل TypeScript تتحقق من شيفرتك في مقابل تعريفات الأنواع التي توفّرها هذه الحزم.

files

تشير الخاصية “files” للمصرّف إلى قائمة الملفات التي يجب تضمينها دائمًا في البرنامج.

include

تشير الخاصية “include” للمصرّف إلى قائمة الملفات التي نرغب في تضمينها. وتسمح هذه الخاصية بأنماط شبيهة بأنماط glob، مثل ”*” لأي دليل فرعي، و"" لأي اسم ملف، و”?” للمحارف الاختيارية.

exclude

تشير الخاصية “exclude” للمصرّف إلى قائمة الملفات التي ينبغي عدم تضمينها في التصريف. ويمكن أن تشمل ملفات مثل “node_modules” أو ملفات الاختبار. ملاحظة: يسمح tsconfig.json بالتعليقات.

importHelpers

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

نصائح للانتقال إلى TypeScript

بالنسبة إلى المشاريع الكبيرة، يُنصح باتباع انتقال تدريجي تتعايش فيه شيفرات TypeScript وJavaScript في البداية. ولا يمكن الانتقال إلى TypeScript دفعة واحدة إلا في المشاريع الصغيرة.

تتمثل الخطوة الأولى في هذا الانتقال في إدخال TypeScript ضمن سلسلة عملية البناء. ويمكن فعل ذلك باستخدام خيار المصرّف “allowJs”، الذي يسمح لملفات .ts و.tsx بالتعايش مع ملفات JavaScript الموجودة. وبما أن TypeScript سيلجأ إلى النوع “any” للمتغير عندما يتعذر عليه استدلال النوع من ملفات JavaScript، فيُنصح بتعطيل “noImplicitAny” في خيارات المصرّف في بداية الانتقال.

تتمثل الخطوة الثانية في التأكد من أن اختبارات JavaScript تعمل إلى جانب ملفات TypeScript، حتى تتمكن من تشغيل الاختبارات أثناء تحويل كل وحدة. وإذا كنت تستخدم Jest، ففكّر في استخدام ts-jest، الذي يتيح لك اختبار مشاريع TypeScript باستخدام Jest.

تتمثل الخطوة الثالثة في تضمين تصريحات الأنواع الخاصة بمكتبات الجهات الخارجية في مشروعك. ويمكن العثور على هذه التصريحات إما مضمّنة مع المكتبات أو على DefinitelyTyped. ويمكنك البحث عنها باستخدام https://www.typescriptlang.org/dt/search وتثبيتها باستخدام:

npm install --save-dev @types/package-name

أو

yarn add --dev @types/package-name

تتمثل الخطوة الرابعة في الانتقال وحدةً تلو الأخرى باتباع نهج من الأسفل إلى الأعلى، مع تتبّع مخطط التبعيات بدءًا من الأوراق. والفكرة هي البدء بتحويل الوحدات التي لا تعتمد على وحدات أخرى. ولعرض مخططات التبعيات مرئيًا، يمكنك استخدام أداة “madge”.

من الوحدات المرشحة جيدًا لهذه التحويلات الأولية دوال الأدوات المساعدة والشيفرة المرتبطة بواجهات API الخارجية أو المواصفات. ومن الممكن توليد تعريفات أنواع TypeScript تلقائيًا من عقود Swagger أو مخططات GraphQL أو JSON لتضمينها في مشروعك.

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

أثناء الانتقال، امتنع عن إعادة هيكلة الشيفرة وركّز فقط على إضافة الأنواع إلى وحداتك.

تتمثل الخطوة الخامسة في تفعيل “noImplicitAny”، ما سيفرض معرفة جميع الأنواع وتعريفها، ويوفر تجربة أفضل لاستخدام TypeScript في مشروعك.

أثناء الانتقال، يمكنك استخدام التوجيه @ts-check، الذي يفعّل التحقق من أنواع TypeScript داخل ملف JavaScript. يوفر هذا التوجيه إصدارًا متساهلًا من التحقق من الأنواع، ويمكن استخدامه في البداية لتحديد المشكلات في ملفات JavaScript. وعندما يُضمَّن @ts-check في ملف، ستحاول TypeScript استدلال التعريفات باستخدام تعليقات بأسلوب JSDoc. ومع ذلك، فكّر في استخدام تعليقات JSDoc التوضيحية في مرحلة مبكرة جدًا من الانتقال فقط.

فكّر في إبقاء القيمة الافتراضية للخيار noEmitOnError في ملف tsconfig.json على false. سيسمح لك ذلك بإخراج شيفرة JavaScript المصدرية حتى عند الإبلاغ عن أخطاء.