Модули и разрешение импортов
Определи публичные экспорты модуля и разрешенное направление зависимостей; внутренние файлы не становятся стабильным API по факту доступности пути.
Плохо
TypeScript принимает alias @internal/db.
Его runtime-поддержка не настроена; браузер импортирует Node-only пакет.
Импорт типа считается гарантией выполнения регистрации модуля.
Хорошо
Контракт: публичный export модели; внутренний путь не обещан потребителю.
Node ESM со сборкой: выбран совместимый moduleResolution и runtime specifier.
Type-only зависимость: import type; side effect, если нужен, импортирован явно.
Проверка: чистая сборка и запуск разрешенного entrypoint в целевой среде.
Browser entrypoint не включает server-only зависимость.
Почему это важно
Компилятор, bundler и runtime решают разные задачи. Несогласованное разрешение импортов может пройти проверку типов и отказать только после выпуска.
Когда применять
Для JS/TS модулей и пакетов. Расширения и правила ESM/CommonJS зависят от runtime и сборки; не навязывай один режим браузеру, Node и тестовому runner. Пример описывает контракт проверки, а не готовую конфигурацию.
Подробные условия
Не создавай слой или barrel-файл без задачи: сокрытие реализации, совместимость либо повторное использование.
Согласуй module/moduleResolution, package type, расширения импортов и bundler с фактическим runtime. Успешный typecheck не гарантирует, что модуль найдется при исполнении. paths в tsconfig сам по себе не переписывает emitted imports. Для импорта только типов используй import type, если это соответствует toolchain; он не должен неявно обеспечивать нужный side effect. Серверные зависимости не импортируются в браузерный модуль.
Кто что делает
Человек
Определяет публичную границу и поддерживаемые runtime/toolchain.
AI-агент
Проверяет реальный запуск entrypoint и граф зависимостей, не маскирует runtime-ошибку дополнительным assertion.
Как проверить у себя
- Публичный entrypoint → собрать и запустить в целевой среде → зависимости разрешены без скрытого local alias.
- Alias известен только tsconfig → выполнить runtime-проверку → проблема выявлена до выпуска.
- Type-only import удален при сборке, а регистрация нужна → проверить → side effect импортирован отдельно либо архитектура исправлена.
Первоисточники
- TypeScript: Modules Reference — Type-only imports, module resolution, paths and emitted specifiers.
- Next.js App Router: Server and Client Components — Client module graph, serializable props and server-only modules.
Дата проверки отражает содержательную сверку. Синхронизация сайта не обновляет её автоматически.