TypeScript ломается не в типах, а в границах между пакетами и файлами

TypeScript ломается не в типах, а в границах между пакетами и файлами

Чаще всего проблемы начинаются не с интерфейсов, а с tsconfig. Если у вас в репе несколько пакетов, проверьте три вещи: strict включён везде, baseUrl не используется без нужды, а пути из paths совпадают с реальными алиасами в сборке.

Дальше — режим модулей. Смешивать CommonJS и ESM можно, но цена почти всегда одна: странные импорты, дублирование зависимостей и «магия» вокруг default export. Если проект уже на ESM, держите одинаковые правила для всех пакетов: один формат входа, один стиль импортов, одна схема публикации.

Отдельно проверьте типы для внешних границ: API, события, env, runtime-ответы. TypeScript не спасает, если вы описали форму данных красивым интерфейсом, но не валидируете вход. Для этого обычно хватает простого правила: всё, что пришло извне, считается unknown до проверки.

И ещё одно наблюдение которое стоит проверить: большинство «медленных» TS-проектов тормозит не компилятор, а лишние пересчёты. Слишком широкие include, глубокие re-export цепочки, лишние project references и общие файлы типов на весь монорепо быстро раздувают build time.

Если хотите меньше боли, начните не с кода, а с границ: tsconfig, формат модулей, контракт данных и область видимости типов. Тогда TypeScript начинает помогать, а не просто шуметь в редакторе.