Структура React-проекта — ключ к его масштабируемости, читаемости и удобству сопровождения. Чем крупнее приложение, тем важнее продуманный подход к организации директорий, разделению ответственности, повторному использованию компонентов и управлению зависимостями. Ниже описаны подходы и паттерны, используемые в современных React-проектах, включая модульную структуру, фиче-ориентированный подход, atomic design, слой архитектуры, доменные и UI-компоненты, хуки, сервисы и стили.

1. Базовая структура

Стартовая структура проекта может выглядеть так:

src/

├── assets/ # картинки, шрифты, svg

├── components/ # переиспользуемые UI-компоненты

├── features/ # фичи или модули

├── entities/ # бизнес-сущности (пользователь, пост, продукт и т.д.)

├── pages/ # маршруты / страницы

├── app/ # глобальные настройки и инициализация (роутинг, store, theming)

├── shared/ # утилиты, константы, переиспользуемые хуки и UI

└── widgets/ # композиционные UI-блоки

Этот подход популярен в feature-sliced design и хорошо масштабируется.

2. Feature-Sliced Design

Это архитектурный подход, при котором проект делится на фичи, сущности, виджеты, страницы, шаред и ядро приложения.

Структура слоёв:

src/

├── app/ # глобальные настройки, entry point

├── processes/ # бизнес-процессы (регистрация, checkout)

├── pages/ # конечные страницы (маршруты)

├── widgets/ # самостоятельные блоки UI (header, sidebar)

├── features/ # логически завершённые функции (auth, cart)

├── entities/ # бизнес-сущности (user, product, article)

├── shared/ # атомарные UI-компоненты, утилиты, api, config

└── assets/

Пример features/auth:

features/
└── auth/
├── ui/
│ └── LoginForm.tsx
├── model/
│ ├── useAuth.ts
│ └── store.ts
├── lib/
│ └── validators.ts
└── api/
└── login.ts

Пример entities/user:

entities/
└── user/
├── ui/
│ └── Avatar.tsx
├── model/
│ └── useUser.ts
└── types/
└── user.ts

3. Подход Atomic Design

Деление компонентов по уровню абстракции:

• atoms/ – кнопки, иконки, инпуты

• molecules/ – группы атомов (инпут + лейбл)

• organisms/ – сложные блоки (форма входа, карточка товара)

• templates/ – страницы без данных

• pages/ – готовые страницы с данными

Пример:

components/
├── atoms/
│ └── Button.tsx
├── molecules/
│ └── InputWithLabel.tsx
├── organisms/
│ └── LoginForm.tsx
└── templates/
└── MainLayout.tsx

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

UI-компоненты:

• Не знают про бизнес-логику

• Только отображают данные

• Чаще всего в shared/ui/

Container/Smart-компоненты:

• Владеют логикой, состоянием, запросами

• Обычно внутри features, widgets или pages

5. Папка app/

Содержит глобальные зависимости и настройки:

app/
├── App.tsx
├── index.tsx
├── router.tsx
├── store.ts
├── providers/ # провайдеры: redux, i18n, theme
└── styles/ # глобальные стили, темы

6. Хуки

Все кастомные хуки хранятся отдельно, чаще всего:

shared/hooks/
└── useDebounce.ts
└── useModal.ts

Или хуки для конкретной фичи:

features/auth/model/useAuth.ts

7. API

Если используется RTK Query, Axios или другой подход, часто выделяется директория:

shared/api/
└── base.ts
features/auth/api/login.ts
entities/user/api/getUser.ts

8. Стили

Разделяют глобальные и модульные стили:

app/styles/
└── variables.css
shared/ui/Button/
└── Button.module.scss

Можно использовать Tailwind, CSS Modules, styled-components, Emotion — в зависимости от проекта.

9. Константы, утилиты, types

shared/
├── config/ # конфиги окружения
│ └── env.ts
├── lib/ # утилиты
│ └── formatDate.ts
├── constants/ # статичные данные
│ └── routes.ts
├── types/ # глобальные типы
│ └── index.ts

10. Пример реальной структуры проекта

src/
├── app/
│ ├── App.tsx
│ ├── index.tsx
│ └── router.tsx
├── pages/
│ ├── Home/
│ │ └── HomePage.tsx
│ └── Profile/
│ └── ProfilePage.tsx
├── features/
│ └── auth/
│ ├── ui/
│ │ └── LoginForm.tsx
│ ├── model/
│ │ └── useAuth.ts
│ └── api/
│ └── login.ts
├── entities/
│ └── user/
│ ├── ui/
│ │ └── Avatar.tsx
│ └── model/
│ └── useUser.ts
├── widgets/
│ └── Header/
│ ├── Header.tsx
│ └── Logo.tsx
├── shared/
│ ├── ui/
│ │ └── Button.tsx
│ ├── hooks/
│ │ └── useWindowSize.ts
│ ├── lib/
│ │ └── formatDate.ts
│ ├── types/
│ └── config/
└── assets/
└── logo.svg

11. Интеграция с монорепозиториями (если есть)

Если проект большой и используется Monorepo (Turborepo, Nx), структура может быть:

packages/
├── ui-kit/
├── auth-feature/
├── user-entity/
├── app/
└── shared/

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

12. Папка tests/, storybook и документация

Если используется Storybook или Unit-тесты:

src/
├── components/
│ └── Button/
│ ├── Button.tsx
│ ├── Button.test.tsx
│ └── Button.stories.tsx

Такой подход к структуре React-проекта помогает избежать путаницы, улучшает читаемость кода, упрощает масштабирование и onboarding новых разработчиков. Он также способствует лучшей изоляции ответственности между слоями (UI, логика, данные, роутинг) и позволяет более эффективно работать в команде.