tsconfig.json: что генерирует tsc --init сегодня

Команда создаёт tsconfig.json в текущей папке. Файл с расширением .json, но внутри — комментарии и висячая запятая после последнего поля: компилятор читает его своим разбором формата JSONC, а не JSON.parse. Не пугайтесь, если редактор подсветит это красным, — tsc такой файл понимает.

Настройки разложены по озаглавленным блокам, и заголовки эти — обычные комментарии. Вот весь список включённого, сверху вниз, в том порядке, в каком он лежит в файле.

Закомментированные строки — не мусор, а подсказки: rootDir с outDir в блоке File Layout, набор для Node в блоке Environment Settings, шесть придирок в Style Options. Их не включили не потому, что они плохи, а потому что выбор зависит от проекта.

Файл начинается со ссылки на aka.ms/tsconfig — она заменила ту самую сотню закомментированных опций из старых версий.

target делает две работы сразу. Первая: сообщает, какие встроенные объекты считать существующими — из него выводится lib, список файлов с описанием среды. Вторая: определяет, во что переписывать синтаксис при выпуске. Обе видны на запуске, и обе умеют удивить.

Начнём с первой. В песочнице учебника lib объявлен как ES2023 — ровно та ситуация, когда код опережает конфиг.

type Good = { name: string; shop: string };

const goods: Good[] = [
  { name: "молоко", shop: "Пятёрочка" },
  { name: "хлеб", shop: "Магнит" },
  { name: "сыр", shop: "Пятёрочка" }
];

const byShop = Object.groupBy(goods, (good: Good) => good.shop);
console.log(byShop["Пятёрочка"].length);

Компилятор пишет TS2550 и прямо называет виновную настройку: «Вы хотите изменить целевую библиотеку? Попробуйте изменить параметр компилятора lib на es2024 или более поздней версии». А браузер спокойно печатает двойку — Object.groupBy в нём давно есть.

Это и есть суть lib: список обещаний о среде, а не полифилл. Компилятор ничего не добавляет в выпущенный код — он только сверяет ваш код с описанием. Поставите lib выше, чем умеет реальный браузер, — получите молчание на сборке и TypeError у пользователя. Поставите ниже — получите ложные ошибки на рабочем коде.

В сгенерированном конфиге стоит "target": "esnext", то есть «среда свежая, ничего не переписывай». Вместе с ним по умолчанию подключается и разметка браузера: document и window видны без единой строки в конфиге. Именно поэтому для серверного проекта в файле закомментирован набор "lib": ["esnext"] — он убирает DOM, которого на сервере нет.

Вторая работа target — эмит. Здесь одна строка конфига меняет не типы, а поведение программы.

class Product {
  price: number;

  constructor(price: number) {
    this.price = price;
  }
}

class Discounted extends Product {
  price: number;
}

console.log(new Discounted(100).price);

Конструктор записал сотню, потомок не написал ни строки кода — и значение пропало. Компилятор предупреждал дважды: TS2564 про поле без инициализатора (та самая ошибка из главы про классы) и TS2612 — «Свойство price перезапишет базовое свойство в Product. Если это сделано намеренно, добавьте инициализатор. В противном случае добавьте модификатор declare или удалите избыточное объявление».

Виноват target. При target от ES2022 и выше сам собой включается useDefineForClassFields, и объявление поля превращается в настоящее поле класса: движок определяет свойство заново, затирая всё, что успел положить конструктор родителя. С "target": "es2015" из старых руководств тот же исходник печатает 100. Лечится словом declare перед полем — оно говорит «это только объявление типа, кода не выпускай».

class Product {
  price;
  constructor(price) {
    this.price = price;
  }
}
class Discounted extends Product {
  price;
}
console.log(new Discounted(100).price);

class Product {
  constructor(price) {
    this.price = price;
  }
}
class Discounted extends Product {}
console.log(new Discounted(100).price);

Строка выглядит бессмысленной: пустой список типов в проекте про типы. На самом деле types не имеет отношения к вашим аннотациям — он про пакеты, которые добавляют объявления в глобальную область каждого файла, ничего не импортируя.

Раньше это работало так: любая папка внутри node_modules/@types подхватывалась автоматически. Поставили @types/jest ради тестов — и describe с it стали видны в файлах приложения, где им нечего делать. Пришёл @types/node транзитивной зависимостью — и process с Buffer оказались доступны в браузерном коде, который до process не дотянется никогда.

В TypeScript 6 автоматический подхват выключили совсем. Пустой массив в сгенерированном конфиге теперь не выключатель, а надпись на видном месте: вот сюда пишутся глобальные пакеты. Старое поведение вернуть можно — звёздочкой.

