Версия источника: d33454c0dad753475ecc92aaecf8d783f02fd01b
Синхронизировано: 2026-11-13T05:38:20.984Z
Источник: https://github.com/sergey-from-riders/vibecoding-base/tree/d33454c0dad753475ecc92aaecf8d783f02fd01b

<a id="languages-module-boundaries"></a>

# Модули и разрешение импортов

## Коротко

Определи публичные экспорты модуля и разрешенное направление зависимостей; внутренние файлы не становятся стабильным API по факту доступности пути.

## Плохо

```text
TypeScript принимает alias @internal/db.
Его runtime-поддержка не настроена; браузер импортирует Node-only пакет.
Импорт типа считается гарантией выполнения регистрации модуля.
```

## Хорошо

```text
Контракт: публичный 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. Серверные зависимости не импортируются в браузерный модуль.

## Как проверить

- Публичный entrypoint → собрать и запустить в целевой среде → зависимости разрешены без скрытого local alias.
- Alias известен только tsconfig → выполнить runtime-проверку → проблема выявлена до выпуска.
- Type-only import удален при сборке, а регистрация нужна → проверить → side effect импортирован отдельно либо архитектура исправлена.

## Человек

Определяет публичную границу и поддерживаемые runtime/toolchain.

## Агент

Проверяет реальный запуск entrypoint и граф зависимостей, не маскирует runtime-ошибку дополнительным assertion.

## Источники

- [TypeScript: Modules Reference](https://www.typescriptlang.org/docs/handbook/modules/reference.html) — Type-only imports, module resolution, paths and emitted specifiers.
- [Next.js App Router: Server and Client Components](https://nextjs.org/docs/app/getting-started/server-and-client-components) — Client module graph, serializable props and server-only modules.

Уровень: Рекомендуется. Опубликовано: 2026-11-13. Проверено: 2026-11-13. Изменено: 2026-11-13.

[Исходный файл](https://github.com/sergey-from-riders/vibecoding-base/blob/d33454c0dad753475ecc92aaecf8d783f02fd01b/registry/standards/languages/typescript/rules/module-boundaries.md)