Re-export и barrel files

index.ts — единая точка входа в директорию

📖 Введение

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

Точно так же устроены модули в TypeScript. Когда проект растёт и модулей становится много, вам нужно каждый раз писать длинные пути импорта:

import { Button } from './components/ui/Button';
import { Card } from './components/ui/Card';
import { Modal } from './components/ui/Modal';
import { TextField } from './components/forms/TextField';
import { Select } from './components/forms/Select';

Утомительно, правда? А что если бы можно было написать просто:

import { Button, Card, Modal, TextField, Select } from './components';

Именно это и позволяют сделать re-export и barrel files — файлы-бочки, которые собирают все экспорты из папки в одну удобную точку входа. В этом уроке мы подробно разберём, как это работает, зачем нужно, и как правильно организовать код в больших проектах.

1 Что такое re-export — повторный экспорт

Re-export (повторный экспорт) — это механизм, который позволяет взять экспорт из одного модуля и «переотправить» его из другого модуля, не импортируя его в текущий файл. По сути, вы создаёте транзитную точку — что-то вроде перекрёстка, который направляет вас в нужную сторону.

Без re-export вам пришлось бы импортировать имя в файл, а затем экспортировать его обратно:

// Без re-export (длинный путь)
// файл: components/ui/index.ts
import { Button } from './Button';
import { Card } from './Card';
import { Modal } from './Modal';

export { Button };
export { Card };
export { Modal };

Это работает, но каждый раз вы создаёте временную переменную в памяти модуля. Re-export делает то же самое, но компактнее и эффективнее:

// С re-export (короткий путь)
// файл: components/ui/index.ts
export { Button } from './Button';
export { Card } from './Card';
export { Modal } from './Modal';

Разница на первый взгляд небольшая, но она важна. При re-export вы не создаёте промежуточноепривязки — TypeScript компилятор понимает, что вы просто перенаправляете экспорт, и может оптимизировать этот путь. Это особенно важно при работе с tree-shaking (мы обсудим это позже).

Аналогия: Re-export — это как пересылка письма. Вы не вскрываете конверт, не читаете письмо, а просто перенаправляете его по новому адресу. Письмо (экспорт) остаётся тем же, просто меняется точка, из которой его можно забрать.

2 Синтаксис: export { name } from './module'

Базовый синтаксис re-export выглядит так:

export { имяЭкспорта } from './путь/к/модулю';

Давайте рассмотрим конкретный пример. Допустим, у нас есть модуль с утилитами:

// utils/math.ts
export function add(a: number, b: number): number {
  return a + b;
}

export function multiply(a: number, b: number): number {
  return a * b;
}

export const PI = 3.14159;

Теперь создадим barrel file, который переэкспортирует только нужные нам функции:

// utils/index.ts
export { add, multiply } from './math';
// PI не экспортируем — он нам не нужен снаружи

Теперь кто-то извне может импортировать:

// app.ts
import { add, multiply } from './utils';

console.log(add(2, 3));       // 5
console.log(multiply(4, 5));  // 20

Вы можете переэкспортировать несколько имён из одного модуля за раз:

// utils/index.ts
export { add, multiply, PI } from './math';
export { formatDate, parseDate } from './dates';
export { validateEmail } from './validators';

Обратите внимание: после export { ... } идёт from './module'. Вы не используете import — это ключевое отличие re-export от обычного импорта с последующим экспортом.

Важно: Re-export не делает модуль доступным внутри текущего файла. Вы не сможете использовать add() в файле index.ts — вы просто перенаправляете экспорт для внешних потребителей.

3 export * from './module' — экспорт всех имён

Если вы хотите переэкспортировать все имена из модуля, не перечисляя их по одному, используйте звёздочку:

// utils/index.ts
export * from './math';
export * from './dates';
export * from './validators';

Теперь из ./utils доступны все функции из всех трёх модулей:

// app.ts
import { add, formatDate, validateEmail } from './utils';
// Всё работает!

Удобно, но осторожно! export * — это как открыть все двери в здании. Иногда это то, что нужно. Но если в двух модулях есть функции с одинаковыми именами, произойдёт конфликт:

// utils/string-helpers.ts
export function trim(str: string): string {
  return str.trim();
}

// utils/array-helpers.ts
export function trim(arr: any[]): any[] {
  return arr.filter(item => item !== undefined);
}

