خيارات tsconfig مشروحة

خيارات tsconfig المهمة، مجمّعة حسب الوظيفة: تشديد فحص الأنواع، وتحديد هدف اللغة والوحدات، والتحكم في ما يُصدَّر، وربط مسارات الاستيراد، وهيكلة بناءات متعددة المشاريع، وضبط الفحوص المتبقية.

يخبر ملف tsconfig المترجم بالملفات التي يضمها ومدى صرامته. خياران يقومان بمعظم العمل: يحدد target مستوى توليد JavaScript، ويشغّل strict فحوص الأمان دفعة واحدة. الخيارات أدناه هي التي تغيّر السلوك؛ ويُشار إلى المعيّنات المفعّلة افتراضيًا. اشتقّ إعداداتك من أساس ثم تجاوز ما يختلف فقط.

جدول مرجعي · 55 إدخالات

55 of 55 rows


الصرامة
	المفتاح الرئيسي: يفعّل strictNullChecks وnoImplicitAny وعدة خيارات أخرى دفعة واحدة.
	خطأ في المعاملات والمتغيرات التي لا يمكن استنتاج نوعها (وإلا تصبح any).
	لم يعد null وundefined قابلين للإسناد إلى كل نوع؛ يجب السماح بذلك صراحةً.
	يفحص معاملات الدوال بطريقة معاكسة (contravariant)؛ يكشف أنواع معاملات callbacks غير الآمنة.
	يفحص bind وcall وapply مقابل المعاملات المصرَّح بها للدالة.
	خطأ عندما تكون خاصية صنف بلا قيمة ابتدائية ولا تُسند في المُنشئ.
	الخاصية الاختيارية { p?: T } لم تعد تقبل إسناد undefined صراحةً.
	يتطلب الكلمة المفتاحية override على الأعضاء التي تحجب عضوًا من الصنف الأساسي.
	خطأ في المتغيرات المحلية المصرَّح بها التي لا تُقرأ أبدًا.
	خطأ في معاملات الدوال المصرَّح بها التي لا تُقرأ أبدًا.
	خطأ في عبارات التعبير التي بلا أثر.
	يُمنع الوصول بالنقطة لمفاتيح توقيع الفهرسة؛ استخدم الأقواس المربعة (obj["key"]).
	خطأ عندما يُرجع مسار برمجي قيمة بينما لا يُرجع آخر.
	خطأ عندما تمر حالة switch إلى التالية بلا break.
اللغة والوحدات
	مستوى توليد JavaScript (مثل ES2022)؛ الأهداف الأحدث تعني downleveling أقل.
	واجهات API المدمجة المتاحة (مثل ES2022 وDOM وDOM.Iterable).
	نظام الوحدات المُصدَّر (مثل ESNext وCommonJS وNodeNext).
	يتبع قواعد Node الفعلية: كل ملف يختار CJS أو ESM من أقرب package.json، والواردات النسبية تحتاج امتدادات الملفات.
	كيف تُحلّ مسارات الاستيراد (مثل bundler وnode وnodenext).
	متى يُحتسب الملف وحدةً: auto (بوجود import/export) أو legacy أو force (دائمًا).
	يسمح بنمط الاستيراد الافتراضي من وحدات CommonJS (‏true افتراضيًا في معظم الإعدادات).
	يسمح بالواردات الافتراضية من وحدات تصدّر قيمًا مسماة فقط (على مستوى الأنواع فقط).
	تُصدَّر الواردات كما كُتبت حرفيًا؛ واردات الأنواع فقط يجب أن تستخدم import type‏ (TS 5).
	يتيح للواردات تحميل ملفات .json كقيم ذات أنواع.
	يضم ملفات .js كمدخلات للترجمة.
	يفحص أنواع ملفات .js أيضًا مع قراءة تعليقات JSDoc فيها؛ يستلزم allowJs.
	كيف تُترجم ‏.tsx‏: ‏react-jsx‏ (وقت تشغيل تلقائي) أو react‏ (‏React.createElement‏) أو preserve.
	يقصر حزم @types المضمّنة تلقائيًا على هذه القائمة؛ المصفوفة الفارغة لا تضمّ أيًا منها.
	مجلدات تُفحص بحثًا عن حزم @types بدلًا من كل node_modules/@types في الشجرة.
	يضمن إمكانية ترجمة كل ملف بمعزل عن غيره (تتطلبه أدوات التجميع وesbuild).
الإخراج
	المكان الذي يُكتب إليه JavaScript المترجم.
	جذر ملفات المصدر؛ يحافظ على استقرار شكل شجرة المخرجات.
	يُصدر ملفات ‏.js.map لتربط المصححات بالعودة إلى TypeScript.
	يضمّن خريطة المصدر كتعليق داخل ملف .js بدلًا من ملف ‏.js.map.
	يُصدر تصريحات الأنواع ‏‎.d.ts‏ (لازمة للمكتبات).
	يُصدر ملفات ‏‎.d.ts.map لينتقل المحرر من التصريحات إلى مصدر TypeScript.
	يُصدر ملفات ‏‎.d.ts فقط؛ ويُترك JavaScript لأداة تجميع (يتطلب declaration أو composite).
	يعيد استخدام مساعدات مثل __rest من tslib بدلًا من إصدارها في كل ملف.
	يصحح for..of وspread والتفكيك فوق المتكررات عندما يسبق الهدف ES2015.
	يزيل التعليقات من JavaScript المُصدَّر.
	فحص أنواع فقط؛ دون كتابة ملفات (يُستخدم عندما تتولى أداة تجميع الإصدار).
المسارات
	دليل أساسي لحل الوحدات غير النسبية.
	يربط بادئات الاستيراد بمواضع، مثل { "@/": ["src/"] }.
	يتعامل مع عدة أدلة كجذر افتراضي واحد للحل.
هيكل المشروع
	يعلّم المشروع كقابل للبناء لمراجع المشروع (يفعّل declaration وincremental).
	يعتمد على مشاريع tsconfig أخرى لبناءات أسرع ومعزولة.
	يحفظ معلومات البناء لتخطي الملفات غير المتغيرة في التشغيل التالي.
فحوص أخرى
	يتخطى فحص أنواع ملفات ‏‎.d.ts من أجل السرعة (‏true افتراضيًا).
	خطأ في الواردات التي تخالف حالة الأحرف الفعلية للملف.
	الوصول إلى المصفوفات والفهارس يعيد T \| undefined وليس T.
	تُنشأ حقول الصفوف عبر Object.defineProperty بدل الإسناد المباشر (‏true افتراضيًا لأهداف ES2022+).
	يفعّل صياغة الديكورات القديمة التي تستخدمها أُطر أقدم (قبل المعيار).
	يعرض أسماء الأنواع كاملة في رسائل الخطأ بدل اقتطاع الطويلة.
	خطأ عندما لا يحلّ استيراد أثر جانبي مجرد (import "./x.css") إلى شيء.
	يسمح بمسارات استيراد تنتهي بـ ‏.ts‏ (يتطلب noEmit أو emitDeclarationOnly).