Пошук уроків, статей та іншого контенту
Створите tsconfig.json і налаштуєте цільову версію JavaScript, режим strict, каталог результатів та перевірку файлів.
tsconfig.jsontsconfig.json — це конфігураційний файл TypeScript-проєкту. У ньому описують, як компілятор має:
перевіряти TypeScript-код;
перетворювати його на JavaScript;
обирати версію JavaScript у результаті;
визначати вхідні файли;
зберігати згенеровані файли.
Без цього файла TypeScript використовує значення за замовчуванням, які можуть не відповідати вимогам проєкту.
Якщо TypeScript встановлено в проєкті, файл можна створити командою:
npx tsc --initКоманда створить tsconfig.json із великою кількістю закоментованих параметрів. Для невеликого проєкту часто зручніше замінити його мінімальною конфігурацією.
Створимо таку структуру:
project/
├── src/
│ └── index.ts
├── dist/
└── tsconfig.jsonПриклад базового tsconfig.json:
{
"compilerOptions": {
"target": "ES2020",
"strict": true,
"outDir": "./dist"
},
"include": ["src/**/*.ts"],
"exclude": ["node_modules", "dist"]
}compilerOptionsПараметр compilerOptions містить налаштування компілятора. Саме тут задають цільову версію JavaScript, режим суворої перевірки та каталог для результатів компіляції.
targettarget визначає версію JavaScript, у яку TypeScript компілюватиме код.
{
"compilerOptions": {
"target": "ES2020"
}
}Наприклад, можна використовувати:
"ES5" — для дуже старого середовища;
"ES2015" або "ES6" — для сучаснішого, але вже старішого JavaScript;
"ES2020";
"ES2022";
"ESNext" — найновіші можливості, які підтримує поточна версія TypeScript.
Розглянемо TypeScript-код:
const numbers = [1, 2, 3];
const doubled = numbers.map((number) => number * 2);
console.log(doubled);Якщо вибрати старішу цільову версію, TypeScript може перетворити сучасний синтаксис на сумісніший JavaScript. Типи TypeScript у вихідному JavaScript не залишаються — вони видаляються під час компіляції.
target не перевіряє, чи доступні всі API в середовищі виконання. Наприклад, вибір старішого target не додає автоматично поліфіли для нових методів JavaScript.
Для сучасного Node.js-проєкту часто підходить:
{
"compilerOptions": {
"target": "ES2020"
}
}Точне значення залежить від середовища, у якому виконуватиметься результат.
strictstrict вмикає суворий режим перевірки TypeScript:
{
"compilerOptions": {
"strict": true
}
}Це не одна окрема перевірка, а набір суворих правил. Зокрема, TypeScript уважніше працює з:
значеннями null і undefined;
параметрами функцій;
типами змінних;
наслідуванням класів;
доступом до властивостей об’єктів.
Наприклад:
function formatUserName(name: string): string {
return name.toUpperCase();
}
const userName: string | undefined = undefined;
formatUserName(userName);Увімкнений strict повідомить про помилку, оскільки змінна userName може мати значення undefined, а функція приймає лише string.
Код потрібно виправити, явно перевіривши значення:
function formatUserName(name: string): string {
return name.toUpperCase();
}
const userName: string | undefined = undefined;
if (userName !== undefined) {
console.log(formatUserName(userName));
}Суворий режим допомагає виявляти помилки під час розробки, а не після запуску програми. Для нових проєктів зазвичай варто одразу використовувати "strict": true.
outDiroutDir визначає каталог, у який TypeScript записує скомпільовані JavaScript-файли:
{
"compilerOptions": {
"outDir": "./dist"
}
}Якщо файл розташований у src/index.ts, після компіляції результат зазвичай буде розташований у dist/index.js.
Вхідний TypeScript-код і згенерований JavaScript залишаються розділеними:
project/
├── src/
│ └── index.ts
├── dist/
│ └── index.js
└── tsconfig.jsonКаталог dist часто очищають перед новою збіркою або не додають до системи контролю версій, оскільки його вміст можна згенерувати повторно.
includeinclude визначає файли, які TypeScript має включити до проєкту:
{
"include": ["src/**/*.ts"]
}Запис src/**/*.ts означає:
почати пошук у каталозі src;
врахувати файли з розширенням .ts;
врахувати файли також у вкладених каталогах.
Якщо використовуються TypeScript-файли з JSX, для них потрібен шаблон із розширенням .tsx:
{
"include": ["src/**/*.ts", "src/**/*.tsx"]
}excludeexclude виключає каталоги або файли з перевірки:
{
"exclude": ["node_modules", "dist"]
}node_modules містить залежності, а dist — уже згенерований результат. Їх не потрібно повторно перевіряти як власний вихідний код.
Якщо include не вказано, TypeScript може включити до проєкту більше файлів, ніж очікується. Тому явне визначення include робить конфігурацію зрозумілішою.
exclude не є абсолютною забороною для всіх випадків. Якщо файл прямо імпортується з включеного файла або явно вказаний в іншій конфігурації, TypeScript може все одно врахувати його.
Створимо файл src/index.ts:
interface User {
id: number;
name: string;
}
function createGreeting(user: User): string {
return `Привіт, ${user.name}!`;
}
const user: User = {
id: 1,
name: "Олена"
};
console.log(createGreeting(user));Тепер використаємо конфігурацію:
{
"compilerOptions": {
"target": "ES2020",
"strict": true,
"outDir": "./dist"
},
"include": ["src/**/*.ts"],
"exclude": ["node_modules", "dist"]
}Запустимо компіляцію з каталогу проєкту:
npx tscЯкщо помилок немає, TypeScript створить файл:
dist/index.jsЗапустити скомпільований JavaScript можна командою:
node dist/index.jsРезультат:
Привіт, Олена!Іноді потрібно лише перевірити типи, не генеруючи файли. Для цього використовують прапорець --noEmit:
npx tsc --noEmitЦя команда:
читає налаштування з tsconfig.json;
перевіряє файли, визначені через include;
показує помилки типів;
не створює файли в dist.
Такий режим зручний для окремої перевірки коду або автоматичних перевірок у процесі розробки.
За замовчуванням TypeScript може створити JavaScript навіть тоді, коли в TypeScript-коді є помилки. Щоб заборонити створення неповного результату, додайте noEmitOnError:
{
"compilerOptions": {
"target": "ES2020",
"strict": true,
"outDir": "./dist",
"noEmitOnError": true
},
"include": ["src/**/*.ts"],
"exclude": ["node_modules", "dist"]
}Тепер принаймні одна помилка типів означатиме, що нові JavaScript-файли не будуть створені.
Якщо команда tsc запускається без параметрів, TypeScript автоматично шукає tsconfig.json у поточному каталозі:
npx tscЩоб явно вказати файл конфігурації, використовуйте --project:
npx tsc --project tsconfig.jsonЦе корисно, коли в проєкті є кілька конфігурацій, наприклад окремі для розробки та перевірки.
target додасть поліфілиtarget змінює синтаксис JavaScript, але не додає реалізації відсутніх API. Якщо середовище не підтримує певний метод або об’єкт, для цього потрібні окремі засоби сумісності.
dist до перевіркиЯкщо каталог із результатами компіляції знаходиться серед файлів проєкту, його варто виключити:
{
"exclude": ["dist"]
}Інакше згенеровані файли можуть перевірятися повторно.
strict через одну помилкуСуворий режим може вимагати виправлення вже наявного коду, але він допомагає зменшити кількість помилок під час виконання. Не варто вимикати його без конкретної причини.
tsc не з каталогу проєктуЯкщо команда запускається не там, де розташований tsconfig.json, TypeScript може не знайти потрібну конфігурацію. У такому випадку потрібно перейти до каталогу проєкту або використати --project.
tsconfig.json описує правила перевірки та компіляції TypeScript-проєкту.
target визначає цільову версію JavaScript.
strict: true вмикає сувору перевірку типів.
outDir задає каталог для згенерованих JavaScript-файлів.
include визначає файли, які потрібно перевіряти.
exclude виключає непотрібні каталоги, наприклад node_modules і dist.
npx tsc компілює проєкт за конфігурацією.
npx tsc --noEmit перевіряє типи без створення JavaScript.
noEmitOnError: true забороняє створення результату, якщо є помилки типів.