Реэкспорт в index.ts - как упростить структуру модулей в TypeScript и JavaScript

Введение

Реэкспорт в index.ts (или index.js) часто называют паттерном barrel file. Суть простая: вы собираете экспорты из разных модулей в одну точку входа и уже из нее импортируете все необходимое в коде.

Вместо того чтобы тянуть пути наподобие:

import { Button } from "../../components/ui/button/Button"

вы работаете с более короткими и понятными:

import { Button } from "../../components"

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

Давайте начнем с базовой идеи, а затем перейдем к разным вариантам реэкспорта и практическим примерам.

Что такое реэкспорт и barrel file

Экспорт против реэкспорта

Сначала важно разделить два понятия:

• Экспорт – когда модуль напрямую объявляет сущности и делает их доступными наружу.

Пример прямого экспорта:

// button.ts
export const Button = () => {
  // Здесь мы объявляем компонент и экспортируем его напрямую
}

• Реэкспорт – когда модуль не объявляет сущности сам, а только передает наружу то, что он импортировал из других модулей.

Пример реэкспорта:

// index.ts export { Button } from "./button" // Здесь мы просто «прокидываем» Button дальше

Barrel file – это модуль, который в основном (или только) занимается реэкспортом. Обычно его называют index.ts, index.tsx, index.js или index.mjs.

Такой файл становится единой точкой входа к группе связанных модулей (компоненты, utils, сервисы и так далее).

Зачем нужен реэкспорт в index.ts

Давайте разберем практические выгоды.

1. Сокращение и унификация импортов

Вместо множества путей:

import { Button } from "../../components/ui/button"
import { Input } from "../../components/ui/form/input"
import { Checkbox } from "../../components/ui/form/checkbox"

Вы делаете один index.ts в директории components и пишете:

// components/index.ts
export { Button } from "./ui/button"
export { Input } from "./ui/form/input"
export { Checkbox } from "./ui/form/checkbox"

Теперь использование выглядит так:

import { Button, Input, Checkbox } from "../../components"

Код становится компактнее, а пути – стабильнее. Если структура папок поменяется, вы трогаете только index.ts.

2. Стабильный публичный API модуля

Barrel-файл позволяет явно определить, что считается «публичным» API папки.

Например, внутри components/ui может быть много технических файлов, но наружу вы экспортируете только нужные компоненты:

// components/ui/index.ts
export { Button } from "./button/Button"
export { Input } from "./input/Input"
// Другие внутренние файлы не экспортируем, они считаются приватными

С точки зрения потребителя достаточно знать, что есть "components/ui", а не как устроена папка внутри.

3. Уменьшение связности структуры проекта

Если вы импортируете только из index.ts, то внутренняя структура папок становится деталью реализации, а не контрактом. Это снижает хрупкость проекта: рефакторинг структуры почти не цепляет остальные файлы.

4. Удобная группировка по доменам

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

• auth
• user
• orders
• ui

Например, в папке auth могут лежать файлы loginService.ts, signupService.ts, authGuard.ts, но наружу вы дадите только удобный API через index.ts.

Основной синтаксис реэкспорта

Теперь давайте посмотрим подробные варианты синтаксиса, которые предоставляет JavaScript/TypeScript.

Реэкспорт именованных сущностей

Самый распространенный вариант.

Базовый пример

// button.ts
export const Button = () => {
  // Здесь мы объявляем сам компонент
}

// index.ts export { Button } from "./button" // Здесь мы просто говорим - реэкспортируй Button

Теперь другой модуль может написать:

// app.ts
import { Button } from "./index" // Здесь мы импортируем Button уже из index.ts

Важный момент: в index.ts мы не создаем новую сущность, а только прокидываем оригинальный экспорт.

Переименование при реэкспорте

Иногда удобно задать другое имя:

// math.ts
export const add = (a: number, b: number) => a + b

// index.ts
export { add as sum } from "./math" 
// Здесь мы говорим - экспортируй функцию add под именем sum

