Шпаргалка по TSConfig

tsconfig.json пугает всех. Это огромный файл с огромным количеством дополнительных опций.

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

Быстрый старт

Хотите только код? Вот, пожалуйста:

{
  "compilerOptions": {
    /* Базовый опции: */
    "esModuleInterop": true,
    "skipLibCheck": true,
    "target": "es2022",
    "allowJs": true,
    "resolveJsonModule": true,
    "moduleDetection": "force",
    "isolatedModules": true,

    /* Строгость */
    "strict": true,
    "noUncheckedIndexedAccess": true,

    /* Если транспилируете с TypeScript: */
    "moduleResolution": "NodeNext",
    "module": "NodeNext",
    "outDir": "dist",
    "sourceMap": true,

    /* А если вы собираете для библиотеки: */
    "declaration": true,

    /* А если вы собираете для библиотеки в монорепо: */
    "composite": true,
    "declarationMap": true,

    /* Если НЕ транспилируете с TypeScript: */
    "moduleResolution": "Bundler",
    "module": "preserve",
    "noEmit": true,

    /* Если ваш код запускается в DOM: */
    "lib": ["es2022", "dom", "dom.iterable"],

    /* Если ваш код не запускается в DOM: */
    "lib": ["es2022"]
  }
}

Полное объяснение

Базовые опции

Вот базовые опции, которые я рекомендую для всех проектов.

{
  "compilerOptions": {
    "esModuleInterop": true,
    "skipLibCheck": true,
    "target": "es2022",
    "allowJs": true,
    "resolveJsonModule": true,
    "moduleDetection": "force",
    "isolatedModules": true
  }
}

• esModuleInterop: Помогает устранить некоторые противоречия между CommonJS и ES-модулями.
• skipLibCheck: Пропускает проверку типов файлов .d.ts. Это важно для производительности, в противном случае будут проверены все файлы в node_modules.
• target: Версия JavaScript, на которую вы ориентируетесь. Рекомендую использовать es2022, а не esnext для стабильности.
• allowJs и resolveJsonModule: Позволяют импортировать файлы .js и .json. Всегда полезны.
• moduleDetection: Эта опция заставляет TypeScript рассматривать все файлы как модули. Помогает избежать ошибок типа "cannot redeclare block-scoped variable".
• isolatedModules: Эта опция предотвращает несколько возможностей TS, которые небезопасны при обращении с модулями как с изолированными файлами.

Строгость

Вот опции строгости, рекомендуемые мной для всех проектов.

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true
  }
}

• strict: Включает все опции строгой проверки типов. Незаменим.
• noUncheckedIndexedAccess: Запрещает обращаться к массиву или объекту, не проверив предварительно, определён ли он. Это отличный способ предотвратить ошибки времени выполнения, и его действительно следует включить в strict.

Многие рекомендуют использовать опции строгости в tsconfig/bases, замечательном репозитории, в котором собраны опции TSConfig. Эти опции включают множество правил, которые я считаю слишком "шумными", например noImplicitReturns, noUnusedLocals, noUnusedParameters и noFallthroughCasesInSwitch. Рекомендую добавлять их в tsconfig.json только в том случае, если они вам нужны.

Транспиляция с TypeScript

Если вы транспилируете свой код (создаёте файлы JavaScript) с помощью tsc, вам понадобятся эти опции.

{
  "compilerOptions": {
    "moduleResolution": "NodeNext",
    "module": "NodeNext",
    "outDir": "dist"
  }
}

• moduleResolution: Указывает TypeScript, как разрешать модули. NodeNext — лучший вариант, если код, который вы пишете, предназначен для выполнения в Node.
• module: Указывает TypeScript, какой синтаксис модуля использовать. NodeNext — лучший вариант для Node.
• outDir: Указывает TypeScript, куда поместить скомпилированные файлы JavaScript. Я предпочитаю использовать соглашение dist, но вам решать.

Сборка для библиотеки

Если вы собираете проект для библиотеки, вам понадобится declaration: true.

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

• declaration: Указывает TypeScript создавать файлы .d.ts. Это необходимо для того, чтобы библиотеки могли получить автозавершение в создаваемых .js файлах.

Сборка для библиотеки в монорепо

Если вы собираете библиотеку в моно репозитории, вам также понадобятся эти опции.

{
  "compilerOptions": {
    "declaration": true,
    "composite": true,
    "sourceMap": true,
    "declarationMap": true
  }
}

• composite: Указывает TypeScript создавать файлы .tsbuildinfo. Это сообщает TypeScript, что ваш проект является частью монорепо, а также помогает ему кэшировать сборки для более быстрой работы.
• sourceMap и declarationMap: Указывает TypeScript создавать карты исходного кода и карты деклараций. Они нужны для того, чтобы при отладке пользователи ваших библиотек могли перейти к исходному коду, используя go-to-definition.

Без транспиляции с TypeScript

Если вы не транспилируете свой код с помощью tsc, то есть используете TypeScript скорее как линтер, вам пригодятся эти опции.

{
  "compilerOptions": {
    "moduleResolution": "Bundler",
    "module": "preserve",
    "noEmit": true
  }
}

• moduleResolution: Bundler — лучший вариант, если код, который вы пишете, предназначен для комплектации с помощью таких инструментов, как Webpack, Rollup, Babel, SWC или ESBuild.
• module: preserve — лучший вариант, поскольку он наиболее точно имитирует работу бандлеров с модулями.

Выполняется в DOM

Если ваш код выполняется в DOM, вам понадобятся эти опции.

{
  "compilerOptions": {
    "lib": ["es2022", "dom", "dom.iterable"]
  }
}

• lib: Указывает TypeScript, какие встроенные типы включить. es2022 — лучший вариант для стабильности. dom и dom.iterable предоставляют типы для window, document и т. д.

Не выполняется в DOM

Если ваш код не выполняется в DOM, вам понадобится lib: ["es2022"].

{
  "compilerOptions": {
    "lib": ["es2022"]
  }
}

Это то же самое, что и выше, но без типов dom и dom.iterable.

Я что-то упустил?

Надеюсь, я дал немного вдохновения для следующего раза, когда понадобится настроить TypeScript.

Я что-то пропустил? Сообщите мне об этом, написав в X.