Конфигурация на TypeScript: Цялостно ръководство за tsconfig.json

TypeScript, надмножество на JavaScript, въвежда статичното типизиране в динамичния свят на уеб разработката. Добре конфигурираният файл tsconfig.json е от решаващо значение за използването на пълната мощ на TypeScript. Това ръководство предоставя изчерпателен преглед на tsconfig.json, като обхваща основни опции на компилатора, настройка на проекти и разширени конфигурации.

Какво е tsconfig.json?

Файлът tsconfig.json е конфигурационен файл, който указва опциите на компилатора за проект на TypeScript. Той казва на компилатора на TypeScript как да транспилира TypeScript код в JavaScript. Този файл е от съществено значение за дефиниране на структурата на проекта, задаване на правила за компилация и осигуряване на последователност в екипа за разработка, независимо дали този екип се намира в един офис или е разпределен на няколко континента.

Създаване на файл tsconfig.json

За да създадете файл tsconfig.json, навигирайте до основната директория на вашия проект в терминала и изпълнете следната команда:

tsc --init

Тази команда генерира основен файл tsconfig.json с често използвани опции на компилатора. След това можете да персонализирате файла, за да отговаря на специфичните изисквания на вашия проект. Типичният tsconfig.json ще включва опции като compilerOptions, include и exclude.

Основни опции на компилатора

Секцията compilerOptions е сърцето на файла tsconfig.json. Тя съдържа широк набор от опции, които контролират поведението на компилатора на TypeScript. Ето някои от най-важните опции на компилатора:

`target`

Опцията target указва целевата версия на ECMAScript за генерирания JavaScript код. Често срещани стойности включват ES5, ES6 (ES2015), ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext. Изборът на правилната цел е от решаващо значение за осигуряване на съвместимост с предвидената среда на изпълнение, като например браузъри или версии на Node.js.

Пример:

{
  "compilerOptions": {
    "target": "ES2020"
  }
}

`module`

Опцията module указва стила на генериране на код за модули. Често срещани стойности включват CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020 и ESNext. Изборът на модулна система зависи от целевата среда и използвания модулен бандлър (напр. Webpack, Rollup, Parcel). За Node.js често се използва CommonJS, докато за модерни уеб приложения се предпочита ES6 или ESNext с модулен бандлър. Използването на ESNext позволява на разработчиците да се възползват от най-новите функции и оптимизации, като същевременно разчитат на бандлъра да се справи с крайния формат на модула.

Пример:

{
  "compilerOptions": {
    "module": "ESNext"
  }
}

`lib`

Опцията lib указва списък с библиотечни файлове, които да бъдат включени в компилацията. Тези библиотечни файлове предоставят дефиниции на типове за вградени JavaScript API и браузърни API. Често срещани стойности включват ES5, ES6, ES2015, ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext, DOM, WebWorker, ScriptHost, ES2015.Core, ES2015.Collection, ES2015.Iterable, ES2015.Promise, ES2015.Proxy, ES2015.Reflect, ES2015.Generator, ES2015.Symbol, ES2015.Symbol.WellKnown, ES2016.Array.Include, ES2017.object, ES2017.Intl, ES2017.SharedMemory, ES2017.String, ES2017.TypedArrays, ES2018.Intl, ES2018.Promise, ES2018.RegExp, ES2019.Array, ES2019.Object, ES2019.String, ES2019.Symbol, ES2020.BigInt, ES2020.Promise, ES2020.String, ES2020.Symbol.WellKnown, ES2021.Promise, ES2021.String, ES2021.WeakRef, ES2022.Error, ES2022.Object, ES2022.String и много други. Изборът на подходящи библиотеки гарантира, че компилаторът на TypeScript разполага с необходимата информация за типовете за целевата среда. Използването на библиотеката DOM позволява на проекта да компилира код, който използва специфични за браузъра API без грешки в типовете.

Пример:

{
  "compilerOptions": {
    "lib": ["ES2020", "DOM"]
  }
}

`allowJs`

Опцията allowJs позволява на компилатора на TypeScript да компилира JavaScript файлове заедно с TypeScript файлове. Това е полезно за постепенно мигриране на съществуващи JavaScript проекти към TypeScript. Задаването на тази опция на true позволява на компилатора да обработва .js файлове, което позволява постепенно възприемане на TypeScript в рамките на проект.

Пример:

{
  "compilerOptions": {
    "allowJs": true
  }
}

`jsx`

Опцията jsx указва как да се обработва JSX синтаксисът. Често срещани стойности включват preserve, react, react-native и react-jsx. preserve запазва JSX синтаксиса в изходния код, докато react трансформира JSX в извиквания на React.createElement. react-jsx използва новата JSX трансформация, въведена в React 17, която не изисква импортиране на React. Изборът на правилната JSX опция е от решаващо значение за проекти, използващи React или други библиотеки, базирани на JSX.

Пример:

{
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}

`declaration`