Практическое следствие видно сразу, как только вы напишете серверный код. С "types": [] строка import { readFileSync } from "node:fs" не заработает, даже если пакет @types/node стоит: компилятор ответит TS2591 — «Не удается найти имя node:fs… добавьте node в поле типов в файле tsconfig». Именно этот набор и лежит в конфиге закомментированным под заголовком «For nodejs».

Компилятор в таких сообщениях подсказывает и имя пакета, и строку конфига. Читать их стоит до конца — половина ответа уже там.

Три строки конфига — isolatedModules, verbatimModuleSyntax и moduleDetection — про одно и то же: файл должен переживать компиляцию в одиночку. Причина внешняя. В настоящем проекте .ts в .js превращает чаще не tsc, а esbuild, swc, Vite или сам Node, снимающий типы на лету. Все они смотрят ровно на один файл и понятия не имеют, что лежит в соседних.

isolatedModules — это обещание компилятору: «не пиши код, который нельзя понять по одному файлу». Запрещённого немного, зато оно неочевидно. Реэкспорт типа обязан быть помечен как export type, иначе однофайловый компилятор оставит в выпущенном коде импорт несуществующего значения. А const enum перестаёт подставляться числом в место использования — вместо этого выпускается обычный объект-перечисление, потому что подставить значение, не заглянув в другой файл, невозможно.

С moduleDetection история другая, и она про область видимости. Файл без единого import и export — не модуль, а скрипт: его верхние имена лежат в той же общей области, что и всё остальное. Песочница учебника выполняет примеры именно так, поэтому эффект видно прямо здесь.

const Map = "моя карта";
console.log(Map);

TS2451: «Невозможно повторно объявить переменную Map с областью видимости „Блок“». Никакого второго Map в файле нет — он пришёл из библиотеки типов, и в скрипте это тот же самый уровень имён. В проекте так же столкнутся два файла, в каждом из которых просто написано const total = 1.

Настройка "moduleDetection": "force" объявляет модулем каждый файл, и проблема исчезает вместе с общей областью. Тонкость: при "module": "nodenext" этот режим и так включается сам — строка в конфиге страхует вас на случай, если module когда-нибудь поменяют на esnext, где по умолчанию действует определение по содержимому.

Раньше файл-скрипт превращали в модуль строкой export {} — с moduleDetection: force этот приём больше не нужен.

Четвёртая строка того же семейства, verbatimModuleSyntax, требует писать import type там, где импортируется только тип. Разговор о ней — в отдельной статье этой главы, вместе с moduleResolution.

Блок File Layout закомментирован целиком, и это осмысленный выбор: пока outDir не задан, каждый .js ложится рядом со своим .ts. Для пробы удобно, для проекта — нет, поэтому строки и оставлены на виду.

Списка файлов в сгенерированном конфиге тоже нет. Значения по умолчанию таковы.

Блок Other Outputs — про то, что кроме .js. sourceMap нужен отладчику: без карты вы ставите точку останова в выпущенном коде, а не в своём. declaration выпускает .d.ts — типы для тех, кто подключит ваш пакет; declarationMap делает так, что «перейти к определению» ведёт из чужого проекта в ваш исходник, а не в сухое объявление.

Если сборкой занимается бандлер, а tsc нужен только как проверяльщик, все три строки можно выкинуть и поставить "noEmit": true. Тогда компилятор ничего не пишет на диск и просто говорит «да» или «нет».

И самое неочевидное про выпуск: ошибки типов по умолчанию его не отменяют. Компилятор ругается и всё равно создаёт .js.

function total(prices: number[]): number {
  return prices.reduce((sum, price) => sum + price, 0);
}

const raw = "100,200";
console.log(total(raw));

TS2345 на сборке, TypeError на запуске — и файл всё-таки выпущен. Так ведёт себя tsc с настройками по умолчанию, и так же устроена песочница учебника: диагностика показывается, а код после неё выполняется. Логика тут есть — при переводе большого проекта на TypeScript иначе было бы нечего запускать.

В боевой сборке этот компромисс не нужен. Либо "noEmitOnError": true в конфиге, либо, что чаще, отдельный шаг tsc --noEmit в проверке перед выкладкой — тогда сборка падает, не дожидаясь пользователя.

Найдя в сети статью с длинным tsconfig.json, полезно знать, что из неё можно не переносить. Почти всё лишнее — это значения по умолчанию, которые за последние годы наконец совпали с тем, как люди пишут код.

Обратная сторона короткого конфига: настроек не стало меньше, они просто перестали быть видимыми. Когда поведение компилятора удивляет, первым делом стоит спросить его самого — tsc --showConfig покажет всё, включая выведенное, а не только написанное вами.

Оставшиеся шесть строк из сгенерированного файла разбираются в этой же главе: strict — в следующей статье, noUncheckedIndexedAccess с exactOptionalPropertyTypes — в статье про строгость сверх strict, verbatimModuleSyntax — в статье про модули.