Модули и резолюция

Модуль в TypeScript — это не косметика синтаксиса, а граница между тем, что вы пишете, и тем, что исполняет рантайм. Правило ровно одно: файл с top-level import или export — это модуль со своей областью видимости; файл без единого из них — скрипт, чьи объявления попадают в глобальную область. Из этого одного факта растут почти все «duplicate identifier» и «cannot find name», а идиома export {} существует затем, чтобы принудительно сделать файл модулем. Поверх этого лежат две ортогональные оси, которые постоянно путают: опция module решает, какой синтаксис эмитит tsc (commonjs переписывает import/export в require/exports, esnext оставляет их ES-модулями), а moduleResolution решает, как строка-спецификатор вроде 'lodash' превращается в файл на диске. Ни одна из них не меняет то, что вы написали в исходнике.

Отсюда и стенд ловушек, который стоит назвать сразу. Типы в TypeScript стираются — поэтому import type гарантированно не эмитит ничего, а paths-алиас никогда не доходит до рантайма и требует отдельного резолвера. CommonJS не знает понятия «экспорт по умолчанию» — поэтому esModuleInterop синтезирует его хелпером, а без него import fs from 'fs' собирается, но падает. namespace — доэсэмное наследие, живое лишь в .d.ts. И версии продолжают резать: TS 6.0 объявил устаревшими moduleResolution: node10, baseUrl, outFile и esModuleInterop: false, а TS 7.0 (GA 8 июля 2026, компилятор на Go) сделал их жёсткими ошибками. Разбор по слоям — ниже.

Карта темы

• Файл-модуль против файла-скрипта — правило «есть top-level import/export → модуль», статическая анализируемость ESM, tree-shaking и почему циклический импорт падает в CommonJS.
• Interop с CommonJS — чем module.exports = x отличается от export default x, что делает esModuleInterop и почему import * as express перестаёт быть вызываемым.
• Резолюция модулей — node10 против node16/nodenext против bundler, paths только на этапе компиляции и почему алиас падает в рантайме.
• import type и стирание — почему tsc вырезает импорт типа, а однофайловый транспилятор — нет, что даёт isolatedModules и verbatimModuleSyntax.
• namespace — наследие — IIFE на глобальном объекте, почему ES-модули его вытеснили и где declare namespace всё ещё уместен.
• Дополнение модуля — как добавить свойство в типы сторонней библиотеки через declare module, требование к файлу-модулю и пределы слияния.
• Динамический import() — import() как выражение-Promise и как тип, вычисляемый спецификатор даёт any, а module: commonjs ломает code-splitting.
• Типы для JS-пакетов — откуда берутся @types/*, порядок условия types в exports и что на самом деле выключает skipLibCheck.

Частые ошибки и ловушки

Значение для собеседований

Тема модулей — это проверка модели исполнения, а не словаря. Интервьюер хочет услышать, что вы держите в голове два разных вопроса: что tsc эмитит (и что при этом остаётся неизменным в исходнике) и что физически происходит, когда Node или bundler грузит получившийся код. Джуна от middle отделяет один вопрос — «чем module отличается от moduleResolution?»: правильный ответ не «одно новее», а «одно выбирает формат эмита, другое — способ найти файл на диске, и ни одно не трогает то, что вы написали».

Что обычно проверяют:

• Разницу module и moduleResolution и что ни одна опция не меняет исходный код.
• Правило «файл-модуль против файла-скрипта» и зачем нужна идиома export {}.
• Что делает esModuleInterop и чем он отличается от allowSyntheticDefaultImports.
• Чем node16/nodenext отличается от bundler и почему node10 идёт под удаление.
• Что гарантирует import type и зачем он однофайловым транспиляторам под isolatedModules.
• Почему paths-алиас проходит проверку типов, но падает в рантайме.
• Когда namespace ещё уместен и почему в остальных случаях его вытеснили ES-модули.
• Как дополнить типы сторонней библиотеки, не форкая её.
• Почему вычисляемый import() даёт any и как вернуть типобезопасность.
• Откуда берутся @types/* и что на самом деле выключает skipLibCheck.

Типичный неверный ответ: «import type — это оптимизация, подсказка bundler-у выбросить импорт при tree-shaking». На деле это гарантия про эмит: оператор стирается безусловно, прямо в синтаксисе. Нужен он потому, что однофайловый транспилятор (esbuild, SWC, Babel) видит один файл и без межфайловых типов не может отличить import { User }-тип от import { User }-значения — а tsc может, потому что видит всю программу. Та же путаница слепит кандидата к циклическим импортам: обычный импорт значения, оставленный ради одного типа, создаёт рантайм-ребро, и модуль, вычисляемый вторым, получает ещё пустой exports соседа — class Order extends undefined падает там, где tsc --noEmit был абсолютно чист.