// utils/index.ts
export * from './string-helpers';
export * from './array-helpers';
// ❌ Конфликт имён! trim определён дважды

TypeScript не позволит этого — получите ошибку: "Exports of '*' from two modules have the same name 'trim'." В такой ситуации лучше использовать явный re-export с переименованием (об этом дальше) или экспортировать только нужные имена.

Ещё один нюанс: export * не переэкспортирует default экспорты. Если модуль экспортирует что-то по умолчанию, вам придётся обрабатывать его отдельно:

// components/Button.tsx
export default function Button() {
  return <button>Нажми меня</button>;
}

// components/index.ts
export * from './Button';
// ❌ Button по умолчанию НЕ экспортирован!

// Правильно:
export { default as Button } from './Button';

Это частый источник ошибок для новичков. Запомните: export * — только для именованных экспортов.

4 export { name as alias } from './module' — переименование при re-export

Иногда нужно переэкспортировать функцию или класс под другим именем. Это полезно, когда в вашем API есть конфликты имён или когда вы хотите дать более понятное имя экспорту:

// utils/math.ts
export function calculateSum(a: number, b: number): number {
  return a + b;
}

export function calculateProduct(a: number, b: number): number {
  return a * b;
}

// utils/index.ts
export { calculateSum as add, calculateProduct as multiply } from './math';

Теперь потребители используют короткие имена:

// app.ts
import { add, multiply } from './utils';
// А внутри utils/math.ts функции называются calculateSum и calculateProduct

Это удобно по двум причинам:

Вы можете комбинировать именованный re-export и переименование:

// utils/index.ts
export { calculateSum as add } from './math';
export { calculateProduct } from './math';  // без переименования
export { formatDate } from './dates';
export { default as Logger } from './logger';  // re-export default

5 export { default as Name } from './module' — re-export default

Мы уже упоминали, что export * не работает с default-экспортами. Но что если модуль экспортирует что-то по умолчанию, и вы хотите его переэкспортировать? Используйте синтаксис:

export { default as НовоеИмя } from './модуль';

Пример:

// components/Modal.tsx
export default function Modal({ children }: { children: React.ReactNode }) {
  return (
    <div className="modal-overlay">
      <div className="modal-content">
        {children}
      </div>
    </div>
  );
}

// components/index.ts
export { default as Modal } from './Modal';

Теперь потребитель импортирует Modal как именованный экспорт:

// app.tsx
import { Modal } from './components';
// Не import Modal from './components' — это был бы default из index.ts

Почему это важно? В React-экосистеме многие компоненты экспортируются по умолчанию. Когда вы создаёте barrel file, вы хотите, чтобы все компоненты импортировались одинаково — как именованные экспорты. Это делает код консистентным.

Вы также можете переэкспортировать default под оригинальным именем:

// components/index.ts
export { default } from './Modal';
// Теперь можно импортировать как default:
// import MyModal from './components';

Но первый вариант (с именем) обычно предпочтительнее — он делает код более явным и читаемым.

6 Что такое barrel file (файл-бочка)

Barrel file (файл-бочка) — это файл, который не содержит собственной логики. Его единственная задача — собрать экспорты из нескольких модулей и предоставить их через единую точку входа. Название происходит от бочки (barrel), в которую собирают продукцию из разных цехов.

Типичная структура проекта с barrel file:

src/
├── components/
│   ├── Button.tsx
│   ├── Card.tsx
│   ├── Modal.tsx
│   └── index.ts          ← barrel file
├── utils/
│   ├── math.ts
│   ├── dates.ts
│   └── index.ts          ← barrel file
├── services/
│   ├── api.ts
│   ├── auth.ts
│   └── index.ts          ← barrel file
└── index.ts              ← корневой barrel file

Barrel file обычно называют index.ts. Когда вы импортируете из папки, TypeScript автоматически ищет index.ts:

// Эти два импорта эквивалентны:
import { Button } from './components';
import { Button } from './components/index';

Ключевой принцип: Barrel file не должен содержать никакой логики — только re-export'ы. Это чистый фасад, витрина магазина. Если вы начнёте писать функции или переменные прямо в index.ts, вы нарушите паттерн.

Аналогия: Barrel file — это меню ресторана. В меню перечислены все блюда из кухни, но сами блюда готовятся на кухне. Вы не будете готовить еду прямо в меню — вы просто указываете, что доступно.