Опцията declaration генерира съответните .d.ts декларационни файлове за всеки TypeScript файл. Декларационните файлове съдържат информация за типовете и се използват от други TypeScript проекти за консумиране на компилирания код. Генерирането на декларационни файлове е от съществено значение за създаването на библиотеки и модули за многократна употреба. Тези файлове позволяват на други TypeScript проекти да разберат типовете и интерфейсите, изложени от библиотеката, без да е необходимо да компилират оригиналния изходен код.

Пример:

{
  "compilerOptions": {
    "declaration": true
  }
}

`sourceMap`

Опцията sourceMap генерира source map файлове, които свързват генерирания JavaScript код с оригиналния TypeScript код. Source map-овете са от съществено значение за отстраняване на грешки в TypeScript код в браузъри и други среди. Когато възникне грешка в JavaScript кода, source map-ът позволява на разработчика да види съответния TypeScript код в дебъгера, което улеснява идентифицирането и отстраняването на проблема.

Пример:

{
  "compilerOptions": {
    "sourceMap": true
  }
}

`outDir`

Опцията outDir указва изходната директория за генерираните JavaScript файлове. Тази опция помага за организиране на изходния код на проекта, като разделя изходния код от компилирания код. Използването на outDir улеснява управлението на процеса на билдване и внедряването на приложението.

Пример:

{
  "compilerOptions": {
    "outDir": "dist"
  }
}

`rootDir`

Опцията rootDir указва основната директория на проекта на TypeScript. Компилаторът използва тази директория като основа за разрешаване на имената на модулите. Тази опция е особено важна за проекти със сложна структура на директориите. Правилното задаване на rootDir гарантира, че компилаторът може да намери всички необходими модули и зависимости.

Пример:

{
  "compilerOptions": {
    "rootDir": "src"
  }
}

`strict`

Опцията strict активира всички опции за строга проверка на типовете. Това е силно препоръчително за нови проекти на TypeScript, тъй като помага за ранно откриване на потенциални грешки в процеса на разработка. Активирането на строгия режим налага по-строги правила за проверка на типовете, което води до по-здрав и лесен за поддръжка код. Най-добра практика е да се активира строгият режим във всички нови проекти на TypeScript.

Пример:

{
  "compilerOptions": {
    "strict": true
  }
}

`esModuleInterop`

Опцията esModuleInterop позволява съвместимост между CommonJS и ES модули. Това е важно за проекти, които използват и двата вида модули. Когато esModuleInterop е активирана, TypeScript автоматично ще се справи с разликите между CommonJS и ES модулите, което улеснява импортирането и експортирането на модули между двете системи. Тази опция е особено полезна при работа с библиотеки на трети страни, които могат да използват различни модулни системи.

Пример:

{
  "compilerOptions": {
    "esModuleInterop": true
  }
}

`moduleResolution`

Опцията moduleResolution указва как TypeScript разрешава импортирането на модули. Често срещани стойности включват Node и Classic. Стратегията за разрешаване на модули Node е по подразбиране и се основава на алгоритъма за разрешаване на модули на Node.js. Стратегията за разрешаване на модули Classic е по-стара и по-рядко използвана. Използването на стратегията за разрешаване на модули Node гарантира, че TypeScript може правилно да разрешава импортирането на модули в среда на Node.js.

Пример:

{
  "compilerOptions": {
    "moduleResolution": "Node"
  }
}

`baseUrl` и `paths`

Опциите baseUrl и paths се използват за конфигуриране на разрешаването на модули за не-относителни импорти. Опцията baseUrl указва основната директория за разрешаване на не-относителни имена на модули. Опцията paths ви позволява да свързвате имена на модули с конкретни местоположения във файловата система. Тези опции са особено полезни за проекти със сложна структура на директориите и за опростяване на импортирането на модули. Използването на baseUrl и paths може да направи кода по-четлив и лесен за поддръжка.

Пример:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}

Опции Include и Exclude

Опциите include и exclude указват кои файлове да бъдат включени в компилацията и кои файлове да бъдат изключени. Тези опции използват glob шаблони за съвпадение на имената на файловете. Използването на include и exclude ви позволява да контролирате кои файлове се обработват от компилатора на TypeScript, подобрявайки производителността на билдването и намалявайки грешките. Най-добра практика е изрично да се указват файловете, които да бъдат включени в компилацията.

Пример:

{
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Опция Extends

Опцията extends ви позволява да наследявате опции на компилатора от друг tsconfig.json файл. Това е полезно за споделяне на общи настройки на конфигурацията между няколко проекта или за създаване на базови конфигурации. Използването на опцията extends насърчава повторната употреба на код и намалява дублирането. Най-добра практика е да се създават базови конфигурации и да се разширяват в отделни проекти.

Пример:

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["src/**/*"]
}

Разширени конфигурации

Освен основните опции на компилатора, tsconfig.json поддържа разширени конфигурации за специализирани сценарии.

Инкрементална компилация

