quality-avoid-barrel-imports.md

---

title: Avoid Barrel Imports from index.ts Files impact: HIGH impactDescription: Prevents tree-shaking issues and circular dependency problems tags: quality, imports, barrel, performance

Паспорт документа

• Статус документа: living standard
• Актуально на: 28 марта 2026 года
• Владелец: backend/platform-команда
• Пересмотр: при изменении инженерной практики, CI/CD, архитектурных правил или локального workflow
• Область применения: внутренние rule/reference-card документы для инженерной команды
• Связанные документы:
  • Индекс Agents
  • Команды разработки
  • Инженерные принципы

Avoid Barrel Imports from index.ts Files

Impact: HIGH

Barrel files (index.ts that re-exports everything) create problems: they defeat tree-shaking, cause circular dependencies, and make imports ambiguous.

Incorrect (barrel imports):

// widgets/header/index.ts — barrel file
export { Header } from './ui/Header';
export { HeaderActions } from './ui/HeaderActions';
export { HeaderLogo } from './ui/HeaderLogo';

// Consuming code — imports barrel instead of concrete file
import { Header } from '@/widgets/header';

Correct (direct imports):

// Import directly from the source file
import { Header } from '@/widgets/header/ui/Header';
import { HeaderLogo } from '@/widgets/header/ui/HeaderLogo';

// For shared types
import type { CurrentUserResponse } from '@/shared/api/api-types';

Exception: packages/shared/index.ts may export Zod schemas and types that are intentionally shared as a cohesive API. Keep it minimal.