tsconfig.json في TypeScript

مقدمة

وجود ملفٍّ باسم ‎tsconfig.json‎ في مجلّدٍ ما إشارةٌ إلى أنّ المجلّد هو جذر (root) مشروع TypeScript. يُحدِّد الملفّ ‎tsconfig.json‎ الملفات الجذر (root files) وخيارات الترجمة المطلوبة لترجمة المشروع. يُترجم المشروع بإحدى الطريقتين التاليتين:

• عبر استخدام أداة ‎tsc‎ دون أي ملفّات مُدخلَة (input files): في هذه الحالة يبحث المترجم عن الملف ‎tsconfig.json‎ بدءًا من المجلد الحالي ثمّ الصعود للأعلى في سلسلة المجلدات الآباء (parent directory chain).
• عبر استخدام أداة ‎tsc‎ دون أي ملفّات مُدخلَة وخيار سطر الأوامر ‎--project‎ (أو ‎-p‎ اختصارًا) الذي يُحدِّد مسار مجلّد يحتوي على ملفّ ‎tsconfig.json‎، أو يُحدِّد مسار ملفّ ‎.json‎ صالحٍ يحتوي على الإعدادات.

عندما تُحدَّد الملفّات المدخلَة على سطر الأوامر، فستُتَجاهَل ملفّات ‎tsconfig.json‎.

أمثلة

هذه أمثلة على ملفّات ‎tsconfig.json‎:

• استخدام الخاصية ‎"files"‎:

{
    "compilerOptions": {
        "module": "commonjs",
        "noImplicitAny": true,
        "removeComments": true,
        "preserveConstEnums": true,
        "sourceMap": true
    },
    "files": [
        "core.ts",
        "sys.ts",
        "types.ts",
        "scanner.ts",
        "parser.ts",
        "utilities.ts",
        "binder.ts",
        "checker.ts",
        "emitter.ts",
        "program.ts",
        "commandLineParser.ts",
        "tsc.ts",
        "diagnosticInformationMap.generated.ts"
    ]
}

• استعمال الخاصيتين ‎"include"‎ و‎"exclude"‎:

    {
        "compilerOptions": {
            "module": "system",
            "noImplicitAny": true,
            "removeComments": true,
            "preserveConstEnums": true,
            "outFile": "../../built/local/tsc.js",
            "sourceMap": true
        },
        "include": [
            "src/**/*"
        ],
        "exclude": [
            "node_modules",
            "**/*.spec.ts"
        ]
    }

يمكن التخلّي عن الخاصية ‎"compilerOptions"‎، وإذا لم تُحدَّد فستُستَخدَم إعدادات المترجم الافتراضية. انظر قائمة إعدادات المترجم الكاملة للاستزادة.

تستقبل الخاصية ‎"files"‎ قائمةَ مسارات نسبية (relative) أو مسارات مطلقة (absolute) تشير إلى الملفات. وتستقبل الخاصيتان ‎"include"‎، و‎"exclude"‎ أنماط ملفّاتٍ مشابهة لنمط glob. وهذه قائمة أحرف البدل (wildcards) المدعومة:

• ‎*‎ يوافق نمطًا عديم المحارف (صفر محارف) أو أكثر من ذلك (محرف واحد أو أكثر)، مع استثناء فواصل المجلّدات (directory separators).
• ‎?‎ يوافق أي محرف واحدٍ (مع استثناء فواصل المجلّدات).
• ‎**/‎ يوافق أي مجلدٍ فرعي تعاوديا (recursively).

إذا كان جزء من نمط glob يشمل ‎*‎ أو ‎.*‎ فقط، فهذا يعني أن الملفات ذات الامتدادات المدعومة هي وحدها ستُضمَّن (مثل ‎.ts‎، و‎.tsx‎، و‎.d.ts‎ افتراضيًّا، إضافةً إلى ‎.js‎، و‎.jsx‎، إذا كان الخيار ‎allowJs‎ مفعّلًا بالقيمة ‎true‎).

