<b>ESM ломается не в коде, а в границах: 4 места, где проект начинает «плыть»</b>

<b>ESM ломается не в коде, а в границах: 4 места, где проект начинает «плыть»</b>



В проектах на ESM чаще всего ломается не импорт как таковой, а соглашения вокруг него. Если модули живут в одном формате, а сборка — в другом, ошибки появляются в самых скучных местах: в CLI, тестах и на границе пакетов.

— Проверь, что у тебя один формат на уровне репы: либо <code>type: "module"</code>, либо явные расширения <code>.mjs</code>/<code>.cjs</code> там, где это нужно. Смешение без правил почти всегда даёт сюрпризы.

— Не полагайся на «магический» импорт без расширения. В ESM Node и часть рантаймов ждут точное имя файла. <code>./utils.js</code> и <code>./utils</code> — это не одно и то же.

— Если есть shared-пакеты в монорепе, проверь <code>exports</code> и <code>main</code>. Без явных точек входа потребитель начинает тянуть внутренности пакета, а потом ломается на рефакторинге.

— Для TypeScript отдельно смотри <code>moduleResolution</code> и <code>tsconfig-paths</code>. Алиасы в IDE могут работать, а в рантайме — нет. Это классическая ловушка при миграции.

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

Если проект уже вырос, ESM лучше внедрять через границы пакетов, а не переписывать всё сразу.