frontend-style-guide/parts/7-project-structure.md

title

title
Структура проекта

Структура проекта

Раздел описывает базовую структуру проекта и принципы организации модулей на уровне папок и файлов.

Базовая структура проекта

Хорошо

src/
├── app/                  # Инициализация приложения, роутинг, провайдеры
│   ├── config/           # Конфигурации и константы уровня приложения
│   ├── providers/        # Провайдеры и обёртки приложения
│   ├── routing/          # Конфигурация маршрутов
│   ├── styles/           # Глобальные стили, CSS-переменные, custom media
│   └── index.ts          # Публичный API слоя
├── screens/              # Экраны приложения
│   └── profile/          # Экран профиля
│       ├── profile.screen.tsx
│       └── index.ts
├── layouts/              # Общие шаблоны и каркасы страниц
│   └── main-layout/      # Основной layout
│       ├── main-layout.layout.tsx
│       └── index.ts
├── widgets/              # Крупные блоки интерфейса
│   └── header/           # Виджет шапки
│       ├── header.widget.tsx
│       └── index.ts
├── features/             # Пользовательские сценарии
│   └── auth-by-email/    # Авторизация по email
│       ├── ui/
│       │   └── login-form.ui.tsx
│       ├── model/
│       │   └── auth-by-email.store.ts
│       ├── auth-by-email.feature.tsx
│       └── index.ts
├── entities/             # Бизнес-сущности
│   └── user/             # Сущность пользователя
│       ├── model/
│       │   └── user.store.ts
│       ├── user.entity.tsx
│       └── index.ts
└── shared/               # Общие ресурсы проекта
    ├── ui/               # Повторно используемые UI-элементы
    │   └── icon/
    │       ├── styles/
    │       │   └── icon.module.css
    │       ├── types/
    │       │   └── icon.interface.ts
    │       ├── icon.ui.tsx
    │       └── index.ts
    ├── lib/              # Утилиты и хелперы
    ├── services/         # Общие сервисы и клиенты
    ├── config/           # Общие конфигурации
    └── assets/           # Ресурсы
        ├── images/       # Изображения
        ├── icons/        # Иконки
        ├── fonts/        # Шрифты
        └── video/        # Видео

Плохо

// Плохо: слои смешаны, нет понятных границ и публичного API.
src/
├── components/
├── api/
├── styles/
└── user.ts

Правила организации

• В слоях FSD (features, entities, widgets, screens и т.д.) ui/ используется только для дочерних элементов, которые относятся к модулю и не экспортируются отдельно. Главные компоненты, которые составляют сам слой, держат собственные *.feature.tsx, *.widget.tsx и т. п., а ui/ служит для вспомогательных мелких компонентов.

• В shared/ui/ хранятся базовые UI-элементы/компоненты, которыми пользуются сразу несколько модулей; в этом случае они экспортируются наружу и не считаются «дочерними» для слоя.

• Если модуль строится вокруг «главного» компонента (*.feature.tsx, *.screen.tsx, *.widget.tsx), помещайте его в корень модуля и экспортируйте через index.ts. Проверяйте, что ui/ не используется просто как «контейнер» слоя.

• Каждый слой и модуль хранится в собственной папке.

• Внутренние реализации разделяются на ui/, model/, styles/, helpers/, lib/, api/.

• Публичный API модуля объявляется в index.ts.

• Внутренние файлы не импортируются напрямую извне.

• Не смешивать ответственность разных слоёв в одном модуле.