إذا لم تُحدّد الخاصيتان ‎"files"‎ و‎"include"‎، فسيُضمِّن المترجم افتراضيًّا جميع ملفّات TypeScript (أي ‎.ts‎، و‎.d.ts‎، و‎.tsx‎) الموجودة في المجلّد الذي يحتوي على الملفّ ‎tsconfig.json‎ ومجلّداته الفرعية، مع استثناء الملفّات المُستثناة باستخدام الخاصية ‎"exclude"‎. تُضمَّنُ ملفّات JavaScript (أي ‎.js‎ و‎.jsx‎) إذا ضُبِطَت قيمة ‎allowJs‎ إلى ‎true‎. إذا حُدِّدَت الخاصية ‎"files"‎ أو الخاصية ‎"include"‎، فسيُضمِّن المترجم اتحادَ (union) الملفاتِ التي تُضمَّن عبر هاتين الخاصيتين. تُستثنَى الملفات في المجلّد المُحدَّد في خيار المترجم ‎"outDir"‎ ما دامت الخاصيّة ‎"exclude"‎ غيرَ مُحدَّدَةٍ.

يُمكن ترشيح (filter) الملفاتِ التي تُضمِّنها الخاصية ‎"include"‎ بالخاصية ‎"exclude"‎. لكنّ الملفّات التي تُضمَّن صراحةً باستخدام الخاصية ‎"files"‎ لا تخضع للاستثناء من طرف ‎"exclude"‎ وتُضمَّن دائمًا بغض النظر عن وجودها في قائمة الخاصية ‎"exclude"‎ من عدمه. تَستثنِي الخاصية ‎"exclude"‎ افتراضيًّا المجلدات ‎node_modules‎، و‎bower_components‎، و‎jspm_packages‎، و‎<outDir>‎ عندما لا تُحدَّد.

تُضمَّن كذلك جميع الملفّات المشار إليها عن طريق الملفّات المُضمَّنَة عبر الخاصيتين ‎"files"‎ أو ‎"include"‎. وبالمثل، إذا أشار الملفُّ (أو أحال [reference]) ‎A.ts‎ إلى الملفّ ‎B.ts‎، فعندئذٍ لا يمكن استثناء الملفّ ‎B.ts‎ إلا إذا كان الملفّ ‎A.ts‎ موجودًا كذلك في قائمة ‎"exclude"‎.

لاحظ أن المترجم لا يُضمِّن الملفّات التي يمكن أن تكون ملفَّاتٍ مُخرجَة، مثلًا، إذا كان المُدخَل يُضمِّن ‎index.ts‎، فهذا يعني استثناءَ الملفّ ‎index.d.ts‎، والملفّ ‎index.js‎. لا يُنصَح عمومًا بوضع ملفّات تختلف في الامتداد فقط (أي لها نفس الاسم مثل ‎index.js‎‎ و‎index.ts‎‎) بجانب بعضها البعض.

يمكن لملفّ ‎tsconfig.json‎ أن يكون فارغًا، ما يعني أنّ المترجم سيترجم جميع الملفّات التي تُضمَّن افتراضيًّا (كما هو موضح أعلاه) مع خيارات المترجم الافتراضية.

خيارات المترجم التي تُحدَّد في سطر الأوامر تُغطّي (override) على تلك التي تُحدَّد في ملفّ ‎tsconfig.json‎.

‎@types‎، و‎typeRoots‎، و‎types‎

تكون جميع حزم ‎@types‎ المرئيّة مُضمَّنةً في الترجمة. تُعدّ الحزم الموجودة في ‎node_modules/@types‎ داخل أي مجلّد مُحيطٍ مرئيّةً؛ هذا يعني خصوصًا الحزمَ الموجودة داخل ‎./node_modules/@types/‎، و‎../node_modules/@types/‎، و‎../../node_modules/@types/‎، وهكذا.

إذا حُدِّدت الخاصية ‎typeRoots‎، فالحزم الموجودة في ‎typeRoots‎ هي وحدها التي ستُضمَّن، مثلًا:

{
   "compilerOptions": {
       "typeRoots" : ["./typings"]
   }
}

