<b>tsconfig ломается не в TypeScript, а в трёх местах: пути, модули и совместимость</b>

<b>tsconfig ломается не в TypeScript, а в трёх местах: пути, модули и совместимость</b>

Если проект начал вести себя странно, первым делом смотрят не на код, а на <code>tsconfig</code>. Ошибка часто сидит в связке <code>module</code>, <code>moduleResolution</code> и <code>baseUrl/paths</code>: компилятор и рантайм могут понимать импорты по-разному.

Три типовые зоны риска:
— <code>module</code> и <code>moduleResolution</code> не совпадают с реальным рантаймом: ESM, NodeNext, Bundler — это не взаимозаменяемые режимы.
— <code>paths</code> работают для TypeScript, но не для Node без alias-решения на уровне сборки или запуска.
— <code>esModuleInterop</code>, <code>allowSyntheticDefaultImports</code>, <code>verbatimModuleSyntax</code> меняют то, как выглядят импорты после компиляции.

Полезная привычка: держать <code>tsconfig</code> как набор явных решений, а не свалку флагов. Если у вас Vite, отдельно проверьте, что алиасы повторяются в конфиге сборщика. Если у вас Node-сервис — убедитесь, что импорт, который проходит типизацию, реально резолвится в рантайме.

Ещё одна ошибка — смешивать цели. Один <code>tsconfig</code> для приложения, другой для тестов, третий для сборки. Когда всё лежит в одном файле, компромиссы быстро становятся багами.

Хороший <code>tsconfig</code> не делает код красивее. Он делает поведение предсказуемым.