7 index.ts — единая точка входа директории

Файл index.ts в каждой директории выполняет роль «входной двери». Когда вы указываете путь к папке, TypeScript автоматически загружает index.ts из этой папки.

Это работает потому, что в TypeScript (и JavaScript) при импорте из директории модуль-резолвер ищет файл index.ts (или index.js) по умолчанию. Это поведение настраивается через tsconfig.json:

// tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "node",
    // или "bundler" для современных сборщиков
  }
}

Преимущества использования index.ts как точки входа:

Без barrel file пришлось бы писать:

// Без barrel file — длинные, хрупкие пути
import { Button } from './components/ui/buttons/Button';
import { Card } from './components/ui/cards/Card';
import { TextField } from './components/forms/inputs/TextField';
import { Select } from './components/forms/inputs/Select';
import { Modal } from './components/ui/overlays/Modal';

8 Как создать barrel file для папки с модулями

Давайте пошагово создадим barrel file для типичной папки с компонентами. Представим, что у нас есть проект с компонентами UI:

// components/Button.tsx
import React from 'react';

interface ButtonProps {
  children: React.ReactNode;
  variant?: 'primary' | 'secondary' | 'danger';
  size?: 'sm' | 'md' | 'lg';
  onClick?: () => void;
}

export function Button({ children, variant = 'primary', size = 'md', onClick }: ButtonProps) {
  return (
    <button
      className={`btn btn-${variant} btn-${size}`}
      onClick={onClick}
    >
      {children}
    </button>
  );
}

// components/Card.tsx
import React from 'react';

interface CardProps {
  title: string;
  children: React.ReactNode;
}

export function Card({ title, children }: CardProps) {
  return (
    <div className="card">
      <h3 className="card-title">{title}</h3>
      <div className="card-body">{children}</div>
    </div>
  );
}

// components/Modal.tsx
import React, { useEffect } from 'react';

interface ModalProps {
  isOpen: boolean;
  onClose: () => void;
  children: React.ReactNode;
}

export function Modal({ isOpen, onClose, children }: ModalProps) {
  useEffect(() => {
    const handleEscape = (e: KeyboardEvent) => {
      if (e.key === 'Escape') onClose();
    };
    if (isOpen) {
      document.addEventListener('keydown', handleEscape);
    }
    return () => document.removeEventListener('keydown', handleEscape);
  }, [isOpen, onClose]);

  if (!isOpen) return null;

  return (
    <div className="modal-overlay" onClick={onClose}>
      <div className="modal-content" onClick={e => e.stopPropagation()}>
        {children}
      </div>
    </div>
  );
}

Теперь создаём barrel file components/index.ts:

// components/index.ts
export { Button } from './Button';
export { Card } from './Card';
export { Modal } from './Modal';

// Также можно реэкспортировать типы
export type { ButtonProps } from './Button';
export type { CardProps } from './Card';
export type { ModalProps } from './Modal';

Теперь можно импортировать всё из одной точки:

// app.tsx
import { Button, Card, Modal, ButtonProps } from './components';

function App() {
  return (
    <div>
      <Card title="Привет">
        <p>Это контент карточки</p>
        <Button variant="primary">Нажми</Button>
      </Card>
    </div>
  );
}

Обратите внимание: export type — это отдельный синтаксис для экспорта типов. Он используется, потому что типы не существуют во время выполнения и tree-shaking может их удалить.

9 Структура проекта с barrel files

Вот как выглядит типичный проект с barrel files на каждом уровне:

src/
├── index.ts                 ← корневой barrel (вход в приложение)
├── components/
│   ├── index.ts             ← barrel для компонентов
│   ├── ui/
│   │   ├── index.ts         ← barrel для UI-компонентов
│   │   ├── Button.tsx
│   │   ├── Card.tsx
│   │   ├── Modal.tsx
│   │   └── TextField.tsx
│   ├── forms/
│   │   ├── index.ts         ← barrel для форм
│   │   ├── LoginForm.tsx
│   │   └── RegistrationForm.tsx
│   └── layout/
│       ├── index.ts         ← barrel для компонентов макета
│       ├── Header.tsx
│       ├── Footer.tsx
│       └── Sidebar.tsx
├── hooks/
│   ├── index.ts             ← barrel для хуков
│   ├── useAuth.ts
│   ├── useTheme.ts
│   └── useLocalStorage.ts
├── services/
│   ├── index.ts             ← barrel для сервисов
│   ├── api.ts
│   ├── auth.ts
│   └── storage.ts
├── types/
│   ├── index.ts             ← barrel для типов
│   ├── user.ts
│   ├── api.ts
│   └── common.ts
└── utils/
    ├── index.ts             ← barrel для утилит
    ├── formatters.ts
    ├── validators.ts
    └── helpers.ts