// app.ts
import { sum } from "./index"
// Теперь мы работаем с именем sum, хотя исходная функция называется add

Это удобно, если вы выравниваете именование в разных модулях.

Реэкспорт всего содержимого модуля

Смотрите, это более «грубый» способ: вы просто передаете наружу все именованные экспорты модуля.

Простой вариант

// utils.ts
export const formatDate = () => { /* ... */ }
export const formatPrice = () => { /* ... */ }

// index.ts
export * from "./utils" 
// Здесь мы не перечисляем конкретные сущности - все именованные экспорты улетают наружу

Теперь любой импорт из index.ts видит formatDate и formatPrice.

Но у этого синтаксиса есть нюансы и подводные камни (разберем чуть дальше).

Объединение нескольких модулей

Barrel-файл часто используют, чтобы объединить несколько модулей:

// index.ts
export * from "./math"
export * from "./string"
export * from "./date"
// Здесь мы собираем все утилиты из разных файлов в одном месте

Теперь можно:

import { add, capitalize, formatDate } from "./utils" 
// Здесь add мог прийти из math, capitalize - из string, formatDate - из date

Комбинирование явного и «звездочного» реэкспорта

Иногда вы хотите:

• импортировать все, но
• кое-что переименовать или скрыть.

Смотрите, как это можно сделать:

// math.ts
export const add = (a: number, b: number) => a + b
export const subtract = (a: number, b: number) => a - b

// index.ts export * from "./math" // Здесь мы экспортируем все как есть export { subtract as minus } from "./math" // А здесь добавляем алиас minus на тот же экспорт

Теперь потребитель увидит:

import { add, subtract, minus } from "./index"
// subtract и minus указывают на одну и ту же функцию

Если имена совпадут, явный реэкспорт перекроет результат export * from … (в TypeScript это имеет значение для типов).

Реэкспорт по умолчанию (default export)

Default-экспорт – отдельная история. Его нельзя реэкспортировать через export *; нужно явно указать default.

Базовый пример

// Button.tsx const Button = () => { // Здесь мы объявляем компонент } export default Button // Это экспорт по умолчанию

// index.ts
export { default as Button } from "./Button" 
// Здесь мы реэкспортируем default под именем Button

Теперь потребитель пишет:

import { Button } from "./index" 
// В итоге он получает тот самый default-экспорт из Button.tsx

Это распространенный паттерн для React-компонентов и не только.

Реэкспорт default без имени (редкий вариант)

Технически возможно:

// Button.tsx
export default Button

// index.ts
export { default } from "./Button" 
// Здесь мы просто прокидываем default дальше как default

Тогда потребителю придется импортировать тоже default:

import Button from "./index"
// Здесь мы импортируем default уже из index.ts

Такой стиль возможен, но для barrel-файлов обычно предпочитают именованные экспорты, чтобы проще объединять несколько сущностей.

Реэкспорт типов в TypeScript

TypeScript добавляет полезный синтаксис для типов: можно явно разделять типовые и значимые экспорты.

Реэкспорт только типов

// types.ts
export interface User {
  id: string
  name: string
}

// index.ts
export type { User } from "./types" 
// Здесь мы говорим - реэкспортируй только тип User, не тянув за собой runtime-код

Это важно для tree-shaking и для того, чтобы не добавлять лишний JavaScript-код в сборку.

Комбинирование типов и значений

// user.ts
export interface User {
  id: string
  name: string
}

export const createUser = (name: string): User => ({
  id: "1",
  name,
})

// index.ts
export type { User } from "./user" 
// Здесь реэкспортируем только тип

export { createUser } from "./user" 
// А здесь реэкспортируем функцию, которая реально будет в runtime

Теперь:

// app.ts
import { createUser } from "./index" 
// Здесь мы импортируем функцию

import type { User } from "./index" 
// А здесь мы импортируем только тип User - это не попадет в собранный JS

Как организовать index.ts в проекте

Теперь давайте перейдем к практической части: как и где создавать barrel-файлы.

