Пошук уроків, статей та іншого контенту
Розберете структуру tsconfig.json і навчитеся налаштовувати target, lib, outDir, rootDir та інші базові параметри.
tsconfig.jsontsconfig.json — це конфігураційний файл TypeScript-проєкту. У ньому описують:
які файли потрібно компілювати;
у який JavaScript перетворювати TypeScript;
яку версію JavaScript використовувати;
куди зберігати згенеровані файли;
які перевірки типів увімкнути.
Коли TypeScript запускається без додаткових параметрів, він шукає tsconfig.json у поточній директорії та її батьківських директоріях.
Базова команда компіляції проєкту:
tscTypeScript прочитає tsconfig.json, перевірить файли та створить JavaScript відповідно до налаштувань.
Приклад простого tsconfig.json:
{
"compilerOptions": {
"target": "ES2020",
"module": "CommonJS",
"lib": ["ES2020", "DOM"],
"rootDir": "./src",
"outDir": "./dist",
"strict": true,
"sourceMap": true
},
"include": ["src/**/*.ts"],
"exclude": ["node_modules", "dist"]
}Файл tsconfig.json підтримує коментарі, тому для прикладів можна використовувати формат JSONC. Звичайний строгий JSON коментарів не підтримує, але TypeScript коректно читає їх у конфігурації.
Конфігурація складається з двох основних частин:
compilerOptions — параметри компілятора;
include та exclude — правила вибору файлів.
targettarget визначає версію JavaScript, у яку TypeScript компілюватиме код.
{
"compilerOptions": {
"target": "ES2020"
}
}Наприклад, TypeScript може перетворити сучасний синтаксис у старішу версію JavaScript:
const numbers = [1, 2, 3];
const doubled = numbers.map((number) => number * 2);Якщо вибрати сучасний target, згенерований код залишатиметься ближчим до початкового:
{
"compilerOptions": {
"target": "ES2020"
}
}Якщо вибрати старішу версію, TypeScript може перетворити сучасні конструкції на сумісніші з нею.
Поширені значення:
ES5 — дуже стара версія JavaScript;
ES2015 або ES6 — перша велика сучасна версія JavaScript;
ES2019;
ES2020;
ES2022;
ESNext — найновіші можливості, доступні TypeScript.
target не додає відсутні можливості середовищу виконання. Наприклад, перетворення синтаксису не гарантує наявність Promise, Map або інших API у старому браузері.
liblib визначає типи стандартних можливостей JavaScript і середовища виконання, доступних TypeScript.
{
"compilerOptions": {
"lib": ["ES2020", "DOM"]
}
}У цьому прикладі TypeScript знає про:
можливості JavaScript до рівня ES2020;
браузерні об’єкти та API, наприклад document, window, console.
Наприклад:
const title = document.querySelector("h1");
if (title) {
title.textContent = "Привіт, TypeScript!";
}
const promise = Promise.resolve("Готово");Типові значення lib:
ES2020, ES2021, ES2022 — стандартні можливості відповідної версії JavaScript;
DOM — браузерні API;
DOM.Iterable — ітераційні можливості DOM;
ES2020.Promise — типи для Promise відповідної версії.
Для браузерного коду часто використовують:
{
"compilerOptions": {
"target": "ES2020",
"lib": ["ES2020", "DOM"]
}
}Для коду, який не використовує браузерні API, DOM може бути непотрібним:
{
"compilerOptions": {
"target": "ES2020",
"lib": ["ES2020"]
}
}lib описує типи API, але не додає їх реалізацію до JavaScript. Якщо середовище не підтримує певний API, це потрібно враховувати окремо.
rootDir і outDirrootDirrootDir визначає кореневу директорію файлів із початковим кодом.
{
"compilerOptions": {
"rootDir": "./src"
}
}Якщо структура проєкту така:
project/
├── src/
│ ├── index.ts
│ └── utils/
│ └── format.ts
└── tsconfig.jsonто src є коренем початкових файлів.
outDiroutDir визначає директорію, у яку TypeScript записуватиме скомпільований JavaScript.
{
"compilerOptions": {
"rootDir": "./src",
"outDir": "./dist"
}
}Структура src буде відтворена в dist:
project/
├── src/
│ ├── index.ts
│ └── utils/
│ └── format.ts
└── dist/
├── index.js
└── utils/
└── format.jsTypeScript зберігає відносні шляхи від rootDir до файлів.
modulemodule визначає формат модулів у згенерованому JavaScript.
{
"compilerOptions": {
"module": "CommonJS"
}
}Поширені значення:
CommonJS — формат, який традиційно використовує Node.js;
ES2020 або ESNext — сучасні ECMAScript-модулі;
NodeNext — режим для проєктів Node.js, які використовують сучасні правила модулів.
Вибір module має відповідати середовищу, у якому запускатиметься згенерований код.
Наприклад, для простої навчальної програми, яку запускають у Node.js у форматі CommonJS:
{
"compilerOptions": {
"target": "ES2020",
"module": "CommonJS"
}
}strictstrict вмикає сувору перевірку типів.
{
"compilerOptions": {
"strict": true
}
}За суворого режиму TypeScript знаходить більше потенційних помилок:
function printLength(value: string | null): void {
console.log(value.length);
}TypeScript повідомить про помилку, тому що value може дорівнювати null.
Потрібно спочатку перевірити значення:
function printLength(value: string | null): void {
if (value !== null) {
console.log(value.length);
}
}Для нових проєктів зазвичай варто вмикати:
{
"compilerOptions": {
"strict": true
}
}Це допомагає виявляти помилки на етапі компіляції, а не під час запуску програми.
include і excludeincludeinclude визначає, які файли потрібно включити до проєкту.
{
"include": ["src/**/*.ts"]
}Шаблон src/**/*.ts означає:
почати пошук у директорії src;
врахувати всі вкладені директорії;
вибрати файли з розширенням .ts.
Можна вказати кілька шаблонів:
{
"include": [
"src/**/*.ts",
"tests/**/*.ts"
]
}excludeexclude визначає файли та директорії, які не потрібно включати.
{
"exclude": [
"node_modules",
"dist",
"coverage"
]
}node_modules зазвичай виключають, тому що це директорія залежностей, а dist — тому що це вже згенерований код.
exclude не є абсолютною забороною для файлу. Якщо файл буде явно підключено імпортом з іншого файлу, TypeScript може додати його до програми.
sourceMapsourceMap створює файли мап відповідності між TypeScript і згенерованим JavaScript.
{
"compilerOptions": {
"sourceMap": true
}
}Наприклад, після компіляції можуть з’явитися:
dist/
├── index.js
└── index.js.mapФайл .map допомагає інструментам розробника показувати початковий TypeScript замість згенерованого JavaScript під час налагодження.
noEmitOnErrorЗа замовчуванням TypeScript може створити JavaScript навіть тоді, коли знайшов помилки типів. Щоб заборонити створення файлів із помилками, використовують noEmitOnError:
{
"compilerOptions": {
"noEmitOnError": true
}
}Тоді JavaScript не буде згенеровано, якщо компіляція завершилася помилками.
Створимо проєкт із такою структурою:
project/
├── src/
│ ├── index.ts
│ └── greeting.ts
└── tsconfig.jsonФайл src/greeting.ts:
export function createGreeting(name: string): string {
return `Привіт, ${name}!`;
}Файл src/index.ts:
import { createGreeting } from "./greeting";
const message = createGreeting("Олено");
console.log(message);Файл tsconfig.json:
{
"compilerOptions": {
"target": "ES2020",
"module": "CommonJS",
"lib": ["ES2020"],
"rootDir": "./src",
"outDir": "./dist",
"strict": true,
"sourceMap": true,
"noEmitOnError": true
},
"include": ["src/**/*.ts"],
"exclude": ["node_modules", "dist"]
}Запустіть компіляцію:
tscПісля цього з’явиться така структура:
project/
├── dist/
│ ├── greeting.js
│ ├── greeting.js.map
│ ├── index.js
│ └── index.js.map
├── src/
│ ├── index.ts
│ └── greeting.ts
└── tsconfig.jsonЗапустити скомпільовану програму можна так:
node dist/index.jsРезультат:
Привіт, Олено!Для невеликого проєкту можна почати з такої конфігурації:
{
"compilerOptions": {
"target": "ES2020",
"module": "CommonJS",
"lib": ["ES2020"],
"rootDir": "./src",
"outDir": "./dist",
"strict": true,
"sourceMap": true,
"noEmitOnError": true
},
"include": ["src/**/*.ts"],
"exclude": ["node_modules", "dist"]
}Для браузерного коду до lib можна додати DOM:
{
"compilerOptions": {
"target": "ES2020",
"lib": ["ES2020", "DOM"]
}
}distЯкщо не вказати outDir, TypeScript може створити .js-файли поруч із .ts-файлами.
Використовуйте:
{
"compilerOptions": {
"rootDir": "./src",
"outDir": "./dist"
}
}rootDir не відповідає розташуванню файлівЯкщо rootDir вказує на src, але в include потрапляють файли з іншої директорії, структура проєкту може бути некоректною або TypeScript повідомить про помилку.
Узгоджуйте ці параметри:
{
"compilerOptions": {
"rootDir": "./src"
},
"include": ["src/**/*.ts"]
}documentЯкщо код використовує браузерний API, але в lib немає DOM, TypeScript може не знати про document та window.
Виправлення:
{
"compilerOptions": {
"lib": ["ES2020", "DOM"]
}
}target додасть APItarget змінює згенерований синтаксис, але не додає реалізацію API. Наявність Promise, fetch чи інших можливостей залежить від середовища виконання та відповідних типів.
tsconfig.jsonЯкщо передати TypeScript окремий файл:
tsc src/index.tsконфігурація проєкту може не застосовуватися так, як під час запуску tsc без аргументів.
Для компіляції всього проєкту використовуйте:
tscСтворіть директорію src для TypeScript-файлів.
Визначте середовище виконання: браузер або Node.js.
Виберіть сумісний target.
Додайте потрібні типи через lib.
Вкажіть rootDir для початкових файлів.
Вкажіть outDir для згенерованого JavaScript.
Увімкніть strict.
Обмежте файли через include і exclude.
Запустіть tsc та перевірте створену директорію.
tsconfig.json описує правила компіляції TypeScript-проєкту.
target визначає версію JavaScript для згенерованого коду.
lib додає типи стандартних і середовищних API.
rootDir визначає корінь початкових файлів.
outDir визначає директорію для скомпільованого JavaScript.
module визначає формат модулів.
strict вмикає сувору перевірку типів.
include і exclude керують набором файлів проєкту.
sourceMap допомагає налагоджувати TypeScript-код.
noEmitOnError забороняє створювати JavaScript, якщо є помилки компіляції.