За големи проекти инкременталната компилация може значително да подобри времето за билдване. TypeScript може да кешира резултатите от предишни компилации и да прекомпилира само файловете, които са се променили. Активирането на инкрементална компилация може драстично да намали времето за билдване на големи проекти. Това е особено важно за проекти с голям брой файлове и зависимости.

{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}

Референции към проекти

Референциите към проекти ви позволяват да структурирате големи TypeScript проекти в по-малки, независими модули. Това може да подобри времето за билдване и организацията на кода. Използването на референции към проекти може да направи големите проекти по-управляеми и лесни за поддръжка. Най-добра практика е да се използват референции към проекти за големи и сложни проекти.

{
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "./module1" },
    { "path": "./module2" }
  ]
}

Персонализирани дефиниции на типове

Понякога може да се наложи да предоставите дефиниции на типове за JavaScript библиотеки, които нямат такива. Можете да създадете персонализирани .d.ts файлове, за да дефинирате типовете за тези библиотеки. Създаването на персонализирани дефиниции на типове ви позволява да използвате JavaScript библиотеки във вашия TypeScript код, без да жертвате безопасността на типовете. Това е особено полезно при работа с наследен JavaScript код или библиотеки, които не предоставят собствени дефиниции на типове.

// custom.d.ts
declare module 'my-library' {
  export function doSomething(x: number): string;
}

Най-добри практики

Използвайте строг режим: Активирайте опцията strict за подобрена проверка на типовете.
Укажете цел: Изберете подходящата target версия за вашата среда на изпълнение.
Организирайте изходния код: Използвайте outDir, за да разделите изходния код от компилирания.
Управлявайте зависимостите: Използвайте include и exclude, за да контролирате кои файлове се компилират.
Възползвайте се от Extends: Споделяйте общи настройки на конфигурацията с опцията extends.
Проверявайте конфигурацията във версия за контрол: Комитирайте `tsconfig.json` в git, за да поддържате последователност между средите за разработка и CI/CD тръбопроводите.

Отстраняване на често срещани проблеми

Конфигурирането на tsconfig.json понякога може да бъде предизвикателство. Ето някои често срещани проблеми и техните решения:

Проблеми с разрешаването на модули

Ако срещнете грешки при разрешаването на модули, уверете се, че опцията moduleResolution е правилно конфигурирана и че опциите baseUrl и paths са настроени правилно. Проверете два пъти пътищата, посочени в опцията paths, за да се уверите, че са правилни. Проверете дали всички необходими модули са инсталирани в директорията node_modules.

Грешки в типовете

Грешки в типовете могат да възникнат, ако дефинициите на типовете са неправилни или липсват. Уверете се, че имате инсталирани правилните дефиниции на типове за всички библиотеки, които използвате. Ако използвате JavaScript библиотека, която няма дефиниции на типове, обмислете създаването на персонализирани дефиниции на типове.

Грешки при компилация

Грешки при компилация могат да възникнат, ако има синтактични грешки или грешки в типовете във вашия TypeScript код. Прегледайте внимателно съобщенията за грешки и поправете всички синтактични грешки или грешки в типовете. Уверете се, че вашият код следва конвенциите за кодиране на TypeScript.

Заключение

Добре конфигурираният файл tsconfig.json е от съществено значение за успешен проект на TypeScript. Като разбирате основните опции на компилатора и разширените конфигурации, можете да оптимизирате работния си процес, да подобрите качеството на кода и да осигурите съвместимост с целевата среда. Инвестирането на време в правилното конфигуриране на tsconfig.json ще се изплати в дългосрочен план, като намали грешките, подобри поддръжката и оптимизира процеса на билдване. Това води до по-ефективна и надеждна разработка на софтуер. Информацията, предоставена тук, е предназначена да бъде универсално приложима и трябва да осигури солидна основа за стартиране на нов проект с TypeScript.

Не забравяйте да се консултирате с официалната документация на TypeScript за най-актуалната информация и подробни обяснения на всички налични опции на компилатора. Документацията на TypeScript е ценен ресурс за разбиране на тънкостите на конфигурацията на TypeScript.

Конфигурация на TypeScript: Цялостно ръководство за tsconfig.json

Какво е tsconfig.json?

Създаване на файл tsconfig.json

Основни опции на компилатора

target

module

lib

allowJs

jsx

declaration

sourceMap

outDir

rootDir

strict

esModuleInterop

moduleResolution

baseUrl и paths

Опции Include и Exclude

Опция Extends

Разширени конфигурации

Инкрементална компилация

Референции към проекти

Персонализирани дефиниции на типове

Най-добри практики

Отстраняване на често срещани проблеми

Проблеми с разрешаването на модули

Грешки в типовете

Грешки при компилация

Заключение

`target`

`module`

`lib`

`allowJs`

`jsx`

`declaration`

`sourceMap`

`outDir`

`rootDir`

`strict`

`esModuleInterop`

`moduleResolution`

`baseUrl` и `paths`