Настройка файла tsconfig.json

kirilljsx

Напомню, для для того что бы создать файл tsconfig.json прописываем в консоли команду:

./node_modules/.bin/tsc --init

или можно использовать команду (спасибо @Jspi):

npx tsc --init

Если кому интересно вот предидущие темы:

Вернемся к нашей конфигурации, сам конфиг поддерживает множество опций, все они описаны в официальной документации.
Мы же разберем самые необходимые.

Расширение

Для тех кто в танке, файлов конфига может быть несколько. Один для разработки, один для продакшена или базовый файл для описания общих элементов. Файлы настроек подключаются при помощи параметра extends в корне основной конфигурации.

Пример:

// tsconfig.json
{
  "extends": "./tsconfig.json", // Данный конфиг расширяет основной файл tsconfig.json
  "compilerOptions": {
    // переопределяем часть настроек
    "declaration": true,
  }
}

Посмотреть итоговую конфигурацию с учетом всех наследований можно выполнив команду:

./node_modules/.bin/tsc --showConfig

Целевая директория

Напомню что скомпилированные файлы и исходники должны храниться отдельно!

Сам TypeScript позволяет это сделать, для этого требуется указать параметр outDir в разделе конфигурации compilerOptions:

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

Исключение файлов

Еще одна не менее важная настройка, если мы запускаем компилятор tsc и не указывает файл в качестве аргумента, то в сборку попадут все файлы TypeScript.

Иногда требуется исключение и в сборку должны попасть не все файлы, для такой задачи у конфигуратора есть аж три параметра, они указываются в корне файла конфигурации.

При помощи параметра files можно указать определенный список компилируемых файлов, вот пример:

{
  "compilerOptions": {},
  "files": [
    ".src/core.ts",
    ".src/app.ts"
  ]
}

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

Но что если у нас большой проект? То перечислять файлы вручную будет конечно же неудобно. Для этого мы можем использовать другой параметр include, в него мы указываем шаблоны файлов и пути к ним.

Как это сделать - одна звездочка (*) будет обозначать любую последовательность символов, а две (**) - любая папка и подпапка. Таким шаблоном можно заменить все необходимые пути.

Пример:

{
  "compilerOptions": {},
  "include": [
    "src/**/*",
    "tests/**/*"
  ]
}

Дополнительно что бы избежать попадания лишних файлов поможет параметр exclude, вот пример:

 {
  "compilerOptions": {},
  "exclude": [
    "node_modules",
    "./src/**/*.spec.ts"
  ]
}

По дефолту параметр exclude включает все папки модулей node_modules и папку компиляции которая указана в outDir, если будете сами переделывать значение exclude, обязательно исключите эти пути!

Гибридный код

Перевод кодовой базы проекта с JavaScript на TypeScript — процесс небыстрый. И чтобы в это время код оставался рабочим, нужно научить компилятор принимать на вход как JS-, так и TS-файлы. Сделать это поможет параметр allowJs:

Перевод проекта с JavaScript на TypeScript довольно долгий процесс, и код должен оставаться рабочим, для этого можно задать компилятор параметры что бы он мог принимать на вход .js и .ts, в этом нам поможет allowJs:

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

При включенном allowJs теперь можно спокойно работать и продолжать переводить проект на TypeScript, старый код переписывать, а новый уже писать на TS.

Кстати о возможности конфликтов с некоторыми старыми библиотеками к примеру lodash, эта библиотека неподерживает ES6 модули. Для работы с ней или аналогичными в конфигурации TypeScript есть параметры esModuleInterop и зависимый от него allowSyntheticDefaultImports. Кстати включить только первый, а второй включится автоматически, пример:

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

Стандарт красоты (качества)

TS имеет возможность компилировать исходники в различные стандарты TS. В зависимости от проекта стандарт можно указать в параметре target:

{
  "compilerOptions": {
    "target": "ES6"
  }
}

По рекомендациям из официального сайта TS рекомендуется использовать ES6 так как он поддерживается всеми современными браузерами.
Глянуть какой стандарт поддерживают те или иные брауезры можно на сайте - caniuse.

Строгий режим

Строгий режим включается простым параметром strict:

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

Но этот режим в TS отличается от простого JS, и вносит дополнительные правила:

noImplicitAny неявный тип any;
noImplicitThis запрещает неявно определять this-контекст;
strictNullChecks проверяет, могут ли используемые значения быть null и undefined;
strictPropertyInitialization следит, чтобы в классе все свойства были инициализированы;
strictBindCallApply проверяет, чтобы bind, call и apply были использованы с правильными аргументами;
strictFunctionTypes сравнивает функции по контрвариантным правилам.

Файлы декларации

TypeScript содержит типы и работает таким образом что во время компиляции они пропадают, а в JS коде остается только реализация.

При импорте какой-либо функции в исходный файл из пакетов npm наш компилятор смотри в папку node_modules. Так как внутри находится уже готовый кода, а это означает что вся типизация пропала.

Чтобы сохранить обратную совместимость, рядом с итоговым файлом размещают декларацию с расширением .d.ts и тем же именем. В этой декларации содержатся исключительно описания типов, без какой‑либо реализации кода

Для того что бы TS умел создавать такие файлы во время компиляции мы должны включить опцию declaration:

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

Теперь когда компилятор будет использовать файлы JS то найдет рядом файлы декларации.

Теперь перейдет к Source Maps, это расширение .js.map оно помогает во время отладки приложения. А именно связывает строки исходного кода с компилированным. Включим параметр sourceMap:

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

Опции в package.json

Не редко все перечисленные параметры выше записываются в конфигурацию, но их также можно использовать при запуске команд tsc:

tsc --sourceMap

Такая практика полезна когда необходим скомпилировать код с минимальными исправлениями в конфигурации.

Оптимизация и ускорение

И как же нам ускорить компиляцию? Ответ есть, сохранять данные предидущей компиляции, это позволит сильно ускорить будущие компиляции не собирая все с нуля. Предидущая компиляция хранится в файле .tsbuildinfo, а вот параметр отвечающий за это:

{
  "compilerOptions": {
    "incremental": true
  }
}

Подведем итоги

А теперь коротко еще раз пробежимся по ключевым параметрам и опция.

В файле tsconfig.json можно указывать настройки двух уровней:

На верхнем уровне:

extends — используется для наследования конфигурации из другого файла.
files — задаёт конкретный список исходных файлов, которые должны быть скомпилированы.
include — позволяет указать набор файлов по шаблону, не перечисляя их вручную.
exclude — определяет файлы или директории, которые нужно исключить из сборки.

Внутри блока compilerOptions:

outDir — каталог, в который будут помещены результаты компиляции.
allowJs — разрешает использовать в проекте обычные JavaScript‑файлы.
esModuleInterop — обеспечивает корректную работу модулей ES6 в окружении CommonJS.
target — указывает стандарт JavaScript, в который будет транслироваться код.
strict — активирует строгий режим с расширенной системой проверок.
declaration — позволяет автоматически создавать декларационные файлы .d.ts.
sourceMap — генерирует Source Maps для отладки.

incremental — включает постепенную компиляцию с сохранением данных о прошлых сборках.

Aladdin

npx tsc --init

kirilljsx

@Jspi Ну или так Я просто старый пожилой уже