Каждый index.ts выглядит так:

// src/components/index.ts
export * from './ui';
export * from './forms';
export * from './layout';

// src/components/ui/index.ts
export { Button } from './Button';
export { Card } from './Card';
export { Modal } from './Modal';
export { TextField } from './TextField';

// src/hooks/index.ts
export { useAuth } from './useAuth';
export { useTheme } from './useTheme';
export { useLocalStorage } from './useLocalStorage';

// src/types/index.ts
export type { User, UserRole } from './user';
export type { ApiResponse, ApiError } from './api';
export type { Nullable, Optional } from './common';

Теперь импорты в приложении выглядят чисто и последовательно:

// src/app.tsx
import { Button, Card, Modal } from './components';
import { useAuth, useTheme } from './hooks';
import { apiClient } from './services';
import type { User, ApiResponse } from './types';
import { formatDate, validateEmail } from './utils';

Обратите внимание на сквозной стиль: все импорты идут из одной точки на уровень выше. Это делает код предсказуемым и удобным для навигации.

10 Преимущества: чистые импорты, рефакторинг, инкапсуляция

Barrel files предоставляют несколько важных преимуществ:

1. Чистые импорты

Вместо множества длинных импортов — один короткий. Это уменьшает когнитивную нагрузку и делает код чище:

// ❌ Без barrel files — хаос
import { Button } from './components/ui/Button';
import { Card } from './components/ui/Card';
import { Modal } from './components/ui/Modal';
import { TextField } from './components/forms/TextField';
import { Select } from './components/forms/Select';
import { useAuth } from './hooks/useAuth';
import { useTheme } from './hooks/useTheme';
import { formatDate } from './utils/formatters';
import { validateEmail } from './utils/validators';

// ✅ С barrel files — порядок
import { Button, Card, Modal } from './components';
import { TextField, Select } from './components/forms';
import { useAuth, useTheme } from './hooks';
import { formatDate, validateEmail } from './utils';

2. Рефакторинг без боли

Если вы решите переместить компонент из одной папки в другую, вам нужно обновить только barrel file. Все импорты в остальном коде останутся без изменений:

// Было:
// components/Button.tsx
// components/index.ts: export { Button } from './Button';

// Стало:
// components/ui/Button.tsx
// components/ui/index.ts: export { Button } from './Button';
// components/index.ts: export * from './ui';

// Импорты в остальном коде НЕ ИЗМЕНИЛИСЬ!
import { Button } from './components';  // ✅ Всё работает

3. Инкапсуляция

Barrel file позволяет скрыть внутреннюю структуру модуля. Потребители видят только то, что вы решили показать:

// utils/index.ts
// Экспортируем только публичный API
export { formatDate, parseDate } from './dates';
export { validateEmail, validatePassword } from './validators';

// НЕ экспортируем внутренние функции:
// - _formatDateInternal()
// - _parseDateRaw()
// - REGEX_PATTERNS

4. Предсказуемость

Когда все проекты используют barrel files, разработчики знают: чтобы найти экспорт, нужно посмотреть index.ts родительской папки. Это создаёт единый стандарт навигации.

5. Типобезопасность

Barrel files прекрасно работают с TypeScript. Вы можете реэкспортировать как значения, так и типы:

// types/index.ts
export type { User, CreateUserDTO, UpdateUserDTO } from './user';
export type { Product, ProductCategory } from './product';
export { ErrorCodes } from './errors';  // значение (enum)

⚠️ Недостатки barrel files: bundle size, производительность, circular deps

Как и любой паттерн, barrel files не лишены недостатков. Важно понимать их, чтобы принимать обоснованные решения:

1. Увеличение размера бандла

