У проектах що використовують TypeScript, файл tsconfig.json слугує для конфігурації компілятора TSC. Простіше кажучи, цей файл визначає правила за якими ваш вихідний TypeScript код, буде трансформований у JavaScript.
Структура файлу tsconfig.json
У структурі файлу tsconfig.json можна виокремити дві основні складові частини:
- Опції що знаходяться у секції compilerOptions, котрі містять налаштування параметрів компіляції.
- Секція root (корінь файлу) – містить такі опції як extends, files, include та exclude. Тут вказують шлях до файлу, з якого слід успадковувати опції (extends), а також визначають файли, котрі обробляються/ігноруються компілятором.
Приклад простого файлу tsconfig.json:
{
"compilerOptions": {
"target": "ES6",
"module": "ES6",
"strict": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}Секція compilerOptions
Цей розділ файлу tsconfig.json, містить параметри котрі визначають яким чином компілятор обробляє вихідний код на TypeScript. Розглянемо деякі основні опції.
target
Визначає цільову версію JavaScript, у яку буде компілюватись код TypeScript. Приклади значень: ES5, ES6, ES2020, тощо.
module
Модульна система, яку буде використовувати зібраний додаток. Приклади значень: CommonJS, ES6, ESNext. Обране значення залежить від вимог проекту та середовища, в якому буде працювати код. У сучасних проектах часто використовують ES6 або ESNext. Про модулі може бути корисним ознайомитись за посиланням: Модулі у Node.js: CommonJS та ES Modules
“strict”: true
Вмикає всі опції суворої перевірки типів. Наприклад noImplicitAny (заборона неявного типу any), або strictNullChecks (гарантує обробку null та undefined як окремих типів, запобігаючи спробам випадкових операцій над потенційно порожніми значеннями).
“noImplicitAny”: true
Забороняє автоматичне присвоєння змінним і параметрам типу any. Це налаштування змушує явно визначати типи, знижуючи ризик несподіваної поведінки.
outDir
Вказує вихідний каталог для скомпільованих файлів JavaScript. Наприклад значення dist означає, що буде створено каталог dist, куди будуть складатись скомпільовані файли. Якщо значення для цієї опції не вказано, то всі скомпільовані файли будуть повторювати структуру вихідних файлів.
Приклад значення: "outDir": "./dist"
rootDir
Вказує на кореневу директорію вихідних файлів проекту, завдяки чому компілятор знає де шукати вихідні файли TypeScript. Це допомагає зберігати усі файли вихідного коду в одному каталозі, виокремивши від іншого коду.
Приклад значення: "rootDir": "src"
“incremental”: true
Підходить для великих кодових баз або ітераційних проектів, де між збірками змінюється лише частина коду. Коли цю опцію увімкнуто, TypeScript кешує попередню збірку, дозволяючи пропускати перекомпіляцію файлів які не змінились, тим самим заощаджуючи час.
“sourceMap”: true
Вмикає генерацію мапи коду, простіше кажучи зв’язок коду на TypeScript з результуючим JavaScript. Це спрощує процес налагодження в інструментах (VS Code, DevTools, тощо). Без прив’язки налагодження ускладнюється, тому що помилки посилаються на згенерований JavaScript код, а не оригінальний TypeScript.
“skipLibCheck”: true
Вмикає пропуск перевірки типів для сторонніх бібліотек, таким чином зменшуючи навантаження, особливо якщо використовується багато сторонніх бібліотек. Це може прискорити процес компіляції без шкоди для безпеки вашого коду, оскільки передбачається, що бібліотеки вже добре протестовані.
noUnusedParameters та noUnusedLocals
Перевірка на невикористані параметри та локальні змінні. Рекомендується вмикати ці опції для підтримки чистоти коду, але іноді є сенс тимчасово їх вимикати (встановивши значення false), особливо під час рефакторингу.
“noImplicitOverride”: true
Якщо увімкнуто noImplicitOverride, будь-які методи котрі перевизначають методи батьківського класу, повинні використовувати ключове слово override. Це полегшує читання і налагодження коду, особливо у великих проектах.
“esModuleInterop”: true
У TypeScript деякі модулі вимагають спеціальної обробки взаємодії між модулями ES і CommonJS. Увімкнення опції esModuleInterop, дозволяє імпортувати пакети CommonJS як ES6, що може спростити інтеграцію бібліотек.
“resolveJsonModule”: true
Дає змогу імпортувати файли JSON як модулі. Імпорт JSON-файлів часто потрібен для конфігурації, локалізації, використання тестових даних, тощо. Увімкнувши resolveJsonModule, можна безпосередньо імпортувати JSON, а TypeScript автоматично призначить йому тип any.
“forceConsistentCasingInFileNames”: true
Вмикає режим чутливості до регістру (case-sensitive) для імпорту файлів, запобігаючи таким чином появі прихованих помилок і проблем із сумісністю, особливо між Unix і Windows.
“allowUnreachableCode”: false
Вмикає відображення помилок при виявленні недоступного коду. Приклад:
function fn(n: number) {
if (n > 5) {
return true;
} else {
return false;
}
return true;
// Error: Unreachable code detected.
}“noFallthroughCasesInSwitch”: true
Запобігає непередбачуваній поведінці в операторах switch, активуючи помилку якщо перехід від однієї гілки до наступної, відбувається без явного використання операторів break, return або throw.
Секція root
extends
Вказує шлях до файлу з якого потрібно успадкувати опції. Здебільшого слугує інструментом упорядкування, даючи змогу розділити опції по окремим файлам за певною логікою, щоб уникнути їх змішування.
При використанні цієї опції, побачити підсумкову об’єднану версію конфігураційного файлу, можна за допомогою команди tsc --showConfig.
files
Ця опція дозволяє вказати список конкретних файлів для компіляції. Підходить для зовсім маленьких проектів з кількох файлів. Приклад:
{
"compilerOptions": {},
"files": ["core.ts", "app.ts"]
}include
Якщо опцію files не вказано у tsconfig.json, TypeScript використовує цю опцію для пошуку файлів котрі буде компілювати. Якщо include також не вказано, то її значення буде неявно оголошено як ["**/*"] (тобто пошук файлів здійснюватиметься у всіх папках, що не є оптимальним рішенням в плані продуктивності). Кращим рішенням буде явно вказувати шляхи в include, при цьому можна прописувати як шляхи до конкретних файлів, так і шаблони шляхів (наприклад ./src).
exclude
Опція exclude виключає з пошуку для компіляції зайві шляхи або файли, які були додані директивою include. За замовчуванням вона містить шляхи менеджерів пакетів (наприклад npm), оскільки модулі у них не потребують компіляції. Крім цього, TypeScript ігноруватиме папку з опції outDir (якщо її вказано), до якої поміщаються зібрані артефакти збірки.
Кілька правил стосовно опції exclude:
- В разі додавання своїх значень до exclude, необхідно також відновити значення за замовчуванням (оскільки користувацькі значення не об’єднуються зі значеннями за замовчуванням). Іншими словами, необхідно явно вказати корінь модулів свого пакетного менеджера.
- Опція exclude не може виключити файли, зазначені у files.
- Опція exclude не може виключити файли, якщо вони імпортуються в інших файлах котрі не виключені.
Команда tsc –init
Попередньо може бути корисним ознайомитись: TypeScript – вступ та початок роботи
Для автоматичної генерації типового файлу tsconfig.json, можна скористатись командою tsc --init, виконавши її в корені проекту.
Сторінка документації tsconfig.json