Структура директив с index.ts

Представьте такую структуру:

src/
  components/
    Button/
      Button.tsx
      styles.css
      index.ts
    Input/
      Input.tsx
      index.ts
    index.ts
  pages/
    Home/
      HomePage.tsx
      index.ts
    index.ts

Локальные index.ts рядом с сущностями

Например, для компонента Button:

// components/Button/index.ts
export { default as Button } from "./Button" 
// Здесь мы делаем единый экспорт для компонента Button

Теперь вы можете импортировать так:

import { Button } from "@/components/Button"
// Внутри components/Button может поменяться структура, импорт останется прежним

Глобальный index.ts для группы

На уровень выше:

// components/index.ts
export * from "./Button"
export * from "./Input"
// Здесь мы объединяем все публичные компоненты в одном месте

Теперь можно писать:

import { Button, Input } from "@/components"

Такой прием легко масштабируется и на страницы:

// pages/index.ts
export * from "./Home"
export * from "./Profile"
export * from "./Settings"

Явные или импорт через звездочку – что выбрать

Давайте посмотрим, когда какой вариант лучше.

Когда использовать явный список

// index.ts
export { Button } from "./Button"
export { Input } from "./Input"

Плюсы:

• Явный контроль публичного API
• Легче следить, что именно доступно наружу
• Меньше шансов «случайно» вывести наружу внутренний модуль
• Проще анализировать зависимости

Такой стиль особенно хорош для библиотек, SDK или публичных модулей.

Когда использовать export * from

// index.ts
export * from "./Button"
export * from "./Input"

Плюсы:

• Быстро и удобно, меньше кода
• Подходит для проектов, где структура понятна, и нет жестких требований к публичному API

Минусы:

• Меньше контроля (легко вывести наружу лишнее)
• С ростом проекта сложнее отслеживать конфликты имен
• Тяжелее использовать auto-complete, если модулей очень много

Частый компромисс: на ближайшем уровне (рядом с сущностями) использовать export * from, а на верхнем уровне проекта – явный список экспортов.

Реэкспорт и alias путей

В TypeScript обычно настраивают path aliases, чтобы не писать длинные относительные пути.

Например, в tsconfig.json:

{
  // Здесь мы настраиваем алиасы путей
  "compilerOptions": {
    "baseUrl": "src",
    "paths": {
      "@components/*": ["components/*"],
      "@pages/*": ["pages/*"]
    }
  }
}

Теперь с barrel-файлами вы можете писать:

// src/components/index.ts
export * from "./Button"
export * from "./Input"

// src/app.ts
import { Button } from "@components" 
// Здесь мы используем алиас - он указывает на src/components/index.ts

А внутри @components/Button может быть свой локальный index.ts, который тоже делает реэкспорт.

Частые проблемы и подводные камни реэкспорта

Теперь посмотрим, где чаще всего возникают сложности.

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

Самая неприятная проблема с barrel-файлами – циклические зависимости.

Ситуация выглядит примерно так:

// A.ts
export { B } from "./index" 
// Здесь A реэкспортирует B из index.ts

// B.ts
export { A } from "./index" 
// Здесь B реэкспортирует A из index.ts

// index.ts
export * from "./A"
export * from "./B"
// Здесь мы объединяем A и B

В итоге:

• A зависит от index.ts
• index.ts зависит от B
• B зависит от index.ts
• index.ts зависит от A

Получается замкнутый круг. В runtime это может привести к undefined вместо ожидаемых значений.

Как избегать циклов

Вот несколько практичных советов:

1. Не импортируйте из barrel-файла внутри модулей, которые этот barrel формируют.
   То есть A.ts и B.ts не должны импортировать что-то из index.ts, в котором они же реэкспортируются.

2. Если модулю A нужен модуль B, импортируйте B напрямую:

// A.ts import { B } from "./B" // Здесь мы импортируем B напрямую, а не через index.ts

3. В TypeScript можно включить флаг:

"importsNotUsedAsValues": "error"