Если вы используете export * from в barrel file, сборщик может не определить, какие экспорты реально используются. Это приводит к тому, что в бандл попадает больше кода, чем нужно.

// utils/index.ts
export * from './heavy-module';
// heavy-module экспортирует 50 функций
// Вы используете только 2 из них
// Но сборщик не может это определить — попадут все 50

2. Проблемы с tree-shaking

Tree-shaking — это процесс удаления неиспользуемого кода. Barrel files могут мешать tree-shaking, потому что создают дополнительный слой абстракции. Современные сборщики (Webpack 5, Rollup, Vite) справляются с этим лучше, но проблема остаётся:

// Может привести к проблемам с tree-shaking:
import { buttonStyles } from './styles';
// Если styles/index.ts экспортирует всё через export *,
// сборщик может не определить, что buttonStyles — единственный нужный экспорт

3. Циклические зависимости

Barrel files создаютбольшезависимости между модулями. Если модуль A импортирует из barrel B, а barrel B реэкспортирует из модуля C, который импортирует из модуля A — возникает цикл:

// utils/helpers.ts
import { formatDate } from '../utils';  // ← импорт из barrel!
// barrel экспортирует formatDate из './dates'
// dates.ts импортирует из helpers.ts
// Цикл!

4. Медленная компиляция

В больших проектах с множеством barrel files время компиляции может увеличиться, потому что TypeScript должен разрешать больше зависимостей.

Как минимизировать недостатки:

11 Практический пример: структура проекта с компонентами

Давайте создадим полноценный пример проекта с barrel files. Представим, что мы строим библиотеку UI-компонентов:

// src/components/ui/Button/Button.tsx
import React from 'react';

export interface ButtonProps {
  children: React.ReactNode;
  variant?: 'primary' | 'secondary' | 'outline';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  loading?: boolean;
  onClick?: () => void;
}

export function Button({
  children,
  variant = 'primary',
  size = 'md',
  disabled = false,
  loading = false,
  onClick
}: ButtonProps) {
  return (
    <button
      className={`btn btn-${variant} btn-${size}`}
      disabled={disabled || loading}
      onClick={onClick}
    >
      {loading ? 'Загрузка...' : children}
    </button>
  );
}

// src/components/ui/Button/index.ts
export { Button } from './Button';
export type { ButtonProps } from './Button';

// src/components/ui/Input/Input.tsx
import React from 'react';

export interface InputProps {
  label: string;
  value: string;
  onChange: (value: string) => void;
  placeholder?: string;
  error?: string;
  type?: 'text' | 'password' | 'email' | 'number';
}

export function Input({
  label,
  value,
  onChange,
  placeholder,
  error,
  type = 'text'
}: InputProps) {
  return (
    <div className="input-group">
      <label className="input-label">{label}</label>
      <input
        type={type}
        value={value}
        onChange={e => onChange(e.target.value)}
        placeholder={placeholder}
        className={`input ${error ? 'input-error' : ''}`}
      />
      {error && <span className="input-error-text">{error}</span>}
    </div>
  );
}

// src/components/ui/Input/index.ts
export { Input } from './Input';
export type { InputProps } from './Input';

// src/components/ui/index.ts
export { Button } from './Button';
export { Input } from './Input';

export type { ButtonProps } from './Button';
export type { InputProps } from './Input';

// src/components/index.ts
export * from './ui';
export * from './forms';
export * from './layout';

Теперь потребитель использует компоненты так:

// Простой импорт из библиотеки
import { Button, Input } from 'my-ui-lib';

function LoginForm() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');

  return (
    <form>
      <Input
        label="Email"
        type="email"
        value={email}
        onChange={setEmail}
        placeholder="your@email.com"
      />
      <Input
        label="Пароль"
        type="password"
        value={password}
        onChange={setPassword}
      />
      <Button variant="primary">Войти</Button>
    </form>
  );
}

Потребителю не нужно знать, что Button лежит в components/ui/Button/Button.tsx. Barrel file скрывает эту деталь.

12 Barrel files в реальных фреймворках (React, Vue)

Большинство современных фреймворков и библиотек используют barrel files. Давайте посмотрим на реальные примеры:

React

В React все компоненты экспортируются из одного модуля:

// Все компоненты React доступны из 'react'
import { useState, useEffect, useCallback, useMemo } from 'react';

