Articles
Введение в TypeScript
TypeScript и tsconfig.json

TypeScript и tsconfig.json

В этой статье объясняется, что такое TypeScript и tsconfig.json.

Начиная с основной роли TypeScript, мы объясним с конкретными примерами, как работает tsconfig.json в проекте.

YouTube Video

TypeScript и tsconfig.json

TypeScript — это 'JavaScript с типами.'. Однако, чтобы эффективно использовать TypeScript в реальных проектах, важно правильно понимать tsconfig.json и осознанно настраивать его.

Зачем нам нужен TypeScript?

В первую очередь основная причина использовать TypeScript — это 'возможность обнаружить ошибки до выполнения кода.'.

1function add(a: number, b: number): number {
2  return a + b;
3}
4
5add(1, "2");

Этот код не вызовет ошибку в JavaScript до момента выполнения, но в TypeScript приведёт к ошибке типов на этапе компиляции.

Такое 'раннее обнаружение' значительно повышает эффективность и качество разработки.

Как выполняется TypeScript?

В принципе, TypeScript нельзя выполнить напрямую. Необходимо преобразовать TypeScript в JavaScript с помощью tsc (TypeScript Compiler)..

1npm install -D typescript
2npx tsc --init
  • Выполнив эту операцию, вы создадите tsconfig.json, который является основным файлом, определяющим поведение TypeScript-проекта.

Какова роль tsconfig.json?

tsconfig.json — это файл конфигурации, который определяет 'какие файлы', 'с какими правилами' и 'как их преобразовывать.'. Хотя это может показаться сложным сначала, действительно важны лишь несколько настроек.

1{
2  "compilerOptions": {
3    "target": "ES2020",
4    "module": "ESNext",
5    "strict": true
6  }
7}
  • Только с этими настройками уже возможна современная и безопасная разработка на TypeScript.

target: Версия JavaScript для вывода

target определяет уровень спецификации выходного JavaScript.

1"target": "ES2020"

С этим TypeScript будет генерировать JavaScript, эквивалентный ES2020. Для старых окружений выберите ES5, для самых новых — ES2022 и т. д.

При указании ESNext 

1"target": "ESNext"

  • ESNext задаёт вывод самой новой доступной синтаксиса JavaScript как есть. TypeScript не транспилирует синтаксис, а оставляет это на исполнение в среде выполнения, такой как Node.js или браузер.

  • Поэтому ESNext подходит, если вы нацеливаетесь только на последние версии Node.js или используете Babel/сборщик для отдельного транспилирования. С другой стороны, если среда выполнения не поддерживает последний синтаксис, это может привести к ошибкам во время выполнения, поэтому требуется осторожность.

module: Задать формат модулей

module определяет формат модуля.

1"module": "ESNext"
  • ESNext является стандартом во фронтенде и современных средах Node.js.
  • Выбирайте "CommonJS" только если вам нужен CommonJS.

strict: Максимальная строгость типов

strict — это переключатель максимальной безопасности TypeScript.

1"strict": true
  • При активации будут тщательно отслеживаться неявные типы и потенциальные ошибки.

strict и неявный any

Когда вы включаете strict, TypeScript воспринимает переменные, тип которых нельзя вывести, как ошибку.

1function printValue(value) {
2	console.log(value);
3}
  • У этой переменной value нет информации о типе при объявлении, поэтому TypeScript не может определить её тип. В результате неявно присваивается тип any, что вызовет предупреждение (ошибку) в режиме strict.
1function printValue(value: number) {
2	console.log(value);
3}
  • Если явно указать тип таким образом, TypeScript поймёт, что 'эта переменная работает только с числами.'. В TypeScript важнее, чтобы тип можно было однозначно определить, чем чтобы его можно было опустить.

include/exclude: Управление файлами для компиляции

В tsconfig.json вы можете указать, какие файлы включать, а какие исключать из компиляции.