и следить за циклическими зависимостями через линтеры (например, eslint-plugin-import с правилом import/no-cycle).

4. Для доменных модулей оправдано вообще отказаться от export * и прописывать зависимости явно.

Смешивание типов и значений

Если реэкспортировать типы и значения одним export * в TypeScript, можно получить лишний код в сборке или странные ошибки.

Лучше разделять:

// user.ts
export interface User {
  id: string
}
export const createUser = () => { /* ... */ }

// index.ts export type { User } from "./user" // Здесь реэкспортируем только тип export { createUser } from "./user" // А здесь реэкспортируем функцию

Так вы явно контролируете, что попадает в runtime.

Конфликты имен при export *

Когда вы пишете:

export * from "./math"
export * from "./string"

и оба модуля экспортируют, например, функцию parse, то:

• в ES-модулях такой реэкспорт приведет к ошибке на этапе сборки (дублирующееся имя);
• вам придется переименовать экспорт хотя бы в одном модуле или использовать явный реэкспорт с alias.

Пример решения:

// math.ts
export const parse = (value: string) => Number(value)

// string.ts
export const parse = (value: unknown) => String(value)

// index.ts
export { parse as parseNumber } from "./math"
export { parse as parseString } from "./string"
// Здесь мы даем им разные имена при реэкспорте

Баррель-файлы и tree-shaking

Barrel-файлы иногда мешают инструментам сборки (Webpack, Rollup, esbuild, Vite) эффективно выкидывать неиспользуемый код, особенно если использовать export *.

Смотрите, в чем проблема:

• Если вы явно экспортируете сущности и импортируете только часть из них, современные сборщики чаще всего справляются и отбрасывают лишнее.
• Но если в index.ts написано много export * from и есть сложные связи, сборщик иногда перестраховывается и тащит лишние модули в bundle.

Что помогает:

1. Отдавать предпочтение явному экспорту, особенно в библиотеках.
2. Отдельно реэкспортировать типы (export type).
3. Проверять бандл анализаторами (Webpack Bundle Analyzer, source-map-explorer и т.п.), если размер начинает расти.

Смешивание default и именованных экспортов

Реэкспорт default и именованных сущностей в одном barrel-файле возможен, но требует аккуратности:

// Button.tsx export const Button = () => { / ... / } export default Button // Здесь default и именованный указывают на один компонент

// index.ts
export { default as Button } from "./Button"
export { Button as NamedButton } from "./Button"

Теперь:

import { Button, NamedButton } from "./index"

Это работает, но легко запутаться, что откуда приходит. Лучше придерживаться одного стиля по проекту:

• или только default для компонентов;
• или только именованные экспорты;
• или строгая договоренность: default + имя совпадает.

Практические примеры структуры с реэкспортом

Теперь давайте посмотрим более полные примеры, как можно организовать код.

Пример 1 – UI-библиотека

Представим простую структуру:

src/
  ui/
    Button/
      Button.tsx
      index.ts
    Input/
      Input.tsx
      index.ts
    Modal/
      Modal.tsx
      index.ts
    index.ts

Локальные index.ts для каждого компонента:

// ui/Button/index.ts
export { default as Button } from "./Button" 
// Здесь мы экспортируем default-экспорт под именем Button

// ui/Input/index.ts
export { default as Input } from "./Input"

// ui/Modal/index.ts
export { default as Modal } from "./Modal"

Общий index.ts:

// ui/index.ts
export * from "./Button"
export * from "./Input"
export * from "./Modal"
// Здесь мы собираем все компоненты в один модуль

Теперь в приложении:

// app.tsx
import { Button, Input, Modal } from "@/ui"
// Здесь нам достаточно знать только про "@/ui"

Если компоненты разрастутся, их структура изменится, публичный API через "@/ui" останется тем же.

Пример 2 – доменные модули

Возьмем доменную область user:

src/
  modules/
    user/
      api/
        getUser.ts
        updateUser.ts
        index.ts
      model/
        types.ts
        store.ts
        index.ts
      ui/
        UserCard.tsx
        index.ts
      index.ts