// Это работает благодаря barrel file в пакете React
// react/index.js (упрощённо)
// export { useState } from './hooks/useState';
// export { useEffect } from './hooks/useEffect';
// export { useCallback } from './hooks/useCallback';
// ... и так далее

Material-UI / MUI

MUI — отличный пример использования barrel files в библиотеке компонентов:

// Импорт компонентов MUI
import {
  Button,
  TextField,
  Dialog,
  DialogTitle,
  DialogContent,
  DialogActions,
  Snackbar,
  Alert
} from '@mui/material';

// Все компоненты доступны из одного модуля
// Благодаря barrel files внутри пакета MUI

Vue

// Vue также использует barrel files
import { createApp, ref, computed, watch } from 'vue';

// Vuetify — библиотека компонентов для Vue
import { VBtn, VCard, VTextField } from 'vuetify/components';

Angular

// Angular NgModule экспортует компоненты через barrel
// components/index.ts
export { HeaderComponent } from './header.component';
export { FooterComponent } from './footer.component';
export { SidebarComponent } from './sidebar.component';

// В модуле:
@NgModule({
  imports: [CommonModule],
  declarations: [HeaderComponent, FooterComponent, SidebarComponent],
  exports: [HeaderComponent, FooterComponent, SidebarComponent]
})
export class ComponentsModule {}

Redux / Zustand

// store/index.ts — barrel file для store
export { store } from './store';
export { useAppDispatch, useAppSelector } from './hooks';
export type { RootState, AppDispatch } from './store';

// Использование:
import { useAppDispatch, useAppSelector } from '../store';

Barrel files — это отраслевой стандарт. Практически любая серьёзная библиотека их использует. Понимание этого паттерна критически важно для работы с современным JavaScript-стеком.

13 Оптимизация импортов с barrel files

Barrel files можно использовать для оптимизации того, что именно доступно из модуля. Вот несколько стратегий:

Стратегия 1: Избирательный экспорт

Вместо export * экспортируйте только то, что нужно потребителям:

// utils/index.ts
// ❌ Плохо — экспортирует ВСЁ, включая внутренние функции
export * from './math';
export * from './string-utils';
export * from './date-utils';

// ✅ Хорошо — экспортирует только публичный API
export { add, subtract, multiply, divide } from './math';
export { capitalize, slugify, truncate } from './string-utils';
export { formatDate, parseDate, daysBetween } from './date-utils';

Стратегия 2: Разделение barrel files

Если модуль большой, создайте несколько barrel files для разных подмодулей:

// components/index.ts — общий barrel
export * from './ui';
export * from './forms';
export * from './layout';

// components/ui/index.ts — barrel только для UI
export { Button } from './Button';
export { Input } from './Input';

// components/forms/index.ts — barrel только для форм
export { LoginForm } from './LoginForm';
export { RegistrationForm } from './RegistrationForm';

Стратегия 3: Lazy-loading через barrel files

Barrel files можно комбинировать с динамическими импортами:

// Lazy-загрузка компонентов
const HeavyChart = lazy(() => import('./components/charts/HeavyChart'));
const ReportBuilder = lazy(() => import('./components/reports/ReportBuilder'));

// А легкие компоненты — обычный импорт
import { Button, Input } from './components';

Стратегия 4: Path aliases

Комбинируйте barrel files с path aliases в tsconfig.json:

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@components/*": ["components/*"],
      "@hooks/*": ["hooks/*"],
      "@utils/*": ["utils/*"],
      "@services/*": ["services/*"],
      "@types/*": ["types/*"]
    }
  }
}

// Теперь импорты выглядят ещё чище:
import { Button, Input } from '@components';
import { useAuth } from '@hooks';
import { formatDate } from '@utils';

❌ Типичные ошибки при работе с re-export

Ошибка 1: Экспорт несуществующего имени

// math.ts
export function add(a: number, b: number) { return a + b; }

// index.ts
export { add, subtract } from './math';
// ❌ Ошибка: "Module '"./math"' has no exported member 'subtract'"

Ошибка 2: Конфликт имён при export *

// module-a.ts
export function helper() { /* ... */ }

// module-b.ts
export function helper() { /* ... */ }

// index.ts
export * from './module-a';
export * from './module-b';
// ❌ Ошибка: "Exports of '*' from two modules have the same name 'helper'"

Ошибка 3: Забыли про default export