سيُضمِّن ملفّ الإعدادات هذا جميع الحزم الموجودة داخل ‎./typings‎، ولن يُضمِّن أي حزم موجودة داخل ‎./node_modules/@types‎.

إذا حُدِّدَت الخاصية ‎types‎، فالحزم الموجودة في قائمتها هي وحدها التي ستُضمَّن، مثلًا:

{
   "compilerOptions": {
       "types" : ["node", "lodash", "express"]
   }
}

ملفّ ‎tsconfig.json‎ هذا سيُضمِّن فقط ‎./node_modules/@types/node‎، و‎./node_modules/@types/lodash‎، و‎./node_modules/@types/express‎. أمّا الحزم الأخرى الموجودة في ‎node_modules/@types/*‎ فلن تُضمَّن.

حزم ‎الأنواع (types package)‎ هي مجلّدات تحتوي على ملفّ باسم ‎index.d.ts‎ أو مجلّد يحتوي على ملفّ ‎package.json‎ يمتلك الحقل ‎types‎.

حدِّد الخاصية ‎"types": []‎ لتعطيل تضمين حزم ‎@types‎ التلقائي.

تذكّر أن التضمين التلقائي مهم فقط إذا كنت تستعمل ملفّات ذات تصريحات عامّة (global declarations)، على عكس الملفّات المُصرَّح عنها كوحدات (modules). إذا كنت تستخدم مثلًا جملة ‎import "foo"‎، فستبحث TypeScript عن الحزمة ‎foo‎ في مجلّد ‎node_modules‎ ومجلّد ‎node_modules/@types‎.

وراثة الإعدادات باستخدام الخاصية ‎extends‎

يمكن لملفّ ‎tsconfig.json‎ أن يرث الإعدادات من ملف آخر باستخدام الخاصية ‎extends‎.

الخاصية ‎extends‎ هي خاصيةٌ في المستوى الأعلى في ملف ‎tsconfig.json‎ (بجانب كل من ‎compilerOptions‎، و‎files‎، و‎include‎، و‎exclude‎). قيمة الخاصية ‎extends‎ هي سلسلة نصية تحتوي على مسار يشير إلى ملف إعداداتٍ آخر للوراثة منه.

تُحمَّل الإعدادات من الملفّ الأساس أولًا، ثمّ تُغطَّى بعد ذلك من طرف الإعدادات الموجودة في ملفّ الإعدادات الوارث. إذا حدثت دورانيّةٌ (الوراثة من ملفٍّ يرث هو الآخر من الملفّ الوارث في نفس الوقت مثلًا) فسيُطلِق المترجم خطأ.

قيم كل من ‎files‎، و‎include‎، و‎exclude‎ في ملف الإعدادات الوارث تُغطّي على تلك الموجودة في ملفّ الإعدادات الأساس.

جميع المسارات النسبية الموجودة في ملف الإعدادات تُقرَّر (resolved) نسبةً إلى ملف الإعدادات الذي تأصّلت منه.

على سبيل المثال:

‎configs/base.json‎:

{
  "compilerOptions": {
    "noImplicitAny": true,
    "strictNullChecks": true
  }
}

‎tsconfig.json‎:

{
  "extends": "./configs/base",
  "files": [
    "main.ts",
    "supplemental.ts"
  ]
}

‎tsconfig.nostrictnull.json‎

{
  "extends": "./tsconfig",
  "compilerOptions": {
    "strictNullChecks": false
  }
}

‎compileOnSave‎

تحديد الخاصيّة ‎compileOnSave‎‎ على المستوى الأعلى يُشير لبيئة التطوير (IDE) إلى توليد جميع الملفّات لملفّ ‎tsconfig.json‎ عند الحفظ:

{
   "compileOnSave": true,
   "compilerOptions": {
       "noImplicitAny" : true
   }
}

هذه الميّزة مدعومة حاليًّا في Visual Studio 2015 مع TypeScript 1.8.4 وما تلاها، وكذلك في الإضافة atom-typescript.

المخطّط (Schema)

هذا مُخطَّط الملفّ ‎tsconfig.json‎.

مصادر

• صفحة tsconfig.json في توثيق TypeScript الرسمي.