Теперь давайте наполним index.ts на разных уровнях.

index.ts для api

// modules/user/api/getUser.ts
export const getUser = async (id: string) => {
  // Здесь мы делаем запрос на сервер за данными пользователя
}

// modules/user/api/updateUser.ts
export const updateUser = async (id: string, payload: unknown) => {
  // Здесь мы отправляем изменения пользователя на сервер
}

// modules/user/api/index.ts
export { getUser } from "./getUser"
export { updateUser } from "./updateUser"
// Здесь мы явным списком формируем публичный API слоя api

index.ts для model

// modules/user/model/types.ts
export interface User {
  id: string
  name: string
}

// modules/user/model/store.ts
export const userStore = {
  // Здесь мы храним и обновляем состояние пользователя
}

// modules/user/model/index.ts
export type { User } from "./types"
export { userStore } from "./store"
// Здесь мы реэкспортируем тип и стор, разделяя типы и значения

index.ts для ui

// modules/user/ui/UserCard.tsx
import type { User } from "../model"

export const UserCard = ({ user }: { user: User }) => {
  // Здесь мы отображаем карточку пользователя
  return null
}

// modules/user/ui/index.ts
export { UserCard } from "./UserCard"
// Здесь мы создаем удобную точку входа для UI части

Глобальный index.ts домена user

// modules/user/index.ts
export * as userApi from "./api"
export * as userModel from "./model"
export * as userUi from "./ui"
// Здесь мы собираем три слоя и даем им имена пространств

Теперь вы можете использовать модуль так:

// app.ts
import { userApi, userModel, userUi } from "@/modules/user"

userApi.getUser("1") // Здесь обращаемся к api-слою userModel.userStore // Здесь используем модель userUi.UserCard // Здесь рендерим UI-компонент

Обратите внимание, как index.ts на разных уровнях создают последовательную структуру API модуля.

Пример 3 – библиотека утилит

Предположим, у вас есть несколько групп утилит:

src/
  utils/
    math/
      add.ts
      subtract.ts
      index.ts
    string/
      capitalize.ts
      trim.ts
      index.ts
    date/
      formatDate.ts
      index.ts
    index.ts

Наполним их.

Локальные barrel-файлы

// utils/math/add.ts
export const add = (a: number, b: number) => a + b

// utils/math/subtract.ts
export const subtract = (a: number, b: number) => a - b

// utils/math/index.ts
export { add } from "./add"
export { subtract } from "./subtract"
// Здесь мы явно описываем публичные функции math

// utils/string/capitalize.ts
export const capitalize = (value: string) =>
  value.charAt(0).toUpperCase() + value.slice(1)

// utils/string/trim.ts
export const trim = (value: string) => value.trim()

// utils/string/index.ts
export { capitalize } from "./capitalize"
export { trim } from "./trim"

// utils/date/formatDate.ts export const formatDate = (date: Date) => date.toISOString().split("T")[0] // Здесь мы возвращаем строку YYYY-MM-DD

// utils/date/index.ts
export { formatDate } from "./formatDate"

Главный index.ts для utils

// utils/index.ts
export * as mathUtils from "./math"
export * as stringUtils from "./string"
export * as dateUtils from "./date"
// Здесь мы структурируем доступ к утилитам по пространствам имен

Теперь в коде:

// app.ts
import { mathUtils, stringUtils, dateUtils } from "@/utils"

const sum = mathUtils.add(1, 2)
const title = stringUtils.capitalize("hello")
const today = dateUtils.formatDate(new Date())

Такой стиль особенно хорошо читается, когда у вас есть несколько логических групп функций.

Лучшие практики при использовании реэкспорта в index.ts

Подведем рекомендации, которые помогут вам использовать barrel-файлы без лишних проблем.

1. Не импортировать из index.ts внутри «его» же модулей

Если модуль участвует в формировании index.ts, он не должен импортировать из этого index.ts.

Используйте прямые пути:

