ESM ломается не в импортах, а в границах пакета и сборки

ESM ломается не в импортах, а в границах пакета и сборки

Если проект на ESM внезапно начинает «сыпаться», проверяйте не код-стайл, а контракт модуля:
— в package.json должны совпадать type, exports и main;
— относительные импорты лучше писать с расширением, если среда этого требует;
— для dual-package не смешивайте CommonJS и ESM в одном entry без явной схемы.

Вторая зона риска — инструменты вокруг. Node, Vite, tsup, Vitest, Bun и бандлеры могут по-разному читать один и тот же пакет. Частая ошибка: локально всё работает через транспиляцию, а в реальном рантайме падает из-за default/named export, условий exports или alias, который был виден только TypeScript.

Третья проверка — tsconfig и резолвинг. Для ESM важны nodenext или bundler-режим, иначе компилятор и рантайм начинают «видеть» разные пути. Если импорт выглядит красиво, но в build появляется странная ошибка, сначала откройте итоговый JS и посмотрите, во что превратились пути и экспорты.

ESM лучше внедрять не «по ощущениям», а через короткий чек-лист: один формат entry, явные exports, одинаковый резолвинг у TypeScript и сборщика, отдельная проверка запуска без транспилятора. Тогда миграция перестаёт быть лотереей и становится обычной инженерной задачей.