1{
2  "include": ["src"],
3  "exclude": ["node_modules"]
4}
  • С этим только файлы в src будут обрабатываться TypeScript.
  • node_modules, указанный в exclude, будет исключён из компиляции даже если он находится в путях, перечисленных в include.

outDir: Задать каталог вывода

Задайте outDir, чтобы управлять местом вывода сборки.

1"outDir": "dist"
  • С этим все результаты компиляции будут выведены в папку dist. На практике разделение исходного кода и артефактов сборки является стандартом.

rootDir: Задать корневой каталог исходников

rootDir указывает каталог, который TypeScript считает корнем исходного кода.

1"rootDir": "src"

  • Эта настройка позволяет TypeScript сохранять структуру каталогов на основе src при выводе файлов. Например, файл src/index.ts станет dist/index.js после компиляции.

  • Структура каталога, заданного в rootDir, будет воспроизведена в outDir.

esModuleInterop: Мост между CommonJS и ES-модулями

Далее рассмотрим esModuleInterop.

1"esModuleInterop": true
  • Если включено, вы сможете безопасно использовать CommonJS-модули с синтаксисом import.
1import fs from "fs";
  • Эта настройка практически обязательна при использовании Node.js.

noImplicitAny: Запрет на неявные типы 'any'

Также важно усилить проверку типов в tsconfig.json.

1"noImplicitAny": true
  • С этим вы сможете запретить неявные типы any. Это позволяет надёжно находить места, где вы забыли указать тип.

Настройка для обнаружения неиспользуемого кода

Параметры для обнаружения неиспользуемого кода также помогают повысить сопровождаемость.

1"noUnusedLocals": true,
2"noUnusedParameters": true
  • С этим ненужные переменные и аргументы сразу помечаются как предупреждения.

lib: Определяет встроенные API, доступные для использования

lib — параметр, определяющий стандартные API, которые предполагается существующими в TypeScript.

1"lib": ["ES2020", "DOM"]
  • С этой настройкой становятся доступны следующие типы:. С ES2020 становятся доступны современные возможности, такие как Promise, Map и Set. С DOM становятся доступны браузерные API: document, window, HTMLElement и др.

Во фронтенде укажите DOM, а для Node.js-проектов удалите DOM, чтобы избежать ненужных глобальных типов.

moduleResolution: Правила поиска модулей

moduleResolution определяет как модули из import будут разрешаться.

1"moduleResolution": "Node"

Два основных варианта следующие:.

  • Если вы укажете Node, будут применяться правила разрешения модулей, как в Node.js.
  • Classic — это старый, специфический для TypeScript метод, который сейчас почти не используется.

В средах с Node.js или сборщиком лучше явно указать вариант Node.

Минимальный, готовый к продакшену tsconfig.json

Основываясь на рассмотренном выше, минимальный продакшен tsconfig.json будет выглядеть так:.

 1{
 2  "compilerOptions": {
 3    "target": "ES2020",
 4    "module": "ESNext",
 5    "moduleResolution": "Node",
 6    "lib": ["ES2020", "DOM"],
 7    "strict": true,
 8    "rootDir": "src",
 9    "outDir": "dist",
10    "esModuleInterop": true,
11    "noImplicitAny": true,
12    "noUnusedLocals": true,
13    "noUnusedParameters": true
14  },
15  "include": ["src"]
16}

Эта конфигурация обеспечивает безопасную основу и для фронтенд-, и для Node.js-проектов.

Резюме: tsconfig.json — это 'свод правил'

tsconfig.json — это не просто конфиг, а 'свод правил' для всего проекта. С помощью tsconfig.json чётко определяются такие важные правила как:.

  • Уровень типовой безопасности.
  • Кодинг-стандарты вашей команды.
  • Профилактика будущих ошибок.

Поняв tsconfig.json, вы сможете не только писать на TypeScript, но и проектировать безопасно его использование в ваших проектах.

Вы можете следовать этой статье, используя Visual Studio Code на нашем YouTube-канале. Пожалуйста, также посмотрите наш YouTube-канал.

YouTube Video

Лучшие практики программирования на TypeScript