// Плохо - может создать цикл
// A.ts
import { B } from "./index"

// Хорошо - прямой импорт
// A.ts
import { B } from "./B"

Так вы снижаете риск циклических зависимостей.

2. Явно контролируйте публичный API

Особенно в библиотеках:

• для публичного API – явные экспорты;
• для внутренних связей – прямые импорты между файлами;
• export * from использовать дозированно, понимая, что вы отдаете наружу.

3. Отдельно реэкспортируйте типы

В TypeScript:

• используйте export type { ... } для типов;
• используйте import type для импортов типов;

Это уменьшает размер бандла и делает код яснее.

4. Соблюдайте единый стиль по проекту

Договоритесь в команде:

• используете ли вы default-экспорты;
• как называете index-файлы (index.ts / index.tsx / main.ts);
• где создаете barrel-файлы (на каждом уровне папок или только на ключевых).

Стабильный стиль уменьшает количество «сюрпризов» при чтении чужого кода.

5. Не делайте слишком «толстые» barrel-файлы

Если index.ts импортирует и реэкспортирует десятки или сотни модулей, это:

• усложняет анализ зависимостей;
• может ухудшать tree-shaking;
• делает отладку сложнее.

Иногда разумнее разбить barrel-файлы по поддоментам, а уже их собрать на самом верхнем уровне.

---

Частозадаваемые технические вопросы по теме статьи и ответы на них

Как реэкспортировать все, кроме одной сущности

Напрямую исключить один экспорт из export * нельзя. Обходной путь – явно перечислить, что вы хотите оставить:

// original.ts
export const a = 1
export const b = 2
export const c = 3

// index.ts - хотим все кроме b
export { a, c } from "./original"
// Здесь мы явно указываем только нужные сущности

Автоматически «все кроме b» синтаксис не поддерживает.

Как правильно реэкспортировать namespace (пространство имен) в TypeScript

Если у вас устаревший namespace:

// legacy.ts
export namespace Legacy {
  export const value = 1
}

Лучше не создавать новый namespace, а просто прокинуть модуль целиком:

// index.ts
export * as Legacy from "./legacy"
// Здесь мы создаем пространство имен на уровне модулей ES

Использовать namespace-синтаксис в новом коде не рекомендуется, предпочтителен модульный подход.

Как реэкспортировать тип и значение с одним именем из разных файлов

Сделайте раздельные файлы и раздельный реэкспорт:

// userType.ts
export interface User {
  id: string
}

// userValue.ts
export const User = {
  // Здесь объект с настройками пользователя
}

// index.ts
export type { User } from "./userType"
export { User as UserConfig } from "./userValue"
// Здесь мы тип оставили под именем User, а значение переименовали

Так вы избежите конфликта и путаницы.

Как реэкспортировать тип из JavaScript-файла в TypeScript-проекте

Если исходный файл на JS:

// user.js
export const createUser = (name) => ({ id: "1", name })

В TypeScript вы не сможете экспортировать тип напрямую, но можно описать тип поверх:

// user.d.ts - файл деклараций
export interface User {
  id: string
  name: string
}

// index.ts
export { createUser } from "./user"
export type { User } from "./user"
// Здесь TypeScript подтянет тип из декларации user.d.ts

Важно иметь декларационные файлы или d.ts-типизацию для JS-модулей.

Как настроить barrel-файлы при использовании смешанных модулей CJS и ESM

Если часть кода на CommonJS, часть на ES-модулях, лучше:

1. На уровне TypeScript/ESM использовать только ESM-синтаксис (import/export).
2. Для CJS-модулей писать адаптеры:

// cjsModule.cjs
module.exports = { foo: () => {} }

// cjsAdapter.ts
import cjs = require("./cjsModule.cjs")
export const foo = cjs.foo
// Здесь мы создаем адаптер под ESM

// index.ts
export { foo } from "./cjsAdapter"
// Здесь мы реэкспортируем уже ESM-совместимую сущность

Так вы избежите проблем с различиями между require и import.