Skip to content

Публичный API директории ​

Индексный файл директории — ее публичный API и единственная разрешенная точка входа для внешнего кода. Такой файл также называют баррелем (barrel): он содержит реэкспорты из содержимого директории.

Наличие индексного файла означает, что директория является самостоятельной границей: внешний код может обращаться к ее содержимому только через этот файл.

Таким образом, index.ts — это не просто сокращение импортов. Он явно отделяет публичный интерфейс директории от ее внутренней реализации.

Это справедливо для любой директории в проекте:

  • модуля;
  • слоя;
  • сложного компонента, состоящего из нескольких файлов.

Какую проблему решает ​

Без четкой границы потребители импортируют внутренние файлы напрямую, превращая детали реализации в публичный контракт. В результате любой рефакторинг может затронуть весь проект.

Правила ​

Чтобы баррель работал как инструмент архитектурного контроля, необходимо соблюдать три правила:

  1. Осознанное расширение API

    Каждая строка в барреле — это публичное обещание поддерживать имя. Добавлять экспорт нужно только тогда, когда он действительно нужен потребителям сегодня. Экспортировать «на будущее» или «всё, что лежит в папке» создает ненужные обязательства.

  2. Запрет импорта из своего или вышестоящего барреля

    Импорт через свои и родительские баррели запрещен — это спасает от циклических зависимостей.

    Это касается только продуктового кода

    Для тестов, сторибука, моков и подобных вспомогательных файлов допустимо импортировать через баррель. Это снижает зависимость от деталей внутренней реализации, при этом опасность циклических зависимостей минимальна — такие файлы сами не импортируются продуктовым кодом.

  3. Разделение потоков импортов

    • Снаружи: Внешний код импортирует сущность строго через ее баррель.
    • Внутри: Файлы внутри сущности импортируют друг друга напрямую, используя только относительные пути, Это дает мгновенную визуальную проверку: если внутри файла сущности появляется абсолютный импорт этой же сущности — это прямое нарушение границы и риск циклической зависимости.

Почему ​

Соблюдение этих правил дает конкретные практические выгоды:

  • Прозрачность на ревью

    Расширение публичного API — это правка одной строки в одном файле. Ревьюер сразу видит, что контракт изменился. Это исключает ситуации, когда новый export тихо появляется где-то в глубине сущности.

  • Безопасный рефакторинг

    Пока публичные экспорты и их контракт сохраняются, потребители не зависят от расположения внутренних файлов. Внешний код этого не заметит.

Правильно ​

Явный баррель сущности:

ts
// src/modules/order/entities/index.ts
export { OrderCard } from './ui/order-card';
export { Order, OrderStatus } from './model/types';

Внутренний импорт (напрямую, относительный путь):

ts
// src/modules/order/entities/ui/order-card.tsx
import { Order } from '../model/types';

Внешний импорт (строго через баррель):

ts
// src/pages/order/order-page.tsx
import { OrderCard, Order } from '@/modules/order/entities';

Неправильно ​

Не контролируемый публичный API:

ts
// src/modules/order/entities/index.ts
export * from './ui/order-card'; // ❌
export * from './model/types'; // ❌

Импорт собственного барреля (риск циклических ссылок):

ts
// src/modules/order/entities/ui/order-card.tsx
import { Order } from '..'; // ❌
import { Order } from '@/modules/order/entities/model'; // ❌

Импорт в обход публичного API:

ts
// src/pages/order/order-page.tsx
import { OrderCard } from '@/modules/order/entities/ui/order-card'; // ❌

Рекомендации ​

  1. Явный интерфейс, а не зеркало

    Баррель должен содержать явный список именованных реэкспортов. Использование export * from './...' нежелательно. Оно превращает границу в автоматическое зеркало, где любой внутренний export случайно становится публичным контрактом.

    Реэкспорт из вложенного барреля

    Использование export * from './subdir' допустимо только в том случае, если subdir уже имеет свой собственный index файл. В этом случае вложенная директория уже имеет свой контролируемый публичный API, и мы не экспортируем «всё подряд», а делегируем контроль известной границе.

  2. Отсутствие side effects

    Баррель должен содержать исключительно инструкции реэкспорта. Никаких импортов стилей, оборачивания компонентов в HOCи, инициализации глобального состояния или вызовов функций. Если в барреле нет исполняемого кода, у бандлера будет больше возможности безопасно вырезать неиспользуемый код.