// Button.tsx
export default function Button() { /* ... */ }

// index.ts
export * from './Button';
// ❌ Button (default) не экспортирован!

// Правильно:
export { default as Button } from './Button';

Ошибка 4: Циклические зависимости

// services/user.ts
import { formatDate } from '../utils';
// utils/index.ts реэкспортирует formatDate из './dates'
// dates.ts импортирует что-то из services/user.ts
// ❌ Циклическая зависимость!

Ошибка 5: Barrel file с логикой

// ❌ Плохо — barrel file содержит логику
// components/index.ts
export function createComponent() {
  // какая-то логика
}

export { Button } from './Button';

// ✅ Хорошо — barrel file только re-export'ы
// components/index.ts
export { Button } from './Button';
export { Card } from './Card';

Ошибка 6: Re-export через import

// ❌ Неэффективно — создаёт промежуточную переменную
import { Button } from './Button';
export { Button };

// ✅ Правильно — используйте синтаксис re-export
export { Button } from './Button';

🌳 Barrel files и tree-shaking

Tree-shaking — это процесс удаления неиспользуемого кода из финального бандла. Barrel files могут как помогать, так и мешать tree-shaking.

Как tree-shaking работает:

// utils/index.ts
export { add } from './math';
export { subtract } from './math';
export { multiply } from './math';
export { divide } from './math';

// app.ts
import { add } from './utils';
// Tree-shaking удалит subtract, multiply, divide
// В бандл попадёт только add

Когда tree-shaking НЕ работает с barrel files:

// ❌ Проблема с export * — сборщик не может определить границы
// utils/index.ts
export * from './math';
export * from './strings';
export * from './dates';

// Сборщик не знает, какие именно имена используются
// Может включить весь код из всех модулей

Решение — используйте именованный re-export:

// ✅ Tree-shaking работает лучше с именованным экспортом
// utils/index.ts
export { add, subtract, multiply, divide } from './math';
export { capitalize, slugify } from './strings';
export { formatDate, parseDate } from './dates';

// app.ts
import { add, formatDate } from './utils';
// Tree-shaking удалит неиспользуемые экспорты

Современные сборщики и barrel files:

Совет: Добавьте в package.json вашей библиотеки:

// package.json
{
  "sideEffects": false
}

Это сообщает сборщику, что модули не имеют побочных эффектов, и tree-shaking может работать агрессивнее.

💡 Рекомендации по организации кода

На основе лучшего опыта сообщества, вот рекомендации по использованию barrel files:

Золотое правило: Barrel file — это фасад, интерфейс модуля. Он должен быть тонким, предсказуемым и стабильным. Все изменения внутренней структуры должны происходить за этим фасадом, не затрагивая потребителей.

🔮 Продвинутые паттерны с barrel files

Паттерн: Namespace re-export

Иногда полезно группировать экспорты по namespace'ам:

// api/index.ts
import * as authApi from './auth';
import * as usersApi from './users';
import * as productsApi from './products';

export const api = {
  auth: authApi,
  users: usersApi,
  products: productsApi,
};

// Использование:
import { api } from './api';
const user = await api.users.getById(1);

Паттерн: Conditional re-export

// types/index.ts
export type { User, Admin } from './user';
export type { Product } from './product';

// Условный экспорт в зависимости от окружения
if (process.env.NODE_ENV === 'development') {
  export { debugTools } from './debug';
}

Паттерн: Re-export с префиксом

// components/index.ts
// Добавляем префикс для уникальности
export { Button as UiButton } from './Button';
export { Card as UiCard } from './Card';
export { Modal as UiModal } from './Modal';

// Теперь можно безопасно импортировать из разных библиотек:
import { UiButton } from './components';
import { Button as LibButton } from 'other-library';

Паттерн: Barrel file с factory functions

// services/index.ts
export { createAuthService } from './auth';
export { createUserService } from './users';
export { createProductService } from './products';

// Фабрики позволяют инжектировать зависимости
const authService = createAuthService(config);
const userService = createUserService(authService);

✅ Итоги урока

В этом уроке мы подробно изучили механизм re-export и barrel files в TypeScript. Давайте подведём итоги:

Barrel files — это мощный инструмент для организации кода в больших проектах. Используйте их с умом, помня о trade-offs, и ваш код станет чище, проще и поддерживаемее.