Compare commits
2 Commits
1950c3612a
...
f2358da397
| Author | SHA1 | Date | |
|---|---|---|---|
| f2358da397 | |||
| bf792f6159 |
4
.gitignore
vendored
4
.gitignore
vendored
@@ -40,3 +40,7 @@ yarn-error.log*
|
||||
# typescript
|
||||
*.tsbuildinfo
|
||||
next-env.d.ts
|
||||
|
||||
# generated sprites
|
||||
/public/sprites/
|
||||
/src/ui/svg-sprite/
|
||||
|
||||
66
AGENTS.md
66
AGENTS.md
@@ -1,65 +1,11 @@
|
||||
# AGENTS.md
|
||||
# AGENTS.md — Маршрутизатор задач агента
|
||||
|
||||
Инструкции для AI-ассистента, работающего с этим проектом.
|
||||
Этот файл определяет, какую документацию агент обязан прочитать перед выполнением задачи.
|
||||
|
||||
## Главная директива
|
||||
## Разработка
|
||||
|
||||
Перед выполнением любой задачи ассистент обязан свериться со стайлгайдом проекта: [`ai/nextjs-style-guide/README.md`](./ai/nextjs-style-guide/README.md).
|
||||
Если задача связана с разработкой (написание кода, рефакторинг, исправление багов, добавление фич, работа с компонентами, API и т.д.), агент **обязан** прочитать и следовать:
|
||||
|
||||
Стайлгайд — единственный источник истины по архитектуре, стеку, оформлению кода и работе с данными. При расхождении между стайлгайдом и пользовательским запросом ассистент задаёт уточняющий вопрос, а не отступает молча.
|
||||
👉 [ai/nextjs-style-guide/DEVELOP.md](./ai/nextjs-style-guide/DEVELOP.md)
|
||||
|
||||
Запрещено писать код «по общим знаниям Next.js / React / TypeScript». Любое решение принимается по правилам этого проекта.
|
||||
|
||||
## Архитектура — фундамент проекта
|
||||
|
||||
Архитектура SLM (Scoped Layered Module Design) — **самое важное в проекте**. Это не правило «при создании нового модуля», а сквозной принцип, применяемый **всегда**: при чтении кода, при правке одной строки, при добавлении импорта, при рефакторинге, при обсуждении решения.
|
||||
|
||||
Без соблюдения архитектуры проект превращается в бардак. Поэтому каждое действие проверяется на соответствие SLM.
|
||||
|
||||
Ключевые принципы, которые ассистент держит в голове постоянно:
|
||||
|
||||
- **Строгое разделение бизнес-логики и инфраструктуры.** Инфраструктура (`shared`, API-клиенты, транспорт, конфигурация) ничего не знает о бизнесе. Бизнес-модули используют инфраструктуру только через её публичный API.
|
||||
- **Направление зависимостей — только сверху вниз по слоям.** Боковые и обратные связи в обход публичного API запрещены.
|
||||
- **Публичный API модуля — единственная точка входа.** Импорт во внутренности чужого модуля запрещён.
|
||||
- **Импорты — через алиасы слоёв.** Префикс `@/` не используется.
|
||||
|
||||
Перед любым действием ассистент задаёт себе вопросы: к какому слою относится код? Не нарушается ли направление зависимостей? Не смешиваются ли бизнес и инфраструктура? Использую ли я публичный API модуля?
|
||||
|
||||
Обязательные к чтению документы по архитектуре:
|
||||
|
||||
- [Архитектура: Обзор](./ai/nextjs-style-guide/basics/architecture/index.md)
|
||||
- [Слои](./ai/nextjs-style-guide/basics/architecture/reference/layers.md)
|
||||
- [Модули](./ai/nextjs-style-guide/basics/architecture/reference/modules.md)
|
||||
- [Сегменты](./ai/nextjs-style-guide/basics/architecture/reference/segments.md)
|
||||
|
||||
## Базовые правила (читать всегда)
|
||||
|
||||
- [Технологии и библиотеки](./ai/nextjs-style-guide/basics/tech-stack.md) — разрешённый стек.
|
||||
- [Именование](./ai/nextjs-style-guide/basics/naming.md)
|
||||
- [Стиль кода](./ai/nextjs-style-guide/basics/code-style.md)
|
||||
- [Типизация](./ai/nextjs-style-guide/basics/typing.md)
|
||||
- [Документирование](./ai/nextjs-style-guide/basics/documentation.md)
|
||||
|
||||
## Контекстные разделы (читать по теме задачи)
|
||||
|
||||
Полный перечень разделов стайлгайда — в его оглавлении: [`ai/nextjs-style-guide/README.md`](./ai/nextjs-style-guide/README.md). Это источник истины: AGENTS.md не дублирует список разделов, чтобы избежать рассинхронизации. Перед задачей ассистент открывает оглавление стайлгайда и выбирает релевантные разделы (компоненты, страницы App Router, данные REST/realtime, стили, SVG-спрайты, шаблоны и генерация, установка и настройка инструментов и т. д.).
|
||||
|
||||
При появлении новых разделов в стайлгайде ассистент учитывает их автоматически — через оглавление, без правок этого файла.
|
||||
|
||||
## Запреты
|
||||
|
||||
- Импорт во внутренности чужих модулей в обход публичного API.
|
||||
- Бизнес-логика в `shared`; инфраструктура внутри бизнес-модулей.
|
||||
- Прямые `fetch` или `useSWR` в компонентах. В клиентских компонентах данные получают только через хуки модуля API; в серверных — прямым вызовом метода API-клиента.
|
||||
- Использование зависимостей вне [tech-stack.md](./ai/nextjs-style-guide/basics/tech-stack.md) без согласования с пользователем.
|
||||
- Префикс `@/` в импортах — все пути идут через алиасы слоёв.
|
||||
- Отступления от стайлгайда «ради скорости» или «потому что так короче».
|
||||
|
||||
## Коммуникация
|
||||
|
||||
- Язык общения — русский.
|
||||
- При неоднозначности задачи — уточняющий вопрос, без догадок.
|
||||
|
||||
## Коммиты
|
||||
|
||||
Коммиты создаются по правилам семантических коммитов через skill `commit`.
|
||||
Этот файл содержит строгий порядок чтения документации. Агент должен следовать ему **без исключений**.
|
||||
|
||||
29
README.md
29
README.md
@@ -15,20 +15,23 @@
|
||||
|
||||
## Архитектура
|
||||
|
||||
Проект использует кастомизированный FSD (Feature-Sliced Design):
|
||||
Проект использует SLM Design — модульную архитектуру с вертикальной организацией домена.
|
||||
|
||||
```
|
||||
src/
|
||||
├── app/ # Роутинг Next.js, провайдеры, глобальные стили
|
||||
├── screens/ # Собранные страницы (UI)
|
||||
├── layouts/ # Каркасы и шаблоны страниц
|
||||
├── widgets/ # Крупные самостоятельные блоки интерфейса
|
||||
├── features/ # Пользовательские сценарии
|
||||
├── entities/ # Бизнес-сущности
|
||||
└── shared/ # Переиспользуемый код (UI, утилиты, типы)
|
||||
├── app/ # Роутинг Next.js и точка входа приложения
|
||||
├── layouts/ # Каркасы страниц (header, footer, sidebar)
|
||||
├── screens/ # Контент конкретных страниц
|
||||
├── widgets/ # Составные блоки интерфейса, не привязанные к домену
|
||||
├── business/ # Бизнес-домены (auth, catalog, orders)
|
||||
├── infrastructure/ # Техсервисы (theme, i18n, API-адаптеры)
|
||||
├── ui/ # UI-кит без бизнес-логики
|
||||
└── shared/ # Общие ресурсы (утилиты, типы, стили, спрайты)
|
||||
```
|
||||
|
||||
Зависимости идут строго сверху вниз: `app` -> `screens` -> `layouts` -> `widgets` -> `features` -> `entities` -> `shared`.
|
||||
Зависимости идут строго сверху вниз: `app` → `[layouts | screens]` → `widgets` → `business` → `infrastructure` → `ui` → `shared`.
|
||||
|
||||
Подробнее: [Архитектура SLM](./ai/nextjs-style-guide/basics/architecture/index.md).
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
@@ -44,13 +47,12 @@ npm run dev
|
||||
Модули создаются из шаблонов `.templates/`:
|
||||
|
||||
```bash
|
||||
npx @gromlab/create component button src/shared/ui
|
||||
npx @gromlab/create feature auth src/features
|
||||
npx @gromlab/create module auth src/business
|
||||
npx @gromlab/create widget header src/widgets
|
||||
npx @gromlab/create entity user src/entities
|
||||
npx @gromlab/create layout admin src/layouts
|
||||
npx @gromlab/create screen profile src/screens
|
||||
npx @gromlab/create store auth src/shared/model
|
||||
npx @gromlab/create module button src/ui
|
||||
npx @gromlab/create store auth src/shared
|
||||
```
|
||||
|
||||
## Скрипты
|
||||
@@ -62,3 +64,4 @@ npx @gromlab/create store auth src/shared/model
|
||||
| `npm run start` | Запуск продакшен-сервера |
|
||||
| `npm run lint` | Проверка кода (Biome) |
|
||||
| `npm run format` | Форматирование кода (Biome) |
|
||||
| `npm run sprite` | Генерация SVG-спрайтов |
|
||||
|
||||
103
ai/nextjs-style-guide/DEVELOP.md
Normal file
103
ai/nextjs-style-guide/DEVELOP.md
Normal file
@@ -0,0 +1,103 @@
|
||||
---
|
||||
title: Гид для агента
|
||||
description: Что AI-агент обязан прочитать перед началом работы, а что — по задаче.
|
||||
---
|
||||
|
||||
# Обязательное чтение перед началом работы
|
||||
|
||||
Этот документ определяет **строгий порядок действий агента перед выполнением любых задач**.
|
||||
|
||||
## Общее правило
|
||||
|
||||
Перед началом работы над **любой задачей** агент **обязан ознакомиться с базовой документацией проекта**.
|
||||
|
||||
Нарушение этого порядка считается ошибкой.
|
||||
|
||||
---
|
||||
|
||||
## Порядок обязательного чтения
|
||||
|
||||
Агент должен читать документацию **строго в следующем порядке**:
|
||||
|
||||
### 1. Архитектура (КРИТИЧЕСКИ ВАЖНО)
|
||||
|
||||
* [Архитектура: Обзор](./basics/architecture/index.md)
|
||||
* [Архитектура: Слои](./basics/architecture/reference/layers.md)
|
||||
* [Архитектура: Модули](./basics/architecture/reference/modules.md)
|
||||
* [Архитектура: Сегменты](./basics/architecture/reference/segments.md)
|
||||
|
||||
**Архитектура — это самое важное в проекте.**
|
||||
|
||||
Агент обязан:
|
||||
|
||||
* строго понимать архитектурный подход (SLM)
|
||||
* соблюдать архитектуру **на 100% без отклонений**
|
||||
* не предлагать решений, нарушающих архитектурные принципы
|
||||
* не упрощать архитектуру даже ради скорости выполнения задачи
|
||||
|
||||
Любое нарушение архитектуры недопустимо.
|
||||
|
||||
---
|
||||
|
||||
### 2. Базовые правила
|
||||
|
||||
После архитектуры необходимо изучить:
|
||||
|
||||
* [Технологии и библиотеки](./basics/tech-stack.md)
|
||||
* [Именование](./basics/naming.md)
|
||||
* [Стиль кода](./basics/code-style.md)
|
||||
* [Документирование](./basics/documentation.md)
|
||||
* [Типизация](./basics/typing.md)
|
||||
|
||||
Агент обязан применять эти правила во всех решениях.
|
||||
|
||||
---
|
||||
|
||||
## Использование карты документации
|
||||
|
||||
Для поиска дополнительных сведений агент должен использовать:
|
||||
|
||||
* [MAP.md](./MAP.md)
|
||||
|
||||
MAP.md содержит ссылки на все прикладные и вспомогательные разделы.
|
||||
|
||||
Агент может:
|
||||
|
||||
* переходить к нужным разделам через MAP.md
|
||||
* уточнять детали реализации
|
||||
* искать примеры и частные случаи
|
||||
|
||||
---
|
||||
|
||||
## Запрещено
|
||||
|
||||
Агенту запрещено:
|
||||
|
||||
* начинать выполнение задачи без изучения архитектуры
|
||||
* игнорировать базовые правила
|
||||
* принимать решения, противоречащие архитектуре
|
||||
* придумывать собственные подходы, если они не описаны в документации
|
||||
|
||||
---
|
||||
|
||||
## Ожидаемое поведение агента
|
||||
|
||||
Перед выполнением задачи агент должен:
|
||||
|
||||
1. Изучить архитектуру
|
||||
2. Изучить базовые правила
|
||||
3. При необходимости открыть MAP.md и найти релевантные разделы
|
||||
4. Только после этого приступать к решению задачи
|
||||
|
||||
---
|
||||
|
||||
## Приоритеты
|
||||
|
||||
При принятии решений агент должен руководствоваться следующим приоритетом:
|
||||
|
||||
1. **Архитектура**
|
||||
2. Базовые правила
|
||||
3. Документация из MAP.md
|
||||
4. Задача пользователя
|
||||
|
||||
Если задача противоречит архитектуре — задача должна быть переосмыслена, а не выполнена напрямую.
|
||||
66
ai/nextjs-style-guide/MAP.md
Normal file
66
ai/nextjs-style-guide/MAP.md
Normal file
@@ -0,0 +1,66 @@
|
||||
# Карта документации
|
||||
|
||||
Список всех разделов архива с относительными ссылками. Точка входа
|
||||
— `DEVELOP.md` рядом с этим файлом.
|
||||
|
||||
## Подсказки
|
||||
|
||||
- [Подсказки](./workflow.md) — Короткие ответы на типовые вопросы и решения для спорных ситуаций.
|
||||
|
||||
## Базовые правила
|
||||
|
||||
- [Технологии и библиотеки](./basics/tech-stack.md) — Какие библиотеки и инструменты используются в проекте.
|
||||
- [Именование](./basics/naming.md) — Как называть переменные, файлы и прочие сущности в коде.
|
||||
- [Архитектура: Обзор](./basics/architecture/index.md) — Архитектурный подход проекта: что такое SLM и как он устроен.
|
||||
- [Архитектура: Слои](./basics/architecture/reference/layers.md) — Из каких слоёв состоит SLM-архитектура и как они связаны.
|
||||
- [Архитектура: Модули](./basics/architecture/reference/modules.md) — Что такое модуль в SLM-архитектуре и как он устроен.
|
||||
- [Архитектура: Сегменты](./basics/architecture/reference/segments.md) — Что такое сегмент модуля в SLM-архитектуре и какие они бывают.
|
||||
- [Стиль кода](./basics/code-style.md) — Как оформляется код в проекте.
|
||||
- [Документирование](./basics/documentation.md) — Что и как документировать в коде.
|
||||
- [Типизация](./basics/typing.md) — Как типизируется код в проекте.
|
||||
|
||||
## Создание проекта
|
||||
|
||||
- [Из шаблона](./creating-project/from-template.md) — Создание нового проекта на основе готового шаблона.
|
||||
- [По гайду вручную](./creating-project/manual.md) — Поэтапное создание нового проекта без использования шаблона.
|
||||
- [Чистый Next.js](./creating-project/nextjs.md) — Установка Next.js без лишнего шаблона — голый каркас под дальнейшую сборку.
|
||||
|
||||
## Работа с данными
|
||||
|
||||
- [Введение](./data/index.md) — Какие источники данных используются в проекте и как с ними работать.
|
||||
- [REST](./data/rest/index.md) — Как правильно работать с REST API в проекте.
|
||||
- [REST: Создание клиента](./data/rest/clients/index.md) — Как выбрать способ создания REST-клиента и где размещать его части.
|
||||
- [REST: Создание клиента: Автогенерация из OpenAPI](./data/rest/clients/auto.md) — Генерация REST-клиента из OpenAPI-спецификации через @gromlab/api-codegen.
|
||||
- [REST: Создание клиента: Ручное создание](./data/rest/clients/manual.md) — Создание REST-клиента вручную, когда OpenAPI нет или он неполный.
|
||||
- [REST: Создание клиента: GET-хуки REST-клиента](./data/rest/clients/hooks.md) — Прозрачные SWR-обёртки над GET-методами REST-клиента.
|
||||
- [REST: Использование: Стратегии получения данных](./data/rest/strategies/index.md) — Как выбрать способ получения REST-данных в зависимости от места и сценария.
|
||||
- [REST: Использование: Серверный await](./data/rest/strategies/server-await.md) — Получение REST-данных на сервере прямым await метода клиента.
|
||||
- [REST: Использование: Параллельные серверные запросы](./data/rest/strategies/parallel-server-requests.md) — Как запускать независимые REST-запросы на сервере без waterfall.
|
||||
- [REST: Использование: Передача промиса ниже](./data/rest/strategies/pass-promise-down.md) — Как запускать серверный REST-запрос выше и ожидать его во вложенном server-компоненте.
|
||||
- [REST: Использование: Начальные данные для клиентских хуков](./data/rest/strategies/client-hooks-initial-data.md) — Как передать серверный промис в SWR fallback, чтобы клиентские GET-хуки получили начальные данные.
|
||||
- [REST: Использование: Клиентский GET-хук](./data/rest/strategies/client-get-hook.md) — Получение REST-данных в Client Components через готовые GET-хуки REST-клиента.
|
||||
- [REST: Использование: Business-композиция](./data/rest/strategies/business-composition.md) — Когда REST-данные нужно объединить или интерпретировать в бизнес-модуле.
|
||||
- [Realtime](./data/realtime.md) — Работа с push-данными от сервера: подписки и события.
|
||||
|
||||
## Прикладные разделы
|
||||
|
||||
- [Структура проекта](./applied/project-structure.md) — Из чего состоит проект и где что лежит.
|
||||
- [Страницы](./applied/page-level.md) — Как работать со страницами и другими файлами роутинга Next.js App Router.
|
||||
- [Компонент](./applied/component.md) — Как создавать React-компоненты внутри SLM-модулей.
|
||||
- [Модуль](./applied/module.md) — Как создавать и организовывать SLM-модули в проекте.
|
||||
- [Стили: Настройка](./applied/styles/styles-setup.md) — Подготовка стилевой основы проекта: токены, медиа-запросы, глобальные стили.
|
||||
- [Стили: Использование](./applied/styles/styles-usage.md) — Как пишутся стили в проекте.
|
||||
- [SVG-спрайты](./applied/svg-sprites/svg-sprites-intro.md) — Что такое SVG-спрайты и какие проблемы они решают.
|
||||
- [SVG-спрайты: Настройка](./applied/svg-sprites/svg-sprites-setup.md) — Подключение SVG-спрайтов в новом проекте.
|
||||
- [SVG-спрайты: Использование](./applied/svg-sprites/svg-sprites-usage.md) — Как добавлять и использовать SVG-иконки в коде.
|
||||
- [Изображения](./applied/images.md) — Как подключать изображения через Next.js Image в проекте.
|
||||
- [Шрифты](./applied/fonts.md) — Как подключать шрифты через Next.js Font в проекте.
|
||||
- [Алиасы импортов](./applied/aliases.md) — Какие алиасы импортов есть в проекте и как ими пользоваться.
|
||||
- [Шаблоны генерации](./applied/templates/templates-intro.md) — Что такое шаблоны кодогенерации и какие проблемы они решают.
|
||||
- [Шаблоны генерации: Настройка](./applied/templates/templates-setup.md) — Первичная установка шаблонов кодогенерации в проект.
|
||||
- [Шаблоны генерации: Создание шаблонов](./applied/templates/templates-create.md) — Структура шаблонов, синтаксис переменных и примеры.
|
||||
- [Шаблоны генерации: Использование](./applied/templates/templates-usage.md) — Генерация файлов из шаблонов через VS Code плагин и CLI.
|
||||
- [Biome](./applied/biome.md) — Установка и настройка линтера-форматтера в новом проекте.
|
||||
- [PostCSS](./applied/postcss.md) — Установка и настройка CSS-процессора в новом проекте.
|
||||
- [VS Code](./applied/vscode.md) — Единые настройки редактора и расширений для команды.
|
||||
- [Локализация](./applied/localization.md) — Как организовать локализацию как infrastructure-модуль.
|
||||
2
ai/nextjs-style-guide/VERSION
Normal file
2
ai/nextjs-style-guide/VERSION
Normal file
@@ -0,0 +1,2 @@
|
||||
e835210
|
||||
2026-04-30T13:02:04.343Z
|
||||
77
ai/nextjs-style-guide/applied/aliases.md
Normal file
77
ai/nextjs-style-guide/applied/aliases.md
Normal file
@@ -0,0 +1,77 @@
|
||||
---
|
||||
title: Алиасы импортов
|
||||
description: Какие алиасы импортов есть в проекте и как ими пользоваться.
|
||||
keywords: [алиасы, aliases, paths, tsconfig, импорты, baseUrl, app, layouts, screens, widgets, business, infrastructure, ui, shared]
|
||||
---
|
||||
|
||||
# Алиасы импортов
|
||||
|
||||
Какие алиасы импортов есть в проекте и как ими пользоваться.
|
||||
|
||||
## Конфиг
|
||||
|
||||
`tsconfig.json` в корне проекта:
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"paths": {
|
||||
"app/*": ["./src/app/*"],
|
||||
"layouts/*": ["./src/layouts/*"],
|
||||
"screens/*": ["./src/screens/*"],
|
||||
"widgets/*": ["./src/widgets/*"],
|
||||
"business/*": ["./src/business/*"],
|
||||
"infrastructure/*": ["./src/infrastructure/*"],
|
||||
"ui/*": ["./src/ui/*"],
|
||||
"shared/*": ["./src/shared/*"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Восемь алиасов — ровно по числу слоёв. Других алиасов в проекте нет.
|
||||
|
||||
## Правила
|
||||
|
||||
- **Каждый импорт между модулями — через алиас слоя.** Относительные пути (`../../`) запрещены за пределами своего модуля.
|
||||
- **Внутри одного модуля** допустимы относительные импорты (`./model`, `./ui/button`) — это часть инкапсуляции модуля.
|
||||
- **Префикс `@/` не используется.** Имя слоя — само по себе адрес.
|
||||
- **Направление импортов** определяется архитектурой, не алиасами. Алиас разрешает импорт технически, но не отменяет правила слоёв (→ [Слои](../basics/architecture/reference/layers.md)).
|
||||
|
||||
**Хорошо**
|
||||
|
||||
```ts
|
||||
import { Button } from 'ui/button'
|
||||
import { useUser } from 'business/user'
|
||||
import { formatDate } from 'shared/utils/date'
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
|
||||
```ts
|
||||
// Относительный путь между модулями
|
||||
import { Button } from '../../../ui/button'
|
||||
|
||||
// Префикс @/, которого нет в paths
|
||||
import { Button } from '@/ui/button'
|
||||
|
||||
// Алиас на src — не предусмотрен
|
||||
import { Button } from 'src/ui/button'
|
||||
```
|
||||
|
||||
## Внутри модуля
|
||||
|
||||
Внутри своего модуля — относительные пути:
|
||||
|
||||
```ts
|
||||
// src/ui/button/button.tsx
|
||||
import styles from './button.module.css'
|
||||
import { Icon } from './icon'
|
||||
```
|
||||
|
||||
Не использовать алиас на самого себя:
|
||||
|
||||
```ts
|
||||
// Плохо — алиас вместо относительного пути внутри модуля
|
||||
import { Icon } from 'ui/button/icon'
|
||||
```
|
||||
81
ai/nextjs-style-guide/applied/biome.md
Normal file
81
ai/nextjs-style-guide/applied/biome.md
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
title: Biome
|
||||
description: Установка и настройка линтера-форматтера в новом проекте.
|
||||
keywords: [biome, линтер, форматтер, lint, format, biome.json, "@biomejs/biome", замена eslint, замена prettier]
|
||||
---
|
||||
|
||||
# Biome
|
||||
|
||||
Установка и настройка линтера-форматтера в новом проекте.
|
||||
|
||||
## Требования
|
||||
|
||||
- Node.js 18+.
|
||||
- Проект без установленного ESLint и Prettier (они конфликтуют с Biome).
|
||||
|
||||
## Установка
|
||||
|
||||
1. Установить пакет:
|
||||
|
||||
```bash
|
||||
npm install --save-dev --save-exact @biomejs/biome
|
||||
```
|
||||
|
||||
2. Инициализировать конфиг:
|
||||
|
||||
```bash
|
||||
npx @biomejs/biome init
|
||||
```
|
||||
|
||||
В корне появится `biome.json` с дефолтными настройками.
|
||||
|
||||
3. Привести `biome.json` к стандартному виду — добавить override для `*.css` (см. «Стандартный `biome.json`»). Делается сразу после `init`, до первого запуска `lint`/`check`.
|
||||
|
||||
4. Добавить скрипты в `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"lint": "biome lint .",
|
||||
"format": "biome format --write .",
|
||||
"check": "biome check --write ."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Скрипт | Что делает |
|
||||
|--------|-----------|
|
||||
| `lint` | Проверка правил без правок |
|
||||
| `format` | Автоформатирование всех файлов |
|
||||
| `check` | Lint + format + organize imports в один проход (основная команда) |
|
||||
|
||||
## Стандартный `biome.json`
|
||||
|
||||
Дефолтный `biome.json`, созданный `biome init`, кастомизируется ровно одним блоком — `overrides` для `*.css` с отключённым правилом `suspicious/noUnknownAtRules`. Этот override **обязателен по умолчанию во всех проектах**, независимо от того, подключены ли уже стили: проектный CSS-стек использует `@custom-media` и другие нестандартные at-правила, которые Biome не распознаёт; без override `npm run lint` падает.
|
||||
|
||||
Фрагмент, который добавляется в `biome.json`:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"overrides": [
|
||||
{
|
||||
"includes": ["**/*.css"],
|
||||
"linter": {
|
||||
"rules": {
|
||||
"suspicious": {
|
||||
"noUnknownAtRules": "off"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Если в `biome.json` уже есть массив `overrides` — добавить элемент в него; не дублировать массив.
|
||||
|
||||
Прочая настройка правил Biome — отдельная задача, не входит в стандартный канон.
|
||||
|
||||
## Интеграция с VS Code
|
||||
|
||||
Расширение `biomejs.biome` и автоформатирование при сохранении настраиваются в [VS Code](./vscode.md).
|
||||
201
ai/nextjs-style-guide/applied/component.md
Normal file
201
ai/nextjs-style-guide/applied/component.md
Normal file
@@ -0,0 +1,201 @@
|
||||
---
|
||||
title: Компонент
|
||||
description: Как создавать React-компоненты внутри SLM-модулей.
|
||||
---
|
||||
|
||||
# Компонент
|
||||
|
||||
Как создавать React-компоненты внутри SLM-модулей.
|
||||
|
||||
## Назначение
|
||||
|
||||
Компонент — минимальная UI-единица проекта. Это один `.tsx` файл без собственной папки, сегментов и публичного API.
|
||||
|
||||
Компонент может использовать стили, типы, хуки и другие ресурсы родительского модуля. Наличие связанных файлов в `styles/` или `types/` не превращает компонент в модуль.
|
||||
|
||||
## Компонент или модуль
|
||||
|
||||
Классификация определяется границей владения:
|
||||
|
||||
- `component` — один `.tsx` файл внутри модуля;
|
||||
- `module` — папка с `index.ts`, сегментами и собственной публичной границей.
|
||||
|
||||
```text
|
||||
user/
|
||||
├── ui/
|
||||
│ └── user-avatar.tsx # компонент
|
||||
├── styles/
|
||||
│ └── user-avatar.module.css # ресурс родительского модуля
|
||||
├── types/
|
||||
│ └── user-avatar.type.ts # ресурс родительского модуля
|
||||
└── user.tsx # корневой компонент модуля
|
||||
```
|
||||
|
||||
`user-avatar.tsx` остаётся компонентом, потому что у него нет собственной папки, `index.ts` и сегментов.
|
||||
|
||||
## Где размещать
|
||||
|
||||
Компонент размещается внутри модуля:
|
||||
|
||||
- В корне модуля, если это главная UI-сущность модуля.
|
||||
- В `ui/`, если это вспомогательный компонент модуля.
|
||||
|
||||
```text
|
||||
user/
|
||||
├── ui/
|
||||
│ └── user-avatar.tsx
|
||||
├── styles/
|
||||
│ ├── user.module.css
|
||||
│ └── user-avatar.module.css
|
||||
├── types/
|
||||
│ ├── user.type.ts
|
||||
│ └── user-avatar.type.ts
|
||||
├── user.tsx
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
`user.tsx` — корневой компонент модуля. `ui/user-avatar.tsx` — вспомогательный компонент этого же модуля.
|
||||
|
||||
## Что запрещено
|
||||
|
||||
- Заворачивать компонент в папку: `ui/header/header.tsx`.
|
||||
- Создавать для компонента отдельный `index.ts`.
|
||||
- Создавать собственные сегменты внутри папки компонента: `ui/header/styles/`, `ui/header/types/`, `ui/header/hooks/` и т.п.
|
||||
- Декларировать внутри `.tsx` сторы, сервисы, API-клиенты, мапперы или утилиты. Для этого есть сегменты родительского модуля.
|
||||
- Размещать бизнес-правила прямо в компоненте. Компонент может использовать готовые зависимости модуля, но не определяет их.
|
||||
- Размещать компонент в `parts/` напрямую. `parts/` содержит только модули.
|
||||
|
||||
**Плохо**
|
||||
|
||||
```text
|
||||
user/
|
||||
└── ui/
|
||||
└── user-avatar/
|
||||
├── styles/
|
||||
│ └── user-avatar.module.css
|
||||
├── user-avatar.tsx
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
**Хорошо**
|
||||
|
||||
```text
|
||||
user/
|
||||
├── ui/
|
||||
│ └── user-avatar.tsx
|
||||
├── styles/
|
||||
│ └── user-avatar.module.css
|
||||
└── types/
|
||||
└── user-avatar.type.ts
|
||||
```
|
||||
|
||||
## Стили и типы
|
||||
|
||||
Компонент использует ресурсы родительского модуля.
|
||||
|
||||
`styles/` и `types/` рядом с корневым компонентом — это сегменты модуля, а не собственные папки `.tsx` файла.
|
||||
|
||||
- CSS Module компонента лежит в `styles/` родительского модуля и называется по компоненту: `user-avatar.module.css`.
|
||||
- Если у компонента есть CSS Module, его корневой класс всегда называется `.root`.
|
||||
- Типы компонента лежат в `types/` родительского модуля и называются по компоненту: `user-avatar.type.ts`.
|
||||
- Локальный `type Props` внутри `.tsx` не используется. Типы пропсов всегда выносятся в `types/` родительского модуля.
|
||||
- Экспорт типа из `types/` не делает его публичным API. Публичным он становится только при реэкспорте из `index.ts` модуля.
|
||||
|
||||
Причина `.root`: в DevTools проще находить корневой DOM-узел компонента и отличать его от внутренних элементов.
|
||||
|
||||
## Реализация
|
||||
|
||||
- Компоненты объявляются через `const`.
|
||||
- `React.FC` не используется.
|
||||
- JSDoc-комментарий обязателен для компонента.
|
||||
- Пропсы деструктурируются в теле компонента.
|
||||
- `className` объединяется с `styles.root` через `cl()`.
|
||||
- Побочные эффекты и состояние выносятся в хуки модуля, если перестают быть тривиальными.
|
||||
- Компонент возвращает JSX и не содержит orchestration-код страницы или бизнес-домена.
|
||||
|
||||
`user/types/user-avatar.type.ts`
|
||||
|
||||
```ts
|
||||
import type { ImageProps } from 'next/image'
|
||||
|
||||
/**
|
||||
* Параметры UserAvatar.
|
||||
*/
|
||||
export type UserAvatarParams = {}
|
||||
|
||||
/** Пропсы базового изображения. */
|
||||
type RootAttrs = ImageProps
|
||||
|
||||
export type UserAvatarProps = RootAttrs & UserAvatarParams
|
||||
```
|
||||
|
||||
`user/ui/user-avatar.tsx`
|
||||
|
||||
```tsx
|
||||
import cl from 'clsx'
|
||||
import Image from 'next/image'
|
||||
import type { UserAvatarProps } from '../types/user-avatar.type'
|
||||
import styles from '../styles/user-avatar.module.css'
|
||||
|
||||
/**
|
||||
* Аватар пользователя.
|
||||
*
|
||||
* Используется для:
|
||||
* - отображения пользователя в карточке
|
||||
* - отображения пользователя в шапке профиля
|
||||
*/
|
||||
export const UserAvatar = (props: UserAvatarProps) => {
|
||||
const { className, ...imageProps } = props
|
||||
|
||||
return <Image {...imageProps} className={cl(styles.root, className)} />
|
||||
}
|
||||
```
|
||||
|
||||
`user/styles/user-avatar.module.css`
|
||||
|
||||
```css
|
||||
.root {
|
||||
display: block;
|
||||
border-radius: 50%;
|
||||
}
|
||||
```
|
||||
|
||||
## Когда нужен модуль
|
||||
|
||||
Решение о выделении модуля остаётся за разработчиком. Поднимать компонент в модуль стоит, если он становится самостоятельной областью:
|
||||
|
||||
- получает свои вложенные компоненты;
|
||||
- получает свои хуки, стор или сервисы;
|
||||
- получает внутренние мапперы или утилиты;
|
||||
- требует собственного публичного API;
|
||||
- начинает переиспользоваться вне родительского модуля;
|
||||
- становится отдельной зоной параллельной разработки.
|
||||
|
||||
Пример: страница — это screen-модуль, а самостоятельные секции страницы — вложенные модули в `parts/`.
|
||||
|
||||
```text
|
||||
screens/home/
|
||||
├── parts/
|
||||
│ ├── hero-section/
|
||||
│ │ ├── styles/
|
||||
│ │ │ └── hero-section.module.css
|
||||
│ │ ├── types/
|
||||
│ │ │ └── hero-section.type.ts
|
||||
│ │ ├── hero-section.tsx
|
||||
│ │ └── index.ts
|
||||
│ └── features-section/
|
||||
│ ├── styles/
|
||||
│ │ └── features-section.module.css
|
||||
│ ├── types/
|
||||
│ │ └── features-section.type.ts
|
||||
│ ├── features-section.tsx
|
||||
│ └── index.ts
|
||||
├── styles/
|
||||
│ └── home.module.css
|
||||
├── types/
|
||||
│ └── home.type.ts
|
||||
├── home.screen.tsx
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
`hero-section` и `features-section` — модули, потому что это самостоятельные части страницы со своей структурой и публичной точкой входа.
|
||||
128
ai/nextjs-style-guide/applied/fonts.md
Normal file
128
ai/nextjs-style-guide/applied/fonts.md
Normal file
@@ -0,0 +1,128 @@
|
||||
---
|
||||
title: Шрифты
|
||||
description: Как подключать шрифты через Next.js Font в проекте.
|
||||
---
|
||||
|
||||
# Шрифты
|
||||
|
||||
Как подключать шрифты через Next.js Font в проекте.
|
||||
|
||||
## Назначение
|
||||
|
||||
Шрифты подключаются через `next/font`. Это стандартный способ Next.js: шрифты загружаются без ручных `<link>`, `@font-face` и настройки preconnect.
|
||||
|
||||
Шрифт подключается в точке инициализации приложения, а в CSS используется через переменную.
|
||||
|
||||
## Google Fonts
|
||||
|
||||
```tsx
|
||||
// src/app/layout.tsx
|
||||
import type { ReactNode } from 'react'
|
||||
import { Inter } from 'next/font/google'
|
||||
import 'shared/styles/global.css'
|
||||
|
||||
const inter = Inter({
|
||||
subsets: ['latin', 'cyrillic'],
|
||||
variable: '--font-main',
|
||||
display: 'swap',
|
||||
})
|
||||
|
||||
type RootLayoutProps = {
|
||||
children: ReactNode
|
||||
}
|
||||
|
||||
export default function RootLayout({ children }: RootLayoutProps) {
|
||||
return (
|
||||
<html lang="ru" className={inter.variable}>
|
||||
<body>{children}</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```css
|
||||
/* src/shared/styles/global.css */
|
||||
body {
|
||||
font-family: var(--font-main), system-ui, sans-serif;
|
||||
}
|
||||
```
|
||||
|
||||
## Локальные шрифты
|
||||
|
||||
Каждый локальный шрифт размещается в отдельной папке внутри `src/shared/fonts/`. В этой же папке лежит `.font.ts`, где объявляется `localFont`.
|
||||
|
||||
```text
|
||||
src/shared/fonts/
|
||||
└── roboto/
|
||||
├── roboto.font.ts
|
||||
├── Roboto-Regular.woff2
|
||||
├── Roboto-Italic.woff2
|
||||
├── Roboto-Bold.woff2
|
||||
└── Roboto-BoldItalic.woff2
|
||||
```
|
||||
|
||||
```ts
|
||||
// src/shared/fonts/roboto/roboto.font.ts
|
||||
import localFont from 'next/font/local'
|
||||
|
||||
export const roboto = localFont({
|
||||
src: [
|
||||
{
|
||||
path: './Roboto-Regular.woff2',
|
||||
weight: '400',
|
||||
style: 'normal',
|
||||
},
|
||||
{
|
||||
path: './Roboto-Italic.woff2',
|
||||
weight: '400',
|
||||
style: 'italic',
|
||||
},
|
||||
{
|
||||
path: './Roboto-Bold.woff2',
|
||||
weight: '700',
|
||||
style: 'normal',
|
||||
},
|
||||
{
|
||||
path: './Roboto-BoldItalic.woff2',
|
||||
weight: '700',
|
||||
style: 'italic',
|
||||
},
|
||||
],
|
||||
variable: '--font-main',
|
||||
display: 'swap',
|
||||
})
|
||||
```
|
||||
|
||||
`app/` импортирует готовый объект шрифта и только подключает его к документу:
|
||||
|
||||
```tsx
|
||||
// src/app/layout.tsx
|
||||
import type { ReactNode } from 'react'
|
||||
import { roboto } from 'shared/fonts/roboto/roboto.font'
|
||||
import 'shared/styles/global.css'
|
||||
|
||||
type RootLayoutProps = {
|
||||
children: ReactNode
|
||||
}
|
||||
|
||||
export default function RootLayout({ children }: RootLayoutProps) {
|
||||
return (
|
||||
<html lang="ru" className={roboto.variable}>
|
||||
<body>{children}</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Путь в `localFont` указывается относительно `.font.ts`, поэтому файлы шрифта импортируются коротко: `./Roboto-Regular.woff2`.
|
||||
|
||||
Если шрифтов несколько, у каждого своя папка и свой `.font.ts`.
|
||||
|
||||
## Правила
|
||||
|
||||
- Использовать `next/font/google` или `next/font/local`.
|
||||
- Не подключать шрифты через ручные `<link>` и `@font-face` без необходимости.
|
||||
- Подключать шрифты один раз — в корневом layout через готовый объект шрифта.
|
||||
- Использовать CSS-переменные `variable`, а не жёстко прописывать семейство в каждом компоненте.
|
||||
- Локальные файлы шрифтов хранить в `src/shared/fonts/{font-name}/` рядом с `{font-name}.font.ts`.
|
||||
- Не объявлять `localFont` внутри `src/app/layout.tsx`; layout только импортирует готовый шрифт.
|
||||
95
ai/nextjs-style-guide/applied/images.md
Normal file
95
ai/nextjs-style-guide/applied/images.md
Normal file
@@ -0,0 +1,95 @@
|
||||
---
|
||||
title: Изображения
|
||||
description: Как подключать изображения через Next.js Image в проекте.
|
||||
---
|
||||
|
||||
# Изображения
|
||||
|
||||
Как подключать изображения через Next.js Image в проекте.
|
||||
|
||||
## Назначение
|
||||
|
||||
Изображения рендерятся через компонент `Image` из `next/image`. Это сохраняет единый API для размеров, `alt`, lazy-loading и `priority`, даже если оптимизация изображений отключена.
|
||||
|
||||
В проекте оптимизация Next.js Image отключается через `unoptimized`, чтобы сборка и рантайм не зависели от встроенного image optimizer.
|
||||
|
||||
## Настройка
|
||||
|
||||
Отключение оптимизации задаётся глобально в `next.config.ts`:
|
||||
|
||||
```ts
|
||||
import type { NextConfig } from 'next'
|
||||
|
||||
const nextConfig: NextConfig = {
|
||||
images: {
|
||||
unoptimized: true,
|
||||
},
|
||||
}
|
||||
|
||||
export default nextConfig
|
||||
```
|
||||
|
||||
После этого `unoptimized` не нужно повторять на каждом `Image`.
|
||||
|
||||
## Использование
|
||||
|
||||
Статические изображения, доступные по URL, размещаются в `public/`:
|
||||
|
||||
```text
|
||||
public/
|
||||
└── images/
|
||||
└── user-avatar.png
|
||||
```
|
||||
|
||||
```tsx
|
||||
import Image from 'next/image'
|
||||
|
||||
export const UserAvatar = () => {
|
||||
return (
|
||||
<Image
|
||||
src="/images/user-avatar.png"
|
||||
alt="Аватар пользователя"
|
||||
width={96}
|
||||
height={96}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Правила
|
||||
|
||||
- Использовать `Image` из `next/image`, не обычный `<img>`.
|
||||
- Для контентных изображений всегда писать осмысленный `alt`.
|
||||
- Для декоративных изображений использовать `alt=""`.
|
||||
- Указывать `width` и `height`, если изображение не использует `fill`.
|
||||
- При `fill` задавать `sizes` и контролировать размеры родителя стилями.
|
||||
- `priority` ставить только для изображений первого экрана.
|
||||
- SVG-иконки не оформлять как изображения — для них используется раздел [SVG-спрайты](./svg-sprites/svg-sprites-intro.md).
|
||||
|
||||
## Пример с `fill`
|
||||
|
||||
```tsx
|
||||
import Image from 'next/image'
|
||||
import styles from '../styles/article-card-cover.module.css'
|
||||
|
||||
export const ArticleCardCover = () => {
|
||||
return (
|
||||
<div className={styles.root}>
|
||||
<Image
|
||||
src="/images/article-cover.jpg"
|
||||
alt="Обложка статьи"
|
||||
fill
|
||||
sizes="(min-width: 768px) 33vw, 100vw"
|
||||
/>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```css
|
||||
.root {
|
||||
position: relative;
|
||||
aspect-ratio: 16 / 9;
|
||||
overflow: hidden;
|
||||
}
|
||||
```
|
||||
81
ai/nextjs-style-guide/applied/localization.md
Normal file
81
ai/nextjs-style-guide/applied/localization.md
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
title: Локализация
|
||||
description: Как организовать локализацию как infrastructure-модуль.
|
||||
---
|
||||
|
||||
# Локализация
|
||||
|
||||
Как организовать локализацию как infrastructure-модуль.
|
||||
|
||||
## Назначение
|
||||
|
||||
Локализация — инфраструктурная подсистема приложения. Она отвечает за текущую локаль, словари, форматирование переводов и API для компонентов.
|
||||
|
||||
Код локализации живёт в `src/infrastructure/i18n/`. Компоненты и модули не читают словари напрямую — они используют публичный API infrastructure-модуля.
|
||||
|
||||
## Структура
|
||||
|
||||
```text
|
||||
src/infrastructure/i18n/
|
||||
├── config/
|
||||
│ └── i18n.config.ts
|
||||
├── dictionaries/
|
||||
│ ├── ru.ts
|
||||
│ └── en.ts
|
||||
├── hooks/
|
||||
│ └── use-translation.hook.ts
|
||||
├── providers/
|
||||
│ └── i18n-provider.tsx
|
||||
├── types/
|
||||
│ └── i18n.type.ts
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
Набор сегментов может отличаться, но публичная точка входа остаётся одна — `infrastructure/i18n`.
|
||||
|
||||
## Подключение
|
||||
|
||||
`app/` только подключает готовый провайдер локализации. Реализация провайдера, словари и конфиг остаются в `infrastructure/i18n/`.
|
||||
|
||||
```tsx
|
||||
// src/app/layout.tsx
|
||||
import type { ReactNode } from 'react'
|
||||
import { I18nProvider } from 'infrastructure/i18n'
|
||||
|
||||
type RootLayoutProps = {
|
||||
children: ReactNode
|
||||
}
|
||||
|
||||
export default function RootLayout({ children }: RootLayoutProps) {
|
||||
return (
|
||||
<html lang="ru">
|
||||
<body>
|
||||
<I18nProvider locale="ru">{children}</I18nProvider>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Использование
|
||||
|
||||
Компоненты получают переводы через готовый API модуля локализации:
|
||||
|
||||
```tsx
|
||||
import { useTranslation } from 'infrastructure/i18n'
|
||||
|
||||
export const ProfileTitle = () => {
|
||||
const { t } = useTranslation()
|
||||
|
||||
return <h1>{t('profile.title')}</h1>
|
||||
}
|
||||
```
|
||||
|
||||
## Правила
|
||||
|
||||
- Локализация живёт в `infrastructure/i18n/`.
|
||||
- `app/` только подключает готовый provider и передаёт locale.
|
||||
- Словари не импортируются напрямую в компоненты, screens или business-модули.
|
||||
- Ключи переводов не собираются динамически из строк, если это ломает типизацию и поиск.
|
||||
- Тексты интерфейса не хардкодятся в переиспользуемых компонентах, если они должны переводиться.
|
||||
- Форматирование дат, чисел и валют должно проходить через API локализации или отдельные утилиты infrastructure-модуля.
|
||||
162
ai/nextjs-style-guide/applied/module.md
Normal file
162
ai/nextjs-style-guide/applied/module.md
Normal file
@@ -0,0 +1,162 @@
|
||||
---
|
||||
title: Модуль
|
||||
description: Как создавать и организовывать SLM-модули в проекте.
|
||||
---
|
||||
|
||||
# Модуль
|
||||
|
||||
Как создавать и организовывать SLM-модули в проекте.
|
||||
|
||||
## Назначение
|
||||
|
||||
Модуль — основной строительный блок SLM-архитектуры. Это папка с публичным API (`index.ts`) и опциональными сегментами: компонентами, стилями, типами, хуками, сторами, сервисами и вложенными модулями.
|
||||
|
||||
Если UI-сущность остаётся одним `.tsx` файлом и использует ресурсы родительского модуля — это [компонент](./component.md), а не модуль. Связанные файлы в `styles/` и `types/` родителя не создают новую модульную границу.
|
||||
|
||||
Архитектурное определение: [Модули SLM](../basics/architecture/reference/modules.md). Список сегментов: [Сегменты SLM](../basics/architecture/reference/segments.md).
|
||||
|
||||
## Когда нужен модуль
|
||||
|
||||
Создавайте модуль, если сущности нужны:
|
||||
|
||||
- публичный API;
|
||||
- хуки, сторы, сервисы, мапперы или утилиты;
|
||||
- вложенные части;
|
||||
- переиспользование вне родительского модуля;
|
||||
- самостоятельная ответственность на слое.
|
||||
|
||||
Если понадобилась папка вокруг компонента — это сигнал, что нужен модуль.
|
||||
|
||||
## Где размещать
|
||||
|
||||
Модуль размещается на самом низком уровне использования.
|
||||
|
||||
- Нужен только одному модулю — размещается в `parts/` родителя.
|
||||
- Нужен одной странице — размещается в `screens/{name}/parts/`.
|
||||
- Нужен одному layout — размещается в `layouts/{name}/parts/`.
|
||||
- Переиспользуется между страницами или layout — поднимается в `widgets/`.
|
||||
- Представляет бизнес-домен — размещается в `business/`.
|
||||
- Является UI-китом — размещается в `ui/`.
|
||||
|
||||
`app/` не содержит модулей. Это слой файлового роутинга и инициализации.
|
||||
|
||||
## Структура
|
||||
|
||||
Минимальный UI-модуль:
|
||||
|
||||
```text
|
||||
user/
|
||||
├── user.tsx
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
Модуль расширяется сегментами только при реальной потребности:
|
||||
|
||||
```text
|
||||
user/
|
||||
├── ui/
|
||||
│ └── user-avatar.tsx
|
||||
├── parts/
|
||||
│ └── user-posts/
|
||||
│ ├── user-posts.tsx
|
||||
│ └── index.ts
|
||||
├── styles/
|
||||
│ ├── user.module.css
|
||||
│ └── user-avatar.module.css
|
||||
├── types/
|
||||
│ ├── user.type.ts
|
||||
│ └── user-avatar.type.ts
|
||||
├── user.tsx
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
Корневой компонент опционален. Business- и infrastructure-модули могут состоять только из хуков, сервисов, типов и публичного API.
|
||||
|
||||
## `ui/` и `parts/`
|
||||
|
||||
`ui/` содержит только компоненты: отдельные `.tsx` файлы без собственных сегментов.
|
||||
|
||||
`parts/` содержит только модули: каждая запись внутри `parts/` — папка с собственным `index.ts`. Отдельные `.tsx`, стили, хуки или произвольные файлы в `parts/` не кладутся.
|
||||
|
||||
```text
|
||||
user/
|
||||
├── ui/
|
||||
│ └── user-avatar.tsx # компонент
|
||||
└── parts/
|
||||
└── user-posts/ # модуль
|
||||
├── styles/
|
||||
│ └── user-posts.module.css
|
||||
├── user-posts.tsx
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
Если компоненту в `ui/` понадобились стили или типы, они добавляются в `styles/` и `types/` родительского модуля. Если компоненту нужны собственные хуки, вложенные части или публичная граница — он переносится в `parts/` как модуль.
|
||||
|
||||
## Публичный API
|
||||
|
||||
`index.ts` — единственная точка входа в модуль. Внешние импорты внутренних файлов запрещены.
|
||||
|
||||
```ts
|
||||
// user/index.ts
|
||||
export { User } from './user'
|
||||
export type { UserProps } from './types/user.type'
|
||||
```
|
||||
|
||||
```ts
|
||||
// Плохо: импорт в обход публичного API.
|
||||
import { UserPosts } from 'screens/user/parts/user-posts/user-posts'
|
||||
|
||||
// Хорошо: импорт через публичный API родительского модуля.
|
||||
import { User } from 'screens/user'
|
||||
```
|
||||
|
||||
Вложенный модуль имеет свой `index.ts`, но наружу родителя экспортируется только при необходимости.
|
||||
|
||||
## Именование
|
||||
|
||||
Базовые правила описаны в разделе [Именование](../basics/naming.md).
|
||||
|
||||
- Папка модуля — `kebab-case`: `user-posts/`.
|
||||
- Файл корневого компонента повторяет имя папки: `user-posts/user-posts.tsx`.
|
||||
- Корневые модули слоёв наследуют роль слоя в имени файла: `screens/profile/profile.screen.tsx`, `layouts/main/main.layout.tsx`.
|
||||
- Корневой компонент именуется в `PascalCase`: `UserPosts`.
|
||||
- Если имя без контекста слишком общее, добавляется префикс родителя или роль слоя: `ProfileUserPosts`, `ProfileScreen`, `MainLayout`.
|
||||
|
||||
## Примеры
|
||||
|
||||
### Screen-модуль
|
||||
|
||||
```text
|
||||
screens/profile/
|
||||
├── ui/
|
||||
│ └── profile-heading.tsx
|
||||
├── parts/
|
||||
│ └── activity-feed/
|
||||
│ ├── styles/
|
||||
│ │ └── activity-feed.module.css
|
||||
│ ├── activity-feed.tsx
|
||||
│ └── index.ts
|
||||
├── styles/
|
||||
│ ├── profile.module.css
|
||||
│ └── profile-heading.module.css
|
||||
├── types/
|
||||
│ ├── profile.type.ts
|
||||
│ └── profile-heading.type.ts
|
||||
├── profile.screen.tsx
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
### Business-модуль без корневого компонента
|
||||
|
||||
```text
|
||||
business/auth/
|
||||
├── hooks/
|
||||
│ └── use-auth.hook.ts
|
||||
├── services/
|
||||
│ └── auth.service.ts
|
||||
├── stores/
|
||||
│ └── auth.store.ts
|
||||
├── types/
|
||||
│ └── auth.type.ts
|
||||
└── index.ts
|
||||
```
|
||||
186
ai/nextjs-style-guide/applied/page-level.md
Normal file
186
ai/nextjs-style-guide/applied/page-level.md
Normal file
@@ -0,0 +1,186 @@
|
||||
---
|
||||
title: Файлы роутинга
|
||||
description: Как работать со страницами и другими файлами роутинга Next.js App Router.
|
||||
---
|
||||
|
||||
# Файлы роутинга
|
||||
|
||||
Как работать со страницами и другими файлами роутинга Next.js App Router.
|
||||
|
||||
## Назначение
|
||||
|
||||
`src/app/**` — точка входа приложения и слой файлового роутинга Next.js.
|
||||
|
||||
Файлы роутинга не реализуют интерфейс. Они описывают маршрут: читают параметры, получают данные первого рендера, подготавливают кеш или состояние и передают результат в screen.
|
||||
|
||||
Границы слоя описаны в [Архитектура → Слои → App](../basics/architecture/reference/layers.md#слой-app).
|
||||
|
||||
## Граница ответственности
|
||||
|
||||
| Область | Где живёт |
|
||||
|---|---|
|
||||
| Файлы маршрутов (`page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `not-found.tsx`) | `src/app/**` |
|
||||
| Параметры маршрута, `metadata`, `redirect()`, `notFound()` | `src/app/**` |
|
||||
| Серверные запросы для первого рендера | `src/app/**`, через готовые клиенты и сервисы нижних слоёв |
|
||||
| Прогрев SWR-кеша, начальное состояние, подключение провайдеров | `src/app/**`, только через готовые обёртки из нижних слоёв |
|
||||
| UI страницы | `screens/` |
|
||||
| Каркас страницы: header, footer, sidebar | `layouts/` |
|
||||
| Провайдеры, сторы, хуки, API-клиенты, сервисы | нижние слои (`screens/`, `business/`, `infrastructure/`, `shared/`) |
|
||||
| CSS Modules и стили компонентов | рядом с компонентами, не в `src/app/**` |
|
||||
|
||||
## Что можно делать в `page.tsx`
|
||||
|
||||
- Экспортировать `metadata` или `generateMetadata`.
|
||||
- Читать `params` и `searchParams`.
|
||||
- Нормализовать и валидировать параметры маршрута.
|
||||
- Делать серверные запросы для первого рендера через готовые клиенты или сервисы.
|
||||
- Вызывать `redirect()` и `notFound()`.
|
||||
- Готовить начальные данные для screen.
|
||||
- Готовить SWR `fallback` и передавать его в готовый провайдер.
|
||||
- Подключать готовый провайдер стора страницы и передавать начальное состояние.
|
||||
- Рендерить screen или композицию из готовых обёрток и screen.
|
||||
|
||||
## Что запрещено
|
||||
|
||||
- Писать UI-разметку страницы прямо в файле роутинга.
|
||||
- Создавать локальные компоненты внутри `src/app/**`.
|
||||
- Добавлять CSS Modules, стили компонентов, `components/`, `styles/`, `hooks/`, `stores/`, `services/` внутри `src/app/**`.
|
||||
- Реализовывать провайдеры, сторы, хуки, API-клиенты или сервисы в файлах роутинга.
|
||||
- Размещать бизнес-логику, мапперы и правила предметной области в файлах роутинга.
|
||||
- Вызывать `useSWR` и доменные клиентские хуки в файлах роутинга.
|
||||
|
||||
## Страницы
|
||||
|
||||
Страница объявляется через `export default function`. Для серверных запросов используется `async function`.
|
||||
|
||||
```tsx
|
||||
import type { Metadata } from 'next'
|
||||
import { ProfileScreen } from 'screens/profile'
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: 'Профиль',
|
||||
description: 'Страница профиля пользователя',
|
||||
}
|
||||
|
||||
type ProfilePageProps = {
|
||||
params: Promise<{ id: string }>
|
||||
}
|
||||
|
||||
export default async function ProfilePage({ params }: ProfilePageProps) {
|
||||
const { id } = await params
|
||||
|
||||
return <ProfileScreen id={id} />
|
||||
}
|
||||
```
|
||||
|
||||
## Данные первого рендера
|
||||
|
||||
Если данные нужны до первого рендера, `page.tsx` получает их на сервере и передаёт в screen. Сам запрос выполняется через готовый клиент или сервис нижнего слоя.
|
||||
|
||||
```tsx
|
||||
import { notFound } from 'next/navigation'
|
||||
import { userApi } from 'infrastructure/backend-api'
|
||||
import { UserScreen } from 'screens/user'
|
||||
|
||||
type UserPageProps = {
|
||||
params: Promise<{ id: string }>
|
||||
}
|
||||
|
||||
export default async function UserPage({ params }: UserPageProps) {
|
||||
const { id } = await params
|
||||
const user = await userApi.users.get(id)
|
||||
|
||||
if (!user) {
|
||||
notFound()
|
||||
}
|
||||
|
||||
return <UserScreen user={user} />
|
||||
}
|
||||
```
|
||||
|
||||
Если данные нужны нескольким клиентским SWR-хукам, файл роутинга может обернуть дерево в `SWRConfig` и передать `fallback`. Запросы стартуют на сервере, а клиентские хуки получают данные из кеша.
|
||||
|
||||
Ключи `fallback` должны совпадать с ключами внутри GET-хуков REST-клиента. Для array-key используется `unstable_serialize`.
|
||||
|
||||
```tsx
|
||||
import type { ReactNode } from 'react'
|
||||
import { SWRConfig, unstable_serialize } from 'swr'
|
||||
import {
|
||||
backendApi,
|
||||
getCurrentUserKey,
|
||||
getPostListKey,
|
||||
} from 'infrastructure/backend-api'
|
||||
|
||||
type FeedLayoutProps = {
|
||||
children: ReactNode
|
||||
}
|
||||
|
||||
export default async function FeedLayout({ children }: FeedLayoutProps) {
|
||||
const userPromise = backendApi.user.getCurrent()
|
||||
const postsPromise = backendApi.posts.list()
|
||||
|
||||
return (
|
||||
<SWRConfig
|
||||
value={{
|
||||
fallback: {
|
||||
[unstable_serialize(getCurrentUserKey())]: userPromise,
|
||||
[unstable_serialize(getPostListKey())]: postsPromise,
|
||||
},
|
||||
}}
|
||||
>
|
||||
{children}
|
||||
</SWRConfig>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Подробнее о стратегиях запросов и начальных данных для клиентских хуков: [REST → Стратегии получения данных](../data/rest/strategies/index.md), [REST → Начальные данные для клиентских хуков](../data/rest/strategies/client-hooks-initial-data.md).
|
||||
|
||||
## Инициализация состояния
|
||||
|
||||
Файл роутинга может подключить готовый провайдер стора страницы, если состояние зависит от маршрута или данных первого рендера. Реализация стора и провайдера не размещается в `src/app/**`.
|
||||
|
||||
```tsx
|
||||
import { ProfileScreen, ProfileStoreProvider } from 'screens/profile'
|
||||
|
||||
type ProfilePageProps = {
|
||||
params: Promise<{ id: string }>
|
||||
}
|
||||
|
||||
export default async function ProfilePage({ params }: ProfilePageProps) {
|
||||
const { id } = await params
|
||||
|
||||
return (
|
||||
<ProfileStoreProvider initialState={{ userId: id }}>
|
||||
<ProfileScreen />
|
||||
</ProfileStoreProvider>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Layout
|
||||
|
||||
`layout.tsx` подключает готовую инициализацию приложения: глобальные стили, провайдеры и верхнеуровневые обёртки из нижних слоёв.
|
||||
|
||||
Вёрстка layout-каркаса выносится в слой `layouts/`. Реализация провайдеров, стилей и UI не размещается в `app/`.
|
||||
|
||||
## Error и Not Found
|
||||
|
||||
`error.tsx` и `not-found.tsx` делегируют разметку готовым screen или widget. В файле роутинга остаётся только адаптация API Next.js к пропсам нижнего слоя.
|
||||
|
||||
```tsx
|
||||
'use client'
|
||||
|
||||
import { ErrorScreen } from 'screens/error'
|
||||
|
||||
type ErrorPageProps = {
|
||||
error: Error & { digest?: string }
|
||||
reset: () => void
|
||||
}
|
||||
|
||||
const ErrorPage = ({ error, reset }: ErrorPageProps) => {
|
||||
return <ErrorScreen error={error} reset={reset} />
|
||||
}
|
||||
|
||||
export default ErrorPage
|
||||
```
|
||||
70
ai/nextjs-style-guide/applied/postcss.md
Normal file
70
ai/nextjs-style-guide/applied/postcss.md
Normal file
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: PostCSS
|
||||
description: Установка и настройка CSS-процессора в новом проекте.
|
||||
keywords: [postcss, postcss.config.mjs, postcss-custom-media, postcss-nesting, autoprefixer, postcss-global-data, csstools, "@custom-media", "@nest", css-процессор]
|
||||
---
|
||||
|
||||
# PostCSS
|
||||
|
||||
Установка и настройка CSS-процессора в новом проекте.
|
||||
|
||||
## Зачем PostCSS
|
||||
|
||||
Подключаем ради двух вещей:
|
||||
|
||||
- **Вложенность** — `&:hover`, `&::before`, `&._active` и `@media` внутри селектора. Без процессора нативный CSS не покрывает всех нужных кейсов вложенности.
|
||||
- **`@custom-media`** — единые breakpoints проекта (`@media (--md)`) вместо магических `min-width`. Определяются в одном месте, переиспользуются везде.
|
||||
|
||||
Autoprefixer и `@csstools/postcss-global-data` идут довеском под эти две задачи.
|
||||
|
||||
## Требования
|
||||
|
||||
- Next.js 14+ (App Router).
|
||||
- Node.js 18+.
|
||||
|
||||
CSS Modules поддерживаются Next.js из коробки — отдельной установки не требуют.
|
||||
|
||||
## Установка
|
||||
|
||||
1. Установить PostCSS-плагины как devDependencies:
|
||||
|
||||
```bash
|
||||
npm install -D postcss-custom-media postcss-nesting autoprefixer @csstools/postcss-global-data
|
||||
```
|
||||
|
||||
2. Создать `postcss.config.mjs` в корне проекта (см. «Конфиг»).
|
||||
|
||||
## Конфиг
|
||||
|
||||
Файл `postcss.config.mjs` в корне проекта.
|
||||
|
||||
```js
|
||||
// postcss.config.mjs
|
||||
export default {
|
||||
plugins: {
|
||||
'@csstools/postcss-global-data': {
|
||||
files: ['src/shared/styles/media.css'],
|
||||
},
|
||||
'postcss-custom-media': {},
|
||||
'postcss-nesting': {},
|
||||
autoprefixer: {},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Разбор плагинов
|
||||
|
||||
| Плагин | Назначение |
|
||||
|--------|------------|
|
||||
| `@csstools/postcss-global-data` | Подгружает определения `@custom-media` из `src/shared/styles/media.css` перед обработкой каждого CSS-модуля. Семантика — «глобальный файл определений, который не импортируется в исходники» |
|
||||
| `postcss-custom-media` | Поддержка `@custom-media --md (...)` и использования `@media (--md) {}`. Определения берутся из файла, который подгрузил `postcss-global-data` |
|
||||
| `postcss-nesting` | Нативная CSS-вложенность: `&:hover`, `&::before`, `&._active` |
|
||||
| `autoprefixer` | Добавление вендорных префиксов по browserslist |
|
||||
|
||||
### Почему внешний файл с `@custom-media`, а не `@import`
|
||||
|
||||
`@custom-media` — глобальные определения, одинаковые для всего проекта. Держим их в `src/shared/styles/media.css`. `@csstools/postcss-global-data` подгружает этот файл перед каждым модулем, а `postcss-custom-media` заменяет `@media (--md)` на конкретные `@media (min-width: ...)` на этапе сборки. Сами определения в бандл не попадают.
|
||||
|
||||
Опция `importFrom` у `postcss-custom-media` удалена в v10+; её роль теперь выполняет `@csstools/postcss-global-data`.
|
||||
|
||||
Импортировать `media.css` в файлы компонентов **не нужно** и запрещено правилами (см. [Использование стилей](./styles/styles-usage.md), раздел «Импорт стилей»).
|
||||
101
ai/nextjs-style-guide/applied/project-structure.md
Normal file
101
ai/nextjs-style-guide/applied/project-structure.md
Normal file
@@ -0,0 +1,101 @@
|
||||
---
|
||||
title: Структура проекта
|
||||
description: Из чего состоит проект и где что лежит.
|
||||
---
|
||||
|
||||
# Структура проекта
|
||||
|
||||
Из чего состоит проект и где что лежит.
|
||||
|
||||
## Корень репозитория
|
||||
|
||||
```text
|
||||
project-root/
|
||||
├── .templates/ # Шаблоны для генерации модулей
|
||||
├── .vscode/ # Настройки и рекомендуемые расширения VS Code
|
||||
├── public/ # Статика, доступная по прямому URL
|
||||
├── src/ # Исходный код приложения
|
||||
├── .env.example # Переменные окружения проекта (шаблон)
|
||||
├── .env # Переменные окружения проекта (не коммитить)
|
||||
├── .gitignore
|
||||
├── AGENTS.md # Инструкции для AI-агентов
|
||||
├── biome.json # Линтер и форматтер (вместо ESLint + Prettier)
|
||||
├── next.config.ts # Конфигурация Next.js
|
||||
├── package.json # Зависимости и скрипты
|
||||
├── postcss.config.mjs # Конфигурация PostCSS
|
||||
└── tsconfig.json # Конфигурация TypeScript
|
||||
```
|
||||
|
||||
## Папка `public/`
|
||||
|
||||
Хранит статические файлы, которые отдаются по прямому URL без обработки сборщиком:
|
||||
|
||||
```text
|
||||
public/
|
||||
└── og-image.png
|
||||
```
|
||||
|
||||
Компоненты, стили и другой исходный код здесь не размещаются.
|
||||
|
||||
## Папка `src/`
|
||||
|
||||
```text
|
||||
src/
|
||||
├── app/ # Роутинг Next.js и точка входа приложения
|
||||
├── layouts/ # Каркасы страниц (header, footer, sidebar)
|
||||
├── screens/ # Контент конкретной страницы
|
||||
├── widgets/ # Составные блоки интерфейса, не привязанные к домену
|
||||
├── business/ # Бизнес-домены (auth, catalog, orders)
|
||||
├── infrastructure/ # Техсервисы (theme, i18n, API-адаптеры)
|
||||
├── ui/ # UI-кит без бизнес-логики
|
||||
└── shared/ # Общие ресурсы (утилиты, типы, стили)
|
||||
```
|
||||
|
||||
Принципы организации слоёв описаны в разделе [Архитектура](../basics/architecture/).
|
||||
|
||||
### Папка `app/`
|
||||
|
||||
Точка входа приложения и файловый роутинг Next.js (`layout.tsx`, `page.tsx`, route-сегменты).
|
||||
`app/` подключает готовую инициализацию из нижних слоёв, но не реализует провайдеры, стили, UI-компоненты, хуки, сторы или сервисы.
|
||||
|
||||
Подробнее о границах слоя: [Архитектура → Слои → App](../basics/architecture/reference/layers.md#слой-app).
|
||||
|
||||
```text
|
||||
src/app/
|
||||
├── layout.tsx # Корневой layout
|
||||
└── page.tsx # Главная страница
|
||||
```
|
||||
|
||||
## Папка `.templates/`
|
||||
|
||||
Содержит шаблоны для генерации кода. Каждый подкаталог — шаблон отдельного типа модуля:
|
||||
|
||||
```text
|
||||
.templates/
|
||||
├── component/ # Шаблон компонента
|
||||
├── screen/ # Шаблон экрана
|
||||
├── layout/ # Шаблон layout
|
||||
├── widget/ # Шаблон виджета
|
||||
├── module/ # Шаблон бизнес-модуля
|
||||
└── store/ # Шаблон стора
|
||||
```
|
||||
|
||||
Подробнее о генерации описано в разделе [Шаблоны генерации](./templates/templates-intro.md).
|
||||
|
||||
## Конфигурационные файлы
|
||||
|
||||
| Файл | Назначение |
|
||||
|---|---|
|
||||
| `next.config.ts` | Настройки Next.js: редиректы, переменные окружения, webpack |
|
||||
| `tsconfig.json` | Настройки TypeScript: пути, строгость, таргет |
|
||||
| `biome.json` | Правила линтера и форматтера Biome |
|
||||
| `postcss.config.mjs` | Подключение PostCSS-плагинов (CSS Modules, custom media) |
|
||||
| `package.json` | Зависимости, версии, npm-скрипты |
|
||||
| `AGENTS.md` | Инструкции для AI-агентов, работающих в проекте |
|
||||
|
||||
## Переменные окружения
|
||||
|
||||
- `.env` — переменные окружения проекта, запрещено коммитить
|
||||
- `.env.example` — шаблон, коммитится в репозиторий
|
||||
|
||||
Переменные с префиксом `NEXT_PUBLIC_` доступны в клиентском коде. Остальные доступны только на сервере.
|
||||
176
ai/nextjs-style-guide/applied/styles/styles-setup.md
Normal file
176
ai/nextjs-style-guide/applied/styles/styles-setup.md
Normal file
@@ -0,0 +1,176 @@
|
||||
---
|
||||
title: Настройка стилей
|
||||
description: "Подготовка стилевой основы проекта: токены, медиа-запросы, глобальные стили."
|
||||
keywords: [variables.css, media.css, global.css, shared/styles, токены, переменные, custom-media, breakpoints, подключение стилей, базовые стили, инициализация]
|
||||
---
|
||||
|
||||
# Настройка стилей
|
||||
|
||||
Подготовка стилевой основы проекта: токены, медиа-запросы, глобальные стили.
|
||||
|
||||
## Требования
|
||||
|
||||
- Установлен PostCSS или любой другой pre/post-процессор с поддержкой `@custom-media`.
|
||||
|
||||
## Файлы
|
||||
|
||||
Состав глобальных стилей — три файла:
|
||||
|
||||
| Файл | Роль |
|
||||
|------|------|
|
||||
| `variables.css` | Токены проекта (цвета, отступы, радиусы) |
|
||||
| `media.css` | Custom media queries (брейкпоинты по ширине и высоте) |
|
||||
| `global.css` | Точка сборки глобальных стилей: через `@import` тянет все остальные глобалы, импортируется в приложение один раз |
|
||||
|
||||
Правила подключения:
|
||||
|
||||
- В приложение импортируется **только** `global.css`.
|
||||
- `variables.css` и будущие глобальные файлы (резеты, темы, типографика) подключаются в `global.css` через `@import`.
|
||||
- `media.css` **не импортируется** — ни в `global.css`, ни в компоненты, ни в точку инициализации. Его читает CSS-процессор на этапе сборки (см. [PostCSS](../postcss.md)).
|
||||
|
||||
## Корневой `font-size`
|
||||
|
||||
Базовая единица `rem` в проекте привязана к **16px**: корневой `font-size` не переопределяется. `html { font-size: ... }` писать запрещено — пользовательская настройка размера шрифта в браузере должна работать (a11y). Все `rem`-значения в `media.css` и других стилях трактуются как `1rem = 16px по умолчанию`.
|
||||
|
||||
Reset браузерных дефолтов (`box-sizing`, сброс `margin`, типографика) каноном не задаётся — каждый проект решает сам. Если заводится — подключается через `global.css`.
|
||||
|
||||
## Установка
|
||||
|
||||
### 1. Создать файлы
|
||||
|
||||
```bash
|
||||
mkdir -p src/shared/styles
|
||||
touch src/shared/styles/variables.css src/shared/styles/media.css src/shared/styles/global.css
|
||||
```
|
||||
|
||||
### 2. Заполнить `media.css`
|
||||
|
||||
Файл `src/shared/styles/media.css`. Стандартный набор брейкпоинтов проекта; редактировать только при согласованном изменении шкалы.
|
||||
|
||||
Единица — `rem` (реагирует на корневой `font-size`). Перевод исходит из дефолтного `html { font-size: 16px }`, т.е. `1rem = 16px`.
|
||||
|
||||
```css
|
||||
/* src/shared/styles/media.css */
|
||||
|
||||
/* Ширина — Mobile First (min-width), кроме --xs (max-width) */
|
||||
@custom-media --xs (max-width: 35.9375rem); /* 575px — до sm */
|
||||
@custom-media --sm (min-width: 36rem); /* 576px — телефон альбом / малый планшет */
|
||||
@custom-media --md (min-width: 48rem); /* 768px — планшет */
|
||||
@custom-media --lg (min-width: 62rem); /* 992px — малый десктоп */
|
||||
@custom-media --xl (min-width: 75rem); /* 1200px — десктоп */
|
||||
@custom-media --2xl (min-width: 88rem); /* 1408px — широкий десктоп */
|
||||
@custom-media --3xl (min-width: 120rem); /* 1920px — full HD+ */
|
||||
|
||||
/* Высота — min-height */
|
||||
@custom-media --h-xs (min-height: 41.6875rem); /* 667px — iPhone SE портрет */
|
||||
@custom-media --h-sm (min-height: 43.875rem); /* 702px */
|
||||
@custom-media --h-md (min-height: 50.625rem); /* 810px — iPad портрет */
|
||||
@custom-media --h-lg (min-height: 56.25rem); /* 900px */
|
||||
@custom-media --h-xl (min-height: 62.5rem); /* 1000px */
|
||||
@custom-media --h-2xl (min-height: 68.75rem); /* 1100px */
|
||||
@custom-media --h-3xl (min-height: 75rem); /* 1200px */
|
||||
```
|
||||
|
||||
Правила:
|
||||
|
||||
- только `@custom-media` на верхнем уровне;
|
||||
- имена короткие, по шкале (`--xs` … `--3xl`); высотные — с префиксом `--h-`;
|
||||
- единица — `rem`, не `em`/`px`; пиксельное значение указывается комментарием;
|
||||
- значения ширины — `min-width` (Mobile First), исключение `--xs` — `max-width` (блок «строго меньше `--sm`»);
|
||||
- значения высоты — `min-height`.
|
||||
|
||||
### 3. Заполнить `variables.css`
|
||||
|
||||
Файл `src/shared/styles/variables.css`. Набор токенов под проект расширяется по мере роста дизайн-системы.
|
||||
|
||||
```css
|
||||
/* src/shared/styles/variables.css */
|
||||
:root {
|
||||
/* Цвета */
|
||||
--color-primary: #3b82f6;
|
||||
--color-bg: #ffffff;
|
||||
--color-bg-hover: #f5f5f5;
|
||||
--color-text: #1a1a1a;
|
||||
|
||||
/* Отступы */
|
||||
--space-1: 4px;
|
||||
--space-2: 8px;
|
||||
--space-3: 12px;
|
||||
--space-4: 16px;
|
||||
|
||||
/* Скругления */
|
||||
--radius-1: 4px;
|
||||
--radius-2: 8px;
|
||||
}
|
||||
```
|
||||
|
||||
Правила:
|
||||
|
||||
- все токены определяются в `:root` — без вложенных селекторов;
|
||||
- именование — `kebab-case` по ролям: `--color-*`, `--space-*`, `--radius-*`;
|
||||
- `px` — основная единица для пространственных токенов;
|
||||
- темы накладываются поверх через `[data-theme="..."] { ... }` — в отдельном файле темы или здесь же.
|
||||
|
||||
`variables.css` напрямую в приложение не импортируется — только через `global.css`.
|
||||
|
||||
### 4. Заполнить `global.css`
|
||||
|
||||
Файл `src/shared/styles/global.css`. Единственный глобальный файл, импортируемый в точку инициализации приложения. Внутри — `@import` остальных глобалов относительным путём.
|
||||
|
||||
```css
|
||||
/* src/shared/styles/global.css */
|
||||
@import './variables.css';
|
||||
|
||||
/* Сюда же подключаются будущие глобалы через @import:
|
||||
* @import './reset.css';
|
||||
* @import './typography.css';
|
||||
* @import './themes.css';
|
||||
* media.css НЕ импортируется — он работает через PostCSS.
|
||||
*/
|
||||
```
|
||||
|
||||
Правила:
|
||||
|
||||
- пути в `@import` — относительные (`./variables.css`), не через алиасы; нативный CSS `@import` не понимает tsconfig-paths;
|
||||
- `media.css` в `global.css` **не импортируется**;
|
||||
- собственные глобальные правила (`html { ... }`, `body { ... }`) писать **не здесь**, а в отдельных файлах рядом (`reset.css`, `typography.css`) и подключать через `@import`. `global.css` — только точка сборки;
|
||||
- порядок `@import` определяет порядок каскада: токены первыми, дальше резеты / темы / типографика.
|
||||
|
||||
### 5. Подключить `global.css` в layout
|
||||
|
||||
Импорт делается **один раз** — в корневом layout приложения:
|
||||
|
||||
```tsx
|
||||
// src/app/layout.tsx
|
||||
import 'shared/styles/global.css'
|
||||
|
||||
import type { Metadata } from 'next'
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: 'App',
|
||||
description: '',
|
||||
}
|
||||
|
||||
export default function RootLayout({ children }: { children: React.ReactNode }) {
|
||||
return (
|
||||
<html lang="ru">
|
||||
<body>{children}</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
`variables.css` и `media.css` в layout **не импортируются напрямую** — только через `global.css` (variables) или через PostCSS на сборке (media).
|
||||
|
||||
## Проверка установки
|
||||
|
||||
- В `src/shared/styles/` присутствуют три файла: `variables.css`, `media.css`, `global.css`. В `src/app/` папки `styles/` нет.
|
||||
- В `src/app/layout.tsx` есть `import 'shared/styles/global.css'`. Импортов `variables.css` и `media.css` там нет.
|
||||
- В проекте **не появились** PostCSS-пакеты и `postcss.config.*` — этот раздел их не ставит.
|
||||
- `npm run build` завершается успешно.
|
||||
|
||||
## Дальше
|
||||
|
||||
- [PostCSS](../postcss.md) — подключить процессор, чтобы заработали `@media (--md)` и вложенность.
|
||||
- [Использование стилей](./styles-usage.md) — правила написания CSS в компонентах.
|
||||
- [SVG-спрайты](../svg-sprites/svg-sprites-setup.md) — стили иконок отдельно от глобальных.
|
||||
271
ai/nextjs-style-guide/applied/styles/styles-usage.md
Normal file
271
ai/nextjs-style-guide/applied/styles/styles-usage.md
Normal file
@@ -0,0 +1,271 @@
|
||||
---
|
||||
title: Использование стилей
|
||||
description: Как пишутся стили в проекте.
|
||||
---
|
||||
|
||||
# Использование стилей
|
||||
|
||||
Как пишутся стили в проекте.
|
||||
|
||||
## Общие правила
|
||||
|
||||
- Только **PostCSS** и **CSS Modules** для кастомной стилизации.
|
||||
- Подход **Mobile First** — стили пишутся от мобильных к десктопу.
|
||||
- Именование классов — `camelCase` (`.root`, `.buttonNext`, `.itemTitle`).
|
||||
- Корневой класс каждого CSS Module компонента всегда называется `.root` — это упрощает ориентацию в DevTools и отладку DOM.
|
||||
- Модификаторы — отдельный класс с `_`, применяется через `&._modifier`.
|
||||
|
||||
**Хорошо**
|
||||
```css
|
||||
.submitButton {
|
||||
padding: 8px 16px;
|
||||
|
||||
&._disabled {
|
||||
opacity: 0.5;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```css
|
||||
/* Плохо: kebab-case и вложенный элемент вместо отдельного класса. */
|
||||
.submit-button {
|
||||
padding: 8px 16px;
|
||||
|
||||
&__icon {
|
||||
margin-right: 8px;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Вложенность
|
||||
|
||||
- Вложенность селекторов запрещена.
|
||||
- Исключения:
|
||||
- Псевдоклассы: `&:hover`, `&:active`, `&:focus`, `&:disabled` и т.д.
|
||||
- Псевдоэлементы: `&::before`, `&::after`.
|
||||
- Медиа-запросы: `@media`.
|
||||
- Модификаторы: `&._active`, `&._disabled`.
|
||||
- Каждый вложенный блок отделяется пустой строкой от предыдущих свойств.
|
||||
|
||||
**Хорошо**
|
||||
```css
|
||||
.card {
|
||||
padding: 16px;
|
||||
background-color: var(--color-bg);
|
||||
|
||||
&:hover {
|
||||
background-color: var(--color-bg-hover);
|
||||
}
|
||||
|
||||
&::after {
|
||||
content: '';
|
||||
display: block;
|
||||
}
|
||||
|
||||
&._highlighted {
|
||||
border-color: var(--color-primary);
|
||||
}
|
||||
|
||||
@media (--md) {
|
||||
padding: 24px;
|
||||
}
|
||||
}
|
||||
|
||||
.cardTitle {
|
||||
font-size: 16px;
|
||||
|
||||
@media (--md) {
|
||||
font-size: 20px;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```css
|
||||
/* Плохо: вложенность селекторов, нет пустых строк между блоками. */
|
||||
.card {
|
||||
padding: 16px;
|
||||
.cardTitle {
|
||||
font-size: 16px;
|
||||
}
|
||||
&:hover {
|
||||
background-color: var(--color-bg-hover);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Медиа-запросы
|
||||
|
||||
- Только **Custom Media Queries**: `@media (--md) {}`.
|
||||
- Запрещены произвольные breakpoints: `@media (min-width: 768px)`.
|
||||
- `@media` пишется только **внутри** селектора.
|
||||
- Запрещено писать `@media` на верхнем уровне с селекторами внутри.
|
||||
|
||||
**Хорошо**
|
||||
```css
|
||||
.sidebar {
|
||||
display: none;
|
||||
|
||||
@media (--md) {
|
||||
display: block;
|
||||
}
|
||||
}
|
||||
|
||||
.sidebarTitle {
|
||||
font-size: 14px;
|
||||
|
||||
@media (--md) {
|
||||
font-size: 18px;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```css
|
||||
/* Плохо: @media на верхнем уровне с селекторами внутри. */
|
||||
@media (--md) {
|
||||
.sidebar {
|
||||
display: block;
|
||||
}
|
||||
|
||||
.sidebarTitle {
|
||||
font-size: 18px;
|
||||
}
|
||||
}
|
||||
|
||||
/* Плохо: произвольный breakpoint вместо custom media. */
|
||||
.sidebar {
|
||||
@media (min-width: 992px) {
|
||||
display: block;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## CSS-переменные
|
||||
|
||||
- Цвета (`--color-*`), отступы (`--space-*`), скругления (`--radius-*`) определяются в `src/shared/styles/variables.css` через `:root`.
|
||||
- Файл переменных подключается через `src/shared/styles/global.css`, который импортируется один раз в `src/app/layout.tsx`.
|
||||
- Не дублировать магические значения в компонентах.
|
||||
|
||||
**Хорошо**
|
||||
```css
|
||||
/* src/shared/styles/variables.css */
|
||||
:root {
|
||||
--color-primary: #3b82f6;
|
||||
--color-bg: #ffffff;
|
||||
--color-bg-hover: #f5f5f5;
|
||||
--space-1: 4px;
|
||||
--space-2: 8px;
|
||||
--space-3: 12px;
|
||||
--radius-1: 4px;
|
||||
--radius-2: 8px;
|
||||
}
|
||||
```
|
||||
|
||||
```css
|
||||
/* компонент */
|
||||
.card {
|
||||
padding: var(--space-3);
|
||||
border-radius: var(--radius-2);
|
||||
background-color: var(--color-bg);
|
||||
}
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```css
|
||||
/* Плохо: магические значения вместо переменных. */
|
||||
.card {
|
||||
padding: 12px;
|
||||
border-radius: 8px;
|
||||
background-color: #ffffff;
|
||||
}
|
||||
```
|
||||
|
||||
## Custom Media
|
||||
|
||||
- Breakpoints определяются через Custom Media Queries в `src/shared/styles/media.css`.
|
||||
- Custom media подключаются глобально через конфиг PostCSS (плагин `postcss-custom-media`) — не импортировать в файлы стилей.
|
||||
|
||||
```css
|
||||
/* src/shared/styles/media.css */
|
||||
@custom-media --sm (min-width: 36em);
|
||||
@custom-media --md (min-width: 62em);
|
||||
@custom-media --lg (min-width: 82em);
|
||||
```
|
||||
|
||||
## Импорт стилей
|
||||
|
||||
- Стили компонента импортируются только внутри своего компонента.
|
||||
- Запрещено импортировать стили одного компонента в другой.
|
||||
- Custom media не импортируются в файлы стилей — они подключаются глобально через конфиг PostCSS.
|
||||
|
||||
## Форматирование
|
||||
|
||||
- Пустая строка между селекторами верхнего уровня.
|
||||
- Пустая строка перед каждым вложенным блоком (медиа, псевдокласс, модификатор).
|
||||
|
||||
**Хорошо**
|
||||
```css
|
||||
.userBar {
|
||||
display: none;
|
||||
color: var(--color-text);
|
||||
|
||||
@media (--md) {
|
||||
display: flex;
|
||||
}
|
||||
}
|
||||
|
||||
.userBarButton {
|
||||
background-color: var(--color-bg);
|
||||
|
||||
&:hover {
|
||||
background-color: var(--color-bg-hover);
|
||||
}
|
||||
|
||||
&._active {
|
||||
background-color: var(--color-primary);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```css
|
||||
/* Плохо: нет пустых строк между селекторами и вложенными блоками. */
|
||||
.userBar {
|
||||
display: none;
|
||||
color: var(--color-text);
|
||||
@media (--md) {
|
||||
display: flex;
|
||||
}
|
||||
}
|
||||
.userBarButton {
|
||||
background-color: var(--color-bg);
|
||||
&:hover {
|
||||
background-color: var(--color-bg-hover);
|
||||
}
|
||||
&._active {
|
||||
background-color: var(--color-primary);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Единицы измерения
|
||||
|
||||
- `px` — основная единица измерения.
|
||||
- Остальные (`em`, `rem`, `%`, `vh`/`vw`) — допускаются по необходимости дизайна.
|
||||
|
||||
## Порядок CSS-свойств
|
||||
|
||||
В стилях рекомендуется придерживаться логического порядка свойств:
|
||||
|
||||
1. Позиционирование (`position`, `top`, `left`, `z-index`).
|
||||
2. Блочная модель (`display`, `width`, `height`, `margin`, `padding`).
|
||||
3. Оформление (`background`, `border`, `box-shadow`, `border-radius`).
|
||||
4. Текст (`font`, `color`, `text-align`, `line-height`).
|
||||
5. Прочее (`transition`, `animation`, `opacity`, `cursor`).
|
||||
|
||||
## Комментарии
|
||||
|
||||
- Желательно не писать комментарии в CSS.
|
||||
- Исключение — нетривиальные хаки и обходные решения, к которым стоит оставить пояснение.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: SVG-спрайты
|
||||
description: "Что такое SVG-спрайты и какие проблемы они решают."
|
||||
---
|
||||
|
||||
# SVG-спрайты
|
||||
|
||||
Что такое SVG-спрайты и какие проблемы они решают.
|
||||
|
||||
## Проблема
|
||||
|
||||
Иконки в проекте — это десятки и сотни SVG-файлов, которые нужно как-то доставлять в интерфейс. Подход «один `<img>` на иконку» или инлайн SVG в каждом компоненте приводят к трём проблемам:
|
||||
|
||||
- **Дублирование.** Инлайн SVG в нескольких компонентах — один и тот же код размазан по проекту. Изменение иконки требует правок в десяти местах.
|
||||
- **Размер бандла.** Каждый инлайн SVG — полный XML-код, который попадает в JS-бандл. Сотня иконок × средний размер SVG = сотни килобайт, которые браузер парсит как JavaScript, а не как статику.
|
||||
- **Нет управления цветом.** Инлайн SVG жёстко закрашивает иконку. Сменить цвет по состоянию (`:hover`, `._disabled`) — значит дублировать SVG или городить `currentColor`-хаки в каждом компоненте.
|
||||
|
||||
## Решение
|
||||
|
||||
SVG-спрайты — это единый файл-контейнер, в который собираются все иконки проекта. В коде используется один React-компонент `<SvgSprite icon="name"/>`, а браузер загружает спрайт как статику — один раз, с кешированием.
|
||||
|
||||
Что дают SVG-спрайты:
|
||||
|
||||
- **Один источник.** Каждая иконка — один SVG-файл в `src/shared/sprites/`. Обновил файл — иконка обновилась везде.
|
||||
- **Лёгкий бандл.** Спрайт отдаётся как статический файл из `public/`, не попадает в JavaScript. Типы имён иконок генерируются автоматически — автодополнение работает без ручных описаний.
|
||||
- **Цвет через CSS.** При сборке цвета в SVG заменяются на CSS-переменные. Цвет иконки меняется через `color` родителя или через переменные `--icon-color-N` — как любой другой стиль.
|
||||
|
||||
## Состав раздела
|
||||
|
||||
- [Настройка](./svg-sprites-setup.md) — подключение пакета, конфигурация, первая генерация.
|
||||
- [Использование](./svg-sprites-usage.md) — добавление иконок, компонент `<SvgSprite/>`, управление цветом.
|
||||
132
ai/nextjs-style-guide/applied/svg-sprites/svg-sprites-setup.md
Normal file
132
ai/nextjs-style-guide/applied/svg-sprites/svg-sprites-setup.md
Normal file
@@ -0,0 +1,132 @@
|
||||
---
|
||||
title: Настройка SVG-спрайтов
|
||||
description: Подключение SVG-спрайтов в новом проекте.
|
||||
keywords: [svg-sprites, установка, настройка, config, пакет, "@gromlab/svg-sprites", svg-sprites.config.ts]
|
||||
---
|
||||
|
||||
# Настройка SVG-спрайтов
|
||||
Подключение SVG-спрайтов в новом проекте.
|
||||
|
||||
## Установка
|
||||
|
||||
1. Установить пакет:
|
||||
|
||||
```bash
|
||||
npm install @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
2. Создать `svg-sprites.config.ts` в корне проекта (см. [Стандартный конфиг](#стандартныи-конфиг)).
|
||||
|
||||
3. Создать папку входа для SVG-файлов в слое `shared`:
|
||||
|
||||
```bash
|
||||
mkdir -p src/shared/sprites/icons
|
||||
```
|
||||
|
||||
Источники спрайтов живут в `src/shared/sprites/<group>/` — это слой `shared` SLM-архитектуры (см. [Структура проекта](../project-structure.md), [Архитектура](../../basics/architecture/index.md)). В `src/` посторонних каталогов вне слоёв не заводим.
|
||||
|
||||
4. Добавить скрипты в `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprite": "svg-sprites",
|
||||
"predev": "svg-sprites",
|
||||
"prebuild": "svg-sprites"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Хуки `predev` и `prebuild` гарантируют, что спрайты и типы всегда актуальны перед запуском и сборкой.
|
||||
|
||||
5. Добавить сгенерированные артефакты в `.gitignore`:
|
||||
|
||||
```text
|
||||
# Сгенерированные спрайты и React-компонент
|
||||
/public/sprites/
|
||||
/src/ui/svg-sprite/
|
||||
```
|
||||
|
||||
6. Выполнить первую генерацию:
|
||||
|
||||
```bash
|
||||
npm run sprite
|
||||
```
|
||||
|
||||
7. Подключить спрайт в layout. Глобальный спрайт (иконки) подключается через `<link rel="preload">` в корневом layout — браузер загрузит файл заранее и закеширует:
|
||||
|
||||
```tsx
|
||||
// src/app/layout.tsx
|
||||
import 'shared/styles/global.css'
|
||||
|
||||
import type { Metadata } from 'next'
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: 'App',
|
||||
description: '',
|
||||
}
|
||||
|
||||
export default function RootLayout({ children }: { children: React.ReactNode }) {
|
||||
return (
|
||||
<html lang="ru">
|
||||
<head>
|
||||
<link rel="preload" href="/sprites/icons.sprite.stack.svg" as="image" />
|
||||
</head>
|
||||
<body>{children}</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Локальные спрайты (если есть) подключаются аналогично в layout конкретной страницы или маршрута.
|
||||
|
||||
## Стандартный конфиг
|
||||
|
||||
Файл `svg-sprites.config.ts` в корне проекта. Это канон — отклонения только по явной причине.
|
||||
|
||||
```ts
|
||||
// svg-sprites.config.ts
|
||||
import { defineConfig } from '@gromlab/svg-sprites'
|
||||
|
||||
export default defineConfig({
|
||||
output: 'public/sprites',
|
||||
publicPath: '/sprites',
|
||||
react: 'src/ui/svg-sprite',
|
||||
sprites: [
|
||||
{ name: 'icons', input: 'src/shared/sprites/icons' },
|
||||
],
|
||||
})
|
||||
```
|
||||
|
||||
### Фиксированные значения
|
||||
|
||||
| Опция | Значение | Почему так |
|
||||
|-------|----------|------------|
|
||||
| `output` | `public/sprites` | Единая папка статики Next.js |
|
||||
| `publicPath` | `/sprites` | URL-путь без `public/` (Next.js раздаёт `public/` как `/`) |
|
||||
| `react` | `src/ui/svg-sprite` | Слой `ui/` из архитектуры проекта (→ [Архитектура](../../basics/architecture/index.md)) |
|
||||
| `sprites[0].name` | `icons` | Основной спрайт всегда называется `icons` |
|
||||
|
||||
### Трансформации
|
||||
|
||||
Все значения по умолчанию оставлять включёнными:
|
||||
|
||||
```ts
|
||||
transform: {
|
||||
removeSize: true,
|
||||
replaceColors: true,
|
||||
addTransition: true,
|
||||
}
|
||||
```
|
||||
|
||||
Явно прописывать блок `transform` не нужно — пакет применяет эти значения по умолчанию.
|
||||
|
||||
Отключать `replaceColors` — только для отдельного спрайта с фиксированной палитрой (например, брендовые логотипы). Делать это на уровне спрайта, не глобально.
|
||||
|
||||
### Режим
|
||||
|
||||
По умолчанию `mode: 'stack'` — не указывать явно. Переход на `symbol` требует обоснования: превью и примеры в пакете оптимизированы под `stack`.
|
||||
|
||||
## Дальше
|
||||
|
||||
- [Использование](./svg-sprites-usage.md) — добавление иконок, компонент `<SvgSprite/>`, управление цветом.
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
title: Использование SVG-спрайтов
|
||||
description: Как добавлять и использовать SVG-иконки в коде.
|
||||
keywords: [svg, спрайт, sprite, иконка, icon, SvgSprite, превью, preview, цвет, color]
|
||||
---
|
||||
|
||||
# Использование SVG-спрайтов
|
||||
|
||||
Как добавлять и использовать SVG-иконки в коде.
|
||||
|
||||
## Шаги
|
||||
|
||||
1. **Положить SVG в папку спрайта:**
|
||||
|
||||
```text
|
||||
src/shared/sprites/icons/new-icon.svg
|
||||
```
|
||||
|
||||
2. **Импортировать компонент.** Компонент `<SvgSprite/>` генерируется пакетом вместе с типами имён иконок — автодополнение работает без ручных описаний:
|
||||
|
||||
```tsx
|
||||
import { SvgSprite } from 'ui/svg-sprite'
|
||||
|
||||
<SvgSprite icon="new-icon" />
|
||||
```
|
||||
|
||||
3. **Посмотреть и пощупать иконку — в превью.** Пакет генерирует HTML-превью рядом со спрайтом (`public/sprites/icons.preview.html`). Там виден набор иконок, имена и поведение цвета.
|
||||
|
||||
## Управление цветом
|
||||
|
||||
При сборке цвета в SVG заменяются на CSS-переменные `--icon-color-N`. Управление — через обычный CSS родителя.
|
||||
|
||||
**Моно-иконка** наследует `color` родителя (`--icon-color-1` по умолчанию `currentColor`):
|
||||
|
||||
```css
|
||||
.button {
|
||||
color: var(--color-primary);
|
||||
}
|
||||
```
|
||||
|
||||
**Точечное переопределение** — через переменную:
|
||||
|
||||
```css
|
||||
.icon-danger {
|
||||
--icon-color-1: var(--color-danger);
|
||||
}
|
||||
```
|
||||
|
||||
**Мульти-иконка** — переменные задаются явно, порядок виден в превью:
|
||||
|
||||
```css
|
||||
.folder {
|
||||
--icon-color-1: var(--color-folder-bg);
|
||||
--icon-color-2: var(--color-folder-accent);
|
||||
}
|
||||
```
|
||||
91
ai/nextjs-style-guide/applied/templates/templates-create.md
Normal file
91
ai/nextjs-style-guide/applied/templates/templates-create.md
Normal file
@@ -0,0 +1,91 @@
|
||||
---
|
||||
title: Создание шаблонов генерации
|
||||
description: "Структура шаблонов, синтаксис переменных и примеры."
|
||||
keywords: [шаблоны, templates, .templates, syntax, переменные, kebabCase, pascalCase, scaffold]
|
||||
---
|
||||
|
||||
<!-- @formatter:off -->
|
||||
::: v-pre
|
||||
|
||||
# Создание шаблонов генерации
|
||||
|
||||
Структура шаблонов, синтаксис переменных и примеры.
|
||||
|
||||
## Структура шаблонов
|
||||
|
||||
Все шаблоны лежат в `.templates/` в корне проекта. Каждая папка — отдельный шаблон.
|
||||
|
||||
```text
|
||||
.templates/
|
||||
├── component/ # шаблон компонента
|
||||
│ └── {{name.kebabCase}}/
|
||||
│ ├── styles/
|
||||
│ │ └── {{name.kebabCase}}.module.css
|
||||
│ ├── types/
|
||||
│ │ └── {{name.kebabCase}}.type.ts
|
||||
│ ├── {{name.kebabCase}}.tsx
|
||||
│ └── index.ts
|
||||
└── store/ # шаблон Zustand стора
|
||||
└── {{name.kebabCase}}/
|
||||
├── {{name.kebabCase}}.store.ts
|
||||
├── {{name.kebabCase}}.type.ts
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
## Синтаксис шаблонов
|
||||
|
||||
### Переменные
|
||||
|
||||
Переменные работают в именах файлов/папок и внутри файлов:
|
||||
|
||||
```text
|
||||
{{variable}}
|
||||
```
|
||||
|
||||
Переменные могут быть любыми. `name` — дефолтная, подставляется генератором автоматически. Если реализация требует дополнительных параметров — можно использовать произвольные наборы переменных.
|
||||
|
||||
### Модификаторы
|
||||
|
||||
Модификаторы меняют регистр и формат записи переменной:
|
||||
|
||||
```text
|
||||
{{name.pascalCase}} → MyButton
|
||||
{{name.camelCase}} → myButton
|
||||
{{name.kebabCase}} → my-button
|
||||
{{name.snakeCase}} → my_button
|
||||
{{name.screamingSnakeCase}} → MY_BUTTON
|
||||
```
|
||||
|
||||
## Как создать новый шаблон
|
||||
|
||||
1. Создать папку в `.templates/` с именем шаблона (например `hook`).
|
||||
2. Внутри разместить файлы и папки, используя `{{name}}` и модификаторы в именах и содержимом.
|
||||
3. Шаблон сразу доступен и в расширении VS Code, и в CLI.
|
||||
|
||||
Пример — создание шаблона для хука:
|
||||
|
||||
```text
|
||||
.templates/
|
||||
└── hook/
|
||||
└── {{name.kebabCase}}/
|
||||
├── {{name.kebabCase}}.hook.ts
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
```ts
|
||||
// .templates/hook/{{name.kebabCase}}.hook.ts
|
||||
export const {{name.camelCase}} = () => {
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
// .templates/hook/index.ts
|
||||
export { {{name.camelCase}} } from './{{name.kebabCase}}.hook'
|
||||
```
|
||||
|
||||
## Дальше
|
||||
|
||||
- [Использование](./templates-usage.md) — генерация через VS Code плагин и CLI.
|
||||
|
||||
:::
|
||||
32
ai/nextjs-style-guide/applied/templates/templates-intro.md
Normal file
32
ai/nextjs-style-guide/applied/templates/templates-intro.md
Normal file
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: Шаблоны генерации
|
||||
description: "Что такое шаблоны кодогенерации и какие проблемы они решают."
|
||||
---
|
||||
|
||||
# Шаблоны генерации
|
||||
|
||||
Что такое шаблоны кодогенерации и какие проблемы они решают.
|
||||
|
||||
## Проблема
|
||||
|
||||
Каждый новый модуль в проекте — компонент, стор, бизнес-модуль — требует однотипной структуры файлов и boilerplate-кода. Ручное создание приводит к трём проблемам:
|
||||
|
||||
- **Расхождения.** Разные разработчики создают модули по-разному: забывают `index.ts`, называют типы не по канону, пропускают стили.
|
||||
- **Время.** Создание одного компонента с типами, стилями и экспортом — 5–10 минут рутины. За спринт набегают часы.
|
||||
- **Ошибки копипасты.** Копирование существующего модуля и переименование — источник опечаток и забытых ссылок.
|
||||
|
||||
## Решение
|
||||
|
||||
Шаблоны кодогенерации — это папки с файлами-заготовками в `.templates/`. Вместо ручного создания файлов разработчик вызывает генератор, указывает имя — и получает готовый модуль со всей структурой, именами и boilerplate, подставленными автоматически.
|
||||
|
||||
Что дают шаблоны:
|
||||
|
||||
- **Единообразие.** Все модули одного типа идентичны по структуре. Канон живёт в шаблоне, а не в памяти разработчика.
|
||||
- **Скорость.** Генерация модуля — одна команда. Остальное время — на бизнес-логику.
|
||||
- **Согласованность с архитектурой.** Шаблоны учитывают SLM: правильные слои, сегменты, экспорты. Отклонение от стайлгайда требует осознанного усилия, а не случайного упущения.
|
||||
|
||||
## Состав раздела
|
||||
|
||||
- [Настройка](./templates-setup.md) — первичная установка: скачивание стандартного набора шаблонов в проект.
|
||||
- [Создание шаблонов](./templates-create.md) — структура файлов, синтаксис переменных, примеры.
|
||||
- [Использование](./templates-usage.md) — генерация через VS Code плагин и CLI.
|
||||
44
ai/nextjs-style-guide/applied/templates/templates-setup.md
Normal file
44
ai/nextjs-style-guide/applied/templates/templates-setup.md
Normal file
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: Настройка шаблонов генерации
|
||||
description: Первичная установка шаблонов кодогенерации в проект.
|
||||
keywords: [шаблоны, templates, .templates, tiged, generator, генератор шаблонов, скачать шаблоны, scaffold]
|
||||
---
|
||||
|
||||
# Настройка шаблонов генерации
|
||||
|
||||
Первичная установка шаблонов кодогенерации в проект.
|
||||
|
||||
## Установка
|
||||
|
||||
1. Проверить, что `.templates/` отсутствует (или согласовать перезапись, если папка уже есть).
|
||||
|
||||
2. Скачать папку из эталонного репозитория:
|
||||
|
||||
```bash
|
||||
npx tiged git@gromlab.ru:templates/nextjs-template.git/.templates .templates
|
||||
```
|
||||
|
||||
3. Если `tiged` падает в default-режиме (HTTP-tarball у Gitea) — повторить с явным git-режимом:
|
||||
|
||||
```bash
|
||||
npx tiged --mode=git git@gromlab.ru:templates/nextjs-template.git/.templates .templates
|
||||
```
|
||||
|
||||
4. Проверить генерацию:
|
||||
|
||||
```bash
|
||||
npx @gromlab/create component test src/ui
|
||||
```
|
||||
|
||||
После проверки — удалить тестовый модуль.
|
||||
|
||||
## Проверка установки
|
||||
|
||||
- В корне проекта есть папка `.templates/`.
|
||||
- Внутри `.templates/` присутствуют стандартные шаблоны (или согласованный кастомный набор).
|
||||
- Пробная генерация через `npx @gromlab/create ...` отрабатывает без ошибок.
|
||||
|
||||
## Дальше
|
||||
|
||||
- [Создание шаблонов](./templates-create.md) — структура файлов, синтаксис переменных, примеры.
|
||||
- [Использование](./templates-usage.md) — генерация через VS Code плагин и CLI.
|
||||
39
ai/nextjs-style-guide/applied/templates/templates-usage.md
Normal file
39
ai/nextjs-style-guide/applied/templates/templates-usage.md
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: Использование шаблонов генерации
|
||||
description: Генерация файлов из шаблонов через VS Code плагин и CLI.
|
||||
keywords: [шаблоны, templates, generate, VS Code, CLI, gromlab/create, npx, scaffold]
|
||||
---
|
||||
|
||||
# Использование шаблонов генерации
|
||||
|
||||
Генерация файлов из шаблонов через VS Code плагин и CLI.
|
||||
|
||||
## Через VS Code
|
||||
|
||||
Template File Generator | gromlab ([Marketplace](https://marketplace.visualstudio.com/items?itemName=gromlab.vscode-templateFileGenerator), [Open VSX](https://open-vsx.org/extension/gromlab/vscode-templateFileGenerator)) — расширение для генерации файлов и папок из шаблонов через интерфейс редактора.
|
||||
|
||||
1. ПКМ на целевой папке в проводнике VS Code.
|
||||
2. **Generate from template** → выбрать шаблон.
|
||||
3. Ввести имя (например `button`) — расширение подставит его во все переменные `{{name}}`.
|
||||
|
||||
Расширение устанавливается разово на машину разработчика, не через проект.
|
||||
|
||||
## Через CLI
|
||||
|
||||
[@gromlab/create](https://www.npmjs.com/package/@gromlab/create) — CLI для генерации из тех же шаблонов. Используется через npx, глобальная установка не требуется.
|
||||
|
||||
```bash
|
||||
npx @gromlab/create <шаблон> <имя> [путь]
|
||||
```
|
||||
|
||||
Путь не обязателен — по умолчанию генерация происходит в текущую директорию.
|
||||
|
||||
| Команда | Что создаёт |
|
||||
|---|---|
|
||||
| `npx @gromlab/create component button` | Компонент в текущей папке |
|
||||
| `npx @gromlab/create module auth src/business` | Бизнес-модуль |
|
||||
| `npx @gromlab/create widget header src/widgets` | Виджет |
|
||||
| `npx @gromlab/create layout admin src/layouts` | Layout |
|
||||
| `npx @gromlab/create store auth src/business/auth/stores` | Стор |
|
||||
|
||||
CLI вызывается через `npx`, в `package.json` отдельно не добавляется.
|
||||
88
ai/nextjs-style-guide/applied/vscode.md
Normal file
88
ai/nextjs-style-guide/applied/vscode.md
Normal file
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: VS Code
|
||||
description: Единые настройки редактора и расширений для команды.
|
||||
---
|
||||
|
||||
# VS Code
|
||||
|
||||
Единые настройки редактора и расширений для команды.
|
||||
|
||||
## Структура `.vscode/`
|
||||
|
||||
```text
|
||||
.vscode/
|
||||
├── extensions.json # Рекомендуемые расширения
|
||||
└── settings.json # Настройки редактора для проекта
|
||||
```
|
||||
|
||||
Оба файла коммитятся в репозиторий.
|
||||
|
||||
## Расширения
|
||||
|
||||
Файл `.vscode/extensions.json` определяет список расширений, которые VS Code предложит установить при открытии проекта.
|
||||
|
||||
```json
|
||||
// .vscode/extensions.json
|
||||
{
|
||||
"recommendations": [
|
||||
"biomejs.biome",
|
||||
"MyTemplateGenerator.mytemplategenerator",
|
||||
"csstools.postcss"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Расширение | Назначение |
|
||||
|---|---|
|
||||
| [Biome](https://marketplace.visualstudio.com/items?itemName=biomejs.biome) | Линтинг и форматирование кода. Заменяет ESLint и Prettier |
|
||||
| Template File Generator \| gromlab ([Marketplace](https://marketplace.visualstudio.com/items?itemName=gromlab.vscode-templateFileGenerator), [Open VSX](https://open-vsx.org/extension/gromlab/vscode-templateFileGenerator)) | Генерация файлов и папок из шаблонов `.templates/` через контекстное меню |
|
||||
| [PostCSS Language Support](https://marketplace.visualstudio.com/items?itemName=csstools.postcss) | Подсветка синтаксиса и автодополнение для PostCSS (`@custom-media`, `@nest` и др.) |
|
||||
|
||||
### Зачем это нужно
|
||||
|
||||
- Новый участник команды получает все нужные расширения одним кликом.
|
||||
- Нет разночтений: все используют одинаковый форматтер и линтер.
|
||||
- Расширения привязаны к проекту, а не к конкретному разработчику.
|
||||
|
||||
## Настройки редактора
|
||||
|
||||
Файл `.vscode/settings.json` переопределяет пользовательские настройки VS Code на уровне проекта.
|
||||
|
||||
```json
|
||||
// .vscode/settings.json
|
||||
{
|
||||
"editor.defaultFormatter": "biomejs.biome",
|
||||
"editor.formatOnSave": true,
|
||||
"editor.codeActionsOnSave": {
|
||||
"source.fixAll.biome": "explicit",
|
||||
"source.organizeImports.biome": "explicit"
|
||||
},
|
||||
"files.associations": {
|
||||
"*.css": "postcss"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Разбор настроек
|
||||
|
||||
| Настройка | Значение | Что делает |
|
||||
|---|---|---|
|
||||
| `editor.defaultFormatter` | `biomejs.biome` | Biome используется как единственный форматтер для всех файлов |
|
||||
| `editor.formatOnSave` | `true` | Код автоматически форматируется при каждом сохранении |
|
||||
| `codeActionsOnSave.source.fixAll.biome` | `explicit` | Biome автоматически применяет безопасные исправления при сохранении |
|
||||
| `codeActionsOnSave.source.organizeImports.biome` | `explicit` | Импорты сортируются и группируются автоматически при сохранении |
|
||||
| `files.associations` | `"*.css": "postcss"` | Все CSS-файлы открываются с подсветкой PostCSS вместо стандартного CSS |
|
||||
|
||||
### Зачем это нужно
|
||||
|
||||
- **Единый стиль кода** -- форматирование происходит автоматически, невозможно закоммитить неформатированный код.
|
||||
- **Автофикс при сохранении** -- распространённые ошибки линтинга исправляются без ручного вмешательства.
|
||||
- **Сортировка импортов** -- импорты всегда в одном порядке, без конфликтов при мерже.
|
||||
- **PostCSS-подсветка** -- кастомные at-правила (`@custom-media`, `@define-mixin`) подсвечиваются корректно, а не как ошибки.
|
||||
|
||||
## Что не должно быть в `.vscode/`
|
||||
|
||||
Не коммитятся файлы, специфичные для конкретного разработчика:
|
||||
|
||||
- **Не коммитить**: отладочные конфигурации с локальными путями, персональные сниппеты, настройки тем оформления.
|
||||
- **Коммитить**: только `extensions.json` и `settings.json` с общими для команды настройками.
|
||||
100
ai/nextjs-style-guide/basics/architecture/index.md
Normal file
100
ai/nextjs-style-guide/basics/architecture/index.md
Normal file
@@ -0,0 +1,100 @@
|
||||
---
|
||||
title: SLM Design
|
||||
description: "Архитектурный подход проекта: что такое SLM и как он устроен."
|
||||
---
|
||||
|
||||
# SLM Design
|
||||
|
||||
Архитектурный подход проекта: что такое SLM и как он устроен.
|
||||
|
||||
## Преимущества
|
||||
|
||||
### Вертикальная организация домена
|
||||
|
||||
Бизнес-домен не разбивается по техническим слоям — сценарии, сущности, типы и UI живут в одном модуле. Это сокращает время навигации и упрощает сопровождение: все изменения домена локализованы.
|
||||
|
||||
### Dependency Injection без фреймворков
|
||||
|
||||
Cross-domain зависимости в бизнес-слое реализуются через фабрики — модуль декларирует что ему нужно, а точка использования предоставляет зависимости. Домены изолированы без DI-контейнеров, провайдеров и шин событий.
|
||||
|
||||
### Разделение ответственности без перегрузки слоёв
|
||||
|
||||
Сервисы приложения (`infrastructure/`), UI-кит (`ui/`) и общие ресурсы (`shared/`) — три разных слоя с разной природой. Ни один слой не превращается в свалку разнородного кода.
|
||||
|
||||
### Горизонтальная инкапсуляция
|
||||
|
||||
Вложенные модули (`parts/`) и направление зависимостей позволяют нескольким разработчикам работать над одной областью приложения параллельно, не затрагивая код друг друга.
|
||||
|
||||
### Колокация по умолчанию
|
||||
|
||||
Код начинает жизнь рядом с местом использования и поднимается в общие слои только при реальной потребности. Глобальные слои не засоряются преждевременными абстракциями.
|
||||
|
||||
### Явное разделение каркаса и контента
|
||||
|
||||
Каркас группы маршрутов (`layouts/`) и контент конкретной страницы (`screens/`) — независимые слои с собственной ответственностью.
|
||||
|
||||
### Масштабирование через группировку
|
||||
|
||||
При росте проекта слои не теряют структуру — модули группируются по естественным признакам: бизнес-домены по субдоменам, страницы по разделам, UI-компоненты по уровню абстракции (примитивы и композиции).
|
||||
|
||||
## Происхождение
|
||||
|
||||
SLM Design вырос на основе:
|
||||
|
||||
- **Feature-Sliced Design** — слоистая структура, публичный API модуля, направление зависимостей
|
||||
- **Vertical Slice Architecture** — модуль как вертикальный срез, содержащий всё необходимое
|
||||
- **Screaming Architecture** — структура проекта «кричит» о назначении: открыл `business/auth` — видишь авторизацию
|
||||
- **Colocation Principle** — код живёт рядом с местом использования
|
||||
|
||||
## Пример структуры проекта
|
||||
|
||||
```text
|
||||
src/
|
||||
├── app/
|
||||
│
|
||||
├── layouts/
|
||||
│ ├── main/
|
||||
│ └── dashboard/
|
||||
│
|
||||
├── screens/
|
||||
│ ├── home/
|
||||
│ ├── products/
|
||||
│ ├── product-detail/
|
||||
│ └── about/
|
||||
│
|
||||
├── widgets/
|
||||
│ ├── page-heading/
|
||||
│ ├── hero-section/
|
||||
│ └── promo-banner/
|
||||
│
|
||||
├── business/
|
||||
│ ├── auth/
|
||||
│ ├── catalog/
|
||||
│ ├── orders/
|
||||
│ └── chat/
|
||||
│
|
||||
├── infrastructure/
|
||||
│ ├── theme/
|
||||
│ ├── i18n/
|
||||
│ ├── backend-api/
|
||||
│ └── logger/
|
||||
│
|
||||
├── ui/
|
||||
│ ├── button/
|
||||
│ ├── input/
|
||||
│ ├── modal/
|
||||
│ ├── toast/
|
||||
│ └── dropdown/
|
||||
│
|
||||
└── shared/
|
||||
├── lib/
|
||||
├── types/
|
||||
└── styles/
|
||||
```
|
||||
|
||||
## Принципы
|
||||
|
||||
- **Домен — единое целое.** Всё, что относится к домену, живёт в одном модуле.
|
||||
- **Колокация.** Код рождается рядом с местом использования и поднимается только при необходимости.
|
||||
- **Зависимости однонаправлены.** Импорты только сверху вниз, только через публичный API.
|
||||
- **Архитектура — каркас, не клетка.** Правила фиксируют направление зависимостей и структуру модуля, остальное определяет команда.
|
||||
253
ai/nextjs-style-guide/basics/architecture/reference/layers.md
Normal file
253
ai/nextjs-style-guide/basics/architecture/reference/layers.md
Normal file
@@ -0,0 +1,253 @@
|
||||
---
|
||||
title: Слои SLM
|
||||
description: Из каких слоёв состоит SLM-архитектура и как они связаны.
|
||||
---
|
||||
|
||||
# Слои SLM
|
||||
|
||||
Из каких слоёв состоит SLM-архитектура и как они связаны.
|
||||
|
||||
## Определение
|
||||
|
||||
**Слой — уровень организации кода внутри `src/`. Каждый слой отвечает за свою область (каркас страницы, бизнес-логика, UI-кит) и задаёт правила для кода внутри: направление импортов, именование, допустимые связи между модулями.**
|
||||
|
||||
## Группы слоёв
|
||||
|
||||
Слои делятся на три группы:
|
||||
|
||||
| Группа | Слои | Описание |
|
||||
|--------|------|----------|
|
||||
| Композиция | `app`, `layouts`, `screens`, `widgets` | Собирают интерфейс из готовых блоков: маршруты, каркасы, страницы |
|
||||
| Ядро | `business`, `infrastructure`, `ui` | Реализация продукта: бизнес-домены, техсервисы, UI-кит |
|
||||
| Фундамент | `shared` | Общие ресурсы: утилиты, хелперы, стили, конфиги |
|
||||
|
||||
## Направление зависимостей
|
||||
|
||||
Любой импорт между модулями — только через публичный API.
|
||||
|
||||
```
|
||||
app → [ layouts | screens ] → widgets → business → infrastructure → ui → shared
|
||||
```
|
||||
|
||||
- `layouts` и `screens` — параллельные слои, не импортируют друг друга
|
||||
- Модули одного слоя в группе «Композиция» изолированы друг от друга
|
||||
- Модули одного слоя `infrastructure` и `ui` могут импортировать друг друга через публичный API
|
||||
- Модули `business` — cross-domain зависимости по коду через фабрику, `import type` напрямую
|
||||
- Импорт типов (`import type`) в «Ядре» разрешён в обоих направлениях
|
||||
|
||||
|
||||
## Слой App
|
||||
|
||||
Точка входа приложения. Отвечает за запуск, роутинг и композицию маршрутов из layout и screen.
|
||||
|
||||
В отличие от остальных слоёв, `app/` не содержит модулей SLM. Здесь живут только инфраструктурные файлы, которые не могут быть никаким другим слоем: файлы фреймворка роутинга, точка запуска и код инициализации.
|
||||
|
||||
### Требования
|
||||
|
||||
- Не содержит модулей SLM — только файлы фреймворка, роутинг, инициализация
|
||||
- Содержит: файлы маршрутов, bootstrap, обработку ошибок верхнего уровня (404, error boundary), подключение глобальных стилей и ассетов
|
||||
- Провайдеры и гарды — только подключает готовые из нижних слоёв, не реализует
|
||||
- Не содержит бизнес-логику, UI-компоненты, хуки, сторы, сервисы
|
||||
- Никем не импортируется
|
||||
|
||||
## Слой Layouts
|
||||
|
||||
Каркас страницы: общие элементы, одинаковые для группы маршрутов (header, footer, sidebar).
|
||||
|
||||
```text
|
||||
src/layouts/
|
||||
├── main/
|
||||
├── dashboard/
|
||||
└── auth/
|
||||
```
|
||||
|
||||
### Требования
|
||||
|
||||
- Содержит только модули
|
||||
- Не содержит бизнес-логику
|
||||
- Контекстно-зависимые блоки принимает через пропсы от `app`, не импортирует напрямую
|
||||
|
||||
## Слой Screens
|
||||
|
||||
Контент конкретной страницы: собирает её из модулей нижних слоёв.
|
||||
|
||||
```text
|
||||
src/screens/
|
||||
├── home/
|
||||
├── products/
|
||||
├── product-detail/
|
||||
├── about/
|
||||
└── contacts/
|
||||
```
|
||||
|
||||
Когда количество страниц затрудняет навигацию — вводится группировка по разделам. Группа — папка для организации, не модуль (без `index.ts`).
|
||||
|
||||
```text
|
||||
src/screens/
|
||||
├── shop/
|
||||
│ ├── home/
|
||||
│ ├── products/
|
||||
│ ├── product-detail/
|
||||
│ └── cart/
|
||||
├── account/
|
||||
│ ├── profile/
|
||||
│ ├── settings/
|
||||
│ └── order-history/
|
||||
└── info/
|
||||
├── about/
|
||||
├── contacts/
|
||||
└── faq/
|
||||
```
|
||||
|
||||
### Требования
|
||||
|
||||
- Содержит только модули
|
||||
- Не содержит бизнес-логику
|
||||
- Локальные одноразовые секции живут внутри screen-модуля, не выносятся в `widgets`/`business`
|
||||
|
||||
## Слой Widgets
|
||||
|
||||
Составной блок интерфейса, который компонует модули ядра, но не принадлежит конкретному бизнес-домену. Widget появляется когда блок используется в нескольких screens или layouts.
|
||||
|
||||
Если блок принадлежит домену — он живёт в `business/{area}/`, даже если переиспользуется. Если блок нужен только в одном месте — это `screens/{name}/parts/` или `layouts/{name}/parts/`, а не widget.
|
||||
|
||||
```text
|
||||
src/widgets/
|
||||
├── page-heading/
|
||||
├── hero-section/
|
||||
├── onboarding-checklist/
|
||||
├── promo-banner/
|
||||
└── error-boundary/
|
||||
```
|
||||
|
||||
### Требования
|
||||
|
||||
- Не принадлежит конкретному бизнес-домену. Если блок доменный — он живёт в `business/`
|
||||
- Используется в нескольких screens или layouts
|
||||
|
||||
## Слой Business
|
||||
|
||||
Бизнес-домены приложения: auth, catalog, orders, checkout, chat. Каждый домен — отдельный модуль со своими типами, логикой, UI и сервисами.
|
||||
|
||||
Слой входит в группу «Ядро». Импортирует `infrastructure/`, `ui/`, `shared/`. Cross-domain зависимости по коду реализуются через фабрику. `import type` между доменами разрешён напрямую.
|
||||
|
||||
Business объединяет то, что в FSD разделено на `features` и `entities`: пользовательские сценарии и бизнес-сущности живут вместе, внутри одного домена. Внутри домена сегменты разделяют ответственность: `types/` — доменная модель, `hooks/` и `services/` — сценарии и логика, `mappers/` — трансформация данных, `parts/` — составные блоки.
|
||||
|
||||
```text
|
||||
src/business/
|
||||
├── auth/
|
||||
├── catalog/
|
||||
├── orders/
|
||||
├── checkout/
|
||||
└── chat/
|
||||
```
|
||||
|
||||
Когда количество доменов затрудняет навигацию — вводится группировка по субдоменам. Группа — папка для организации, не модуль (без `index.ts`).
|
||||
|
||||
```text
|
||||
src/business/
|
||||
├── commerce/
|
||||
│ ├── catalog/
|
||||
│ ├── cart/
|
||||
│ ├── orders/
|
||||
│ └── checkout/
|
||||
└── communication/
|
||||
├── chat/
|
||||
└── notifications/
|
||||
```
|
||||
|
||||
### Требования
|
||||
|
||||
- Один модуль = один бизнес-домен
|
||||
- Циклические зависимости между доменами запрещены
|
||||
- Импорт кода между доменами — через фабрику. `import type` — напрямую
|
||||
- Доменные типы (`User`, `Product`) живут здесь, не в `shared/`
|
||||
|
||||
## Слой Infrastructure
|
||||
|
||||
Техсервисы приложения: theme, i18n, API-адаптеры, logger, realtime. Каждый сервис — отдельный модуль.
|
||||
|
||||
Слой входит в группу «Ядро». Импортирует `infrastructure/`, `ui/`, `shared/`.
|
||||
|
||||
Отличие от `shared/`: infrastructure — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
|
||||
|
||||
```text
|
||||
src/infrastructure/
|
||||
├── theme/
|
||||
├── i18n/
|
||||
├── backend-api/
|
||||
├── maps-api/
|
||||
├── logger/
|
||||
├── feature-flags/
|
||||
└── realtime/
|
||||
```
|
||||
|
||||
### Требования
|
||||
|
||||
- Один модуль = один техсервис
|
||||
- Импортирует `infrastructure/`, `ui/`, `shared/`
|
||||
|
||||
## Слой UI
|
||||
|
||||
UI-кит без бизнес-логики: button, carousel, toast, modal.
|
||||
|
||||
Слой входит в группу «Ядро». Импортирует `ui/` и `shared/`.
|
||||
|
||||
Компоненты строятся друг на друге: `button` использует `icon`, `carousel` использует `button`.
|
||||
|
||||
```text
|
||||
src/ui/
|
||||
├── button/
|
||||
├── input/
|
||||
├── icon/
|
||||
├── carousel/
|
||||
├── modal/
|
||||
├── toast/
|
||||
├── dropdown/
|
||||
├── tabs/
|
||||
└── tooltip/
|
||||
```
|
||||
|
||||
Когда количество компонентов затрудняет навигацию — вводится группировка на примитивы и композиции. Примитивы (`button`, `icon`, `input`) не импортируют композиции. Композиции (`carousel`, `modal`, `dropdown`) строятся на примитивах.
|
||||
|
||||
```text
|
||||
src/ui/
|
||||
├── primitives/
|
||||
│ ├── button/
|
||||
│ ├── input/
|
||||
│ ├── icon/
|
||||
│ └── badge/
|
||||
└── composites/
|
||||
├── carousel/
|
||||
├── modal/
|
||||
├── dropdown/
|
||||
├── tabs/
|
||||
└── tooltip/
|
||||
```
|
||||
|
||||
### Требования
|
||||
|
||||
- Не содержит бизнес-логику
|
||||
- Импортирует только `ui/` и `shared/`
|
||||
|
||||
## Слой Shared
|
||||
|
||||
Общие ресурсы: утилиты, хелперы, стили, конфиги. Не знает о бизнес-домене.
|
||||
|
||||
Слой входит в группу «Фундамент» — ни о ком не знает, никого не импортирует.
|
||||
|
||||
Отличие от `infrastructure/`: infrastructure — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
|
||||
|
||||
Отличие от `ui/`: UI-компоненты (button, carousel, modal) живут в слое `ui/`, а не здесь.
|
||||
|
||||
```text
|
||||
src/shared/
|
||||
├── lib/
|
||||
├── types/
|
||||
├── styles/
|
||||
└── sprites/
|
||||
```
|
||||
|
||||
### Требования
|
||||
|
||||
- Не имеет runtime-состояния
|
||||
165
ai/nextjs-style-guide/basics/architecture/reference/modules.md
Normal file
165
ai/nextjs-style-guide/basics/architecture/reference/modules.md
Normal file
@@ -0,0 +1,165 @@
|
||||
---
|
||||
title: Модули SLM
|
||||
description: Что такое модуль в SLM-архитектуре и как он устроен.
|
||||
---
|
||||
|
||||
# Модули SLM
|
||||
|
||||
Что такое модуль в SLM-архитектуре и как он устроен.
|
||||
|
||||
## Определение
|
||||
|
||||
**Модуль — универсальный строительный блок архитектуры. Живёт на слое и содержит всё необходимое для своей работы: компоненты, хуки, сторы, сервисы, типы, стили. Набор содержимого не фиксирован — включаются только нужные части.**
|
||||
|
||||
## Модуль vs компонент
|
||||
|
||||
**Компонент** — один `.tsx` файл. Не имеет своих сегментов, использует сегменты родительского модуля. Живёт в корне или `ui/` сегменте модуля.
|
||||
|
||||
**Модуль** — папка, которая может содержать корневой компонент, сегменты (`hooks/`, `types/`, `styles/`, `ui/`, `parts/` и т.д.) и публичный API (`index.ts`).
|
||||
|
||||
```text
|
||||
auth/
|
||||
├── ui/
|
||||
│ ├── auth-guard.tsx
|
||||
│ └── logout-button.tsx
|
||||
├── parts/
|
||||
│ ├── login-form/
|
||||
│ ├── registration-form/
|
||||
│ └── restore-form/
|
||||
├── hooks/
|
||||
├── stores/
|
||||
├── types/
|
||||
├── auth.tsx # корневой компонент (опционален)
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
## Структура
|
||||
|
||||
Модуль состоит из сегментов. Ни один сегмент не обязателен — модуль может состоять даже из одного `index.ts` с реэкспортом типов.
|
||||
|
||||
```text
|
||||
{module-name}/
|
||||
├── {module-name}.tsx # корневой компонент (опционален)
|
||||
├── ui/ # компоненты модуля (только .tsx)
|
||||
├── parts/ # вложенные модули (со своими сегментами)
|
||||
├── hooks/ # хуки
|
||||
├── stores/ # сторы состояния
|
||||
├── services/ # внешние источники данных
|
||||
├── mappers/ # трансформация данных между форматами
|
||||
├── types/ # типы
|
||||
├── styles/ # стили
|
||||
├── lib/ # утилиты модуля
|
||||
├── config/ # константы
|
||||
└── index.ts # публичный API
|
||||
```
|
||||
|
||||
Подробное описание каждого сегмента — в разделе [Сегменты](./segments.md).
|
||||
|
||||
## Публичный API
|
||||
|
||||
Модуль экспортирует наружу только то, что нужно другим. Всё остальное — внутреннее.
|
||||
|
||||
```ts
|
||||
// business/auth/index.ts
|
||||
export type { User, Session } from './types/user.types'
|
||||
export { useAuth } from './hooks/use-auth.hook'
|
||||
export { AuthGuard } from './ui/auth-guard'
|
||||
```
|
||||
|
||||
Импорт в обход `index.ts` запрещён:
|
||||
|
||||
```ts
|
||||
// Плохо
|
||||
import { validateToken } from '@/business/auth/lib/tokens'
|
||||
|
||||
// Хорошо
|
||||
import { useAuth } from '@/business/auth'
|
||||
```
|
||||
|
||||
## Фабрика
|
||||
|
||||
Если модуль зависит от кода другого бизнес-домена — он экспортирует фабрику. Фабрика декларирует необходимые зависимости и возвращает API модуля. Точка использования (screen, widget, layout) предоставляет зависимости при вызове.
|
||||
|
||||
Модуль без cross-domain зависимостей экспортирует API напрямую. Типы всегда экспортируются напрямую — `import type` не является runtime-зависимостью.
|
||||
|
||||
### Модуль без зависимостей — прямой экспорт:
|
||||
|
||||
```ts
|
||||
// business/auth/index.ts
|
||||
export { useAuth } from './hooks/use-auth'
|
||||
export { useCurrentUser } from './hooks/use-current-user'
|
||||
export type { User, Session } from './types'
|
||||
```
|
||||
|
||||
### Модуль с зависимостями — фабрика:
|
||||
|
||||
```ts
|
||||
// business/chat/types/deps.ts
|
||||
import type { User } from '@/business/auth'
|
||||
|
||||
export interface ChatDeps {
|
||||
useCurrentUser: () => User | null
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
// business/chat/index.ts
|
||||
import type { ChatDeps } from './types/deps'
|
||||
|
||||
export function chatFactory(deps: ChatDeps) {
|
||||
return {
|
||||
useMessages: (roomId: string) => {
|
||||
const user = deps.useCurrentUser()
|
||||
// ...
|
||||
},
|
||||
useSendMessage: (roomId: string) => {
|
||||
const user = deps.useCurrentUser()
|
||||
return (text: string) => { /* ... */ }
|
||||
},
|
||||
useChatRooms: () => {
|
||||
const user = deps.useCurrentUser()
|
||||
// ...
|
||||
},
|
||||
ChatBadge: ({ count }: { count: number }) => { /* ... */ },
|
||||
}
|
||||
}
|
||||
|
||||
export type { Message, ChatRoom } from './types'
|
||||
export type { ChatDeps } from './types/deps'
|
||||
```
|
||||
|
||||
### Использование на странице:
|
||||
|
||||
```tsx
|
||||
// screens/support/support.tsx
|
||||
import { useCurrentUser } from '@/business/auth'
|
||||
import { chatFactory } from '@/business/chat'
|
||||
|
||||
const chat = chatFactory({ useCurrentUser })
|
||||
|
||||
export function SupportScreen() {
|
||||
const { useMessages, useSendMessage, ChatBadge } = chat
|
||||
const messages = useMessages('support')
|
||||
const sendMessage = useSendMessage('support')
|
||||
|
||||
return (
|
||||
<div>
|
||||
<ChatBadge count={messages.length} />
|
||||
{messages.map(m => <MessageBubble key={m.id} {...m} />)}
|
||||
<MessageInput onSend={sendMessage} />
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Жизненный цикл
|
||||
|
||||
Модуль рождается на самом низком уровне использования и поднимается выше только при реальной потребности.
|
||||
|
||||
- Нужен на одной странице → `screens/{name}/parts/`
|
||||
- Появился в 2+ местах → поднимается по природе:
|
||||
- абстрактный UI → `ui/`
|
||||
- блок с данными/логикой → `widgets/`
|
||||
- представление бизнес-домена → `business/{area}/parts/`
|
||||
|
||||
Подъём — обычный рефакторинг в рамках задачи, а не отдельная активность.
|
||||
159
ai/nextjs-style-guide/basics/architecture/reference/segments.md
Normal file
159
ai/nextjs-style-guide/basics/architecture/reference/segments.md
Normal file
@@ -0,0 +1,159 @@
|
||||
---
|
||||
title: Сегменты SLM
|
||||
description: Что такое сегмент модуля в SLM-архитектуре и какие они бывают.
|
||||
---
|
||||
|
||||
# Сегменты SLM
|
||||
|
||||
Что такое сегмент модуля в SLM-архитектуре и какие они бывают.
|
||||
|
||||
## Определение
|
||||
|
||||
**Сегмент — папка внутри модуля, которая группирует файлы по назначению. Набор сегментов не фиксирован — модуль включает только те, которые ему нужны. Команда сама определяет какие сегменты используются в проекте — архитектура даёт рекомендацию.**
|
||||
|
||||
## Обзор
|
||||
|
||||
| Сегмент | Содержимое |
|
||||
|---------|------------|
|
||||
| `ui/` | Вспомогательные компоненты модуля — только `.tsx` файлы |
|
||||
| `parts/` | Вложенные модули со своими сегментами |
|
||||
| `hooks/` | React-хуки |
|
||||
| `stores/` | Сторы состояния |
|
||||
| `services/` | Работа с внешними источниками данных |
|
||||
| `mappers/` | Трансформация данных между форматами |
|
||||
| `types/` | TypeScript-типы и интерфейсы |
|
||||
| `styles/` | Стили |
|
||||
| `lib/` | Утилиты и хелперы модуля |
|
||||
| `config/` | Константы и конфигурация |
|
||||
|
||||
## Сегмент ui/
|
||||
|
||||
Вспомогательные компоненты модуля. Содержит только `.tsx` файлы — без своих сегментов, стилей, типов, хуков и публичного API. Использует сегменты родительского модуля.
|
||||
|
||||
Корневой компонент модуля в `ui/` не размещается. Он лежит в корне модуля: `{module-name}.tsx`.
|
||||
|
||||
```text
|
||||
user/
|
||||
├── ui/
|
||||
│ ├── user-avatar.tsx
|
||||
│ └── user-status.tsx
|
||||
├── types/
|
||||
├── hooks/
|
||||
├── user.tsx
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
Если компоненту нужны собственные сегменты — это уже не `ui/`, а `parts/`.
|
||||
|
||||
## Сегмент parts/
|
||||
|
||||
Вложенные модули со своими сегментами. `parts/` содержит только модули: каждый элемент `parts/` — папка полноценного модуля с собственным публичным API. Отдельные `.tsx`, стили, хуки или произвольные файлы в `parts/` не размещаются.
|
||||
|
||||
```text
|
||||
home/
|
||||
├── parts/
|
||||
│ ├── hero-section/
|
||||
│ │ ├── hero-section.tsx
|
||||
│ │ ├── styles/
|
||||
│ │ ├── parts/
|
||||
│ │ │ └── top-banner/
|
||||
│ │ │ ├── top-banner.tsx
|
||||
│ │ │ └── index.ts
|
||||
│ │ └── index.ts
|
||||
│ └── features-section/
|
||||
│ ├── features-section.tsx
|
||||
│ ├── hooks/
|
||||
│ └── index.ts
|
||||
├── home.screen.tsx
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
Отличие от `ui/`: элемент `parts/` — модульная папка со своими сегментами. Элемент `ui/` — вспомогательный компонент, один `.tsx` файл.
|
||||
|
||||
Вложенность `parts/` инкапсулирует область разработки горизонтально: каждый разработчик работает в своём `parts/`-модуле, не затрагивая чужие. Это снижает конфликты при параллельной разработке.
|
||||
|
||||
Если вложенный модуль обрастает своими `parts/` — это сигнал, что он достаточно самостоятельный для подъёма на уровень выше.
|
||||
|
||||
## Сегмент hooks/
|
||||
|
||||
React-хуки модуля. Инкапсулируют логику, состояние, подписки, побочные эффекты.
|
||||
|
||||
```text
|
||||
hooks/
|
||||
├── use-auth.hook.ts
|
||||
├── use-session.hook.ts
|
||||
└── use-permissions.hook.ts
|
||||
```
|
||||
|
||||
## Сегмент stores/
|
||||
|
||||
Сторы состояния модуля. Конкретная реализация зависит от выбранного стейт-менеджера (Zustand, MobX, Redux и т.д.).
|
||||
|
||||
```text
|
||||
stores/
|
||||
├── auth.store.ts
|
||||
└── session.store.ts
|
||||
```
|
||||
|
||||
## Сегмент services/
|
||||
|
||||
Работа с внешними источниками данных: API-вызовы, запросы, подписки.
|
||||
|
||||
```text
|
||||
services/
|
||||
├── auth.service.ts
|
||||
└── token.service.ts
|
||||
```
|
||||
|
||||
## Сегмент mappers/
|
||||
|
||||
Функции трансформации данных из одного формата в другой: DTO в доменный тип, доменный тип в DTO, доменный тип в ViewModel.
|
||||
|
||||
```text
|
||||
mappers/
|
||||
├── map-user.ts
|
||||
├── map-product.ts
|
||||
└── map-order-to-dto.ts
|
||||
```
|
||||
|
||||
## Сегмент types/
|
||||
|
||||
TypeScript-типы и интерфейсы модуля. Доменные типы, DTO, пропсы компонентов.
|
||||
|
||||
```text
|
||||
types/
|
||||
├── user.type.ts
|
||||
└── session.type.ts
|
||||
```
|
||||
|
||||
## Сегмент styles/
|
||||
|
||||
Стили модуля. Формат зависит от выбранного подхода (CSS Modules, SCSS, CSS-in-JS и т.д.).
|
||||
|
||||
```text
|
||||
styles/
|
||||
├── auth.module.css
|
||||
└── login-form.module.css
|
||||
```
|
||||
|
||||
## Сегмент lib/
|
||||
|
||||
Утилиты и хелперы, специфичные для модуля. Чистые функции без побочных эффектов.
|
||||
|
||||
```text
|
||||
lib/
|
||||
├── validate-email.ts
|
||||
└── format-phone.ts
|
||||
```
|
||||
|
||||
Отличие от `shared/lib/`: здесь лежат утилиты, нужные только этому модулю. Общие утилиты — в `shared/lib/`.
|
||||
|
||||
## Сегмент config/
|
||||
|
||||
Константы и конфигурация модуля: маршруты, лимиты, дефолтные значения.
|
||||
|
||||
```text
|
||||
config/
|
||||
├── routes.ts
|
||||
└── constants.ts
|
||||
```
|
||||
153
ai/nextjs-style-guide/basics/code-style.md
Normal file
153
ai/nextjs-style-guide/basics/code-style.md
Normal file
@@ -0,0 +1,153 @@
|
||||
---
|
||||
title: Стиль кода
|
||||
description: Как оформляется код в проекте.
|
||||
---
|
||||
|
||||
# Стиль кода
|
||||
|
||||
Как оформляется код в проекте.
|
||||
|
||||
## Отступы
|
||||
|
||||
- 2 пробела (не табы).
|
||||
|
||||
## Длина строк
|
||||
|
||||
- Ориентироваться на 100 символов, но превышение допустимо, если строка читается легко.
|
||||
- Переносить выражение на новые строки, когда строка становится плохо читаемой.
|
||||
- Не переносить строку внутри строковых литералов без необходимости.
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
const config = createRequestConfig(
|
||||
endpoint,
|
||||
{
|
||||
headers: {
|
||||
'X-Request-Id': requestId,
|
||||
'X-User-Id': userId,
|
||||
},
|
||||
params: {
|
||||
page,
|
||||
pageSize,
|
||||
sort: 'createdAt',
|
||||
},
|
||||
},
|
||||
timeoutMs,
|
||||
);
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: длинная строка с вложенными структурами плохо читается.
|
||||
const config = createRequestConfig(endpoint, { headers: { 'X-Request-Id': requestId, 'X-User-Id': userId }, params: { page, pageSize, sort: 'createdAt' } }, timeoutMs);
|
||||
```
|
||||
|
||||
## Кавычки
|
||||
|
||||
- В JavaScript/TypeScript использовать одинарные кавычки.
|
||||
- В JSX/TSX для атрибутов использовать двойные кавычки.
|
||||
- Шаблонные строки использовать только при интерполяции или многострочном тексте.
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
const label = 'Сохранить';
|
||||
const title = `Привет, ${name}`;
|
||||
```
|
||||
|
||||
```tsx
|
||||
<input type="text" placeholder="Введите имя" />
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: двойные кавычки в TS и конкатенация вместо шаблонной строки.
|
||||
const label = "Сохранить";
|
||||
const title = 'Привет, ' + name;
|
||||
```
|
||||
|
||||
```tsx
|
||||
// Плохо: одинарные кавычки в JSX-атрибутах.
|
||||
<input type='text' placeholder='Введите имя' />
|
||||
```
|
||||
|
||||
## Точки с запятой и запятые
|
||||
|
||||
- Допускаются упущения точки с запятой, если код остаётся читаемым и однозначным.
|
||||
- В многострочных массивах, объектах и параметрах функции запятая в конце допускается, но не обязательна.
|
||||
|
||||
## Импорты
|
||||
|
||||
- В именованных импортах использовать пробелы внутри фигурных скобок.
|
||||
- Типы импортировать через `import type`.
|
||||
- `default` экспорт избегать, использовать именованные. `default` импорт допустим (например, стили CSS Modules, сторонние библиотеки).
|
||||
- Избегать импорта всего модуля через `*`.
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
import { MyComponent } from 'MyComponent';
|
||||
import type { User } from '../model/types';
|
||||
import styles from './styles/button.module.css';
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: отсутствие пробелов в именованном импорте.
|
||||
import type {User} from '../model/types';
|
||||
// Плохо: default экспорт.
|
||||
export default MyComponent;
|
||||
```
|
||||
|
||||
## Ранние возвраты (early return)
|
||||
|
||||
- Использовать ранние возвраты для упрощения чтения.
|
||||
- Избегать `else` после `return`.
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
const getName = (user?: { name: string }) => {
|
||||
if (!user) {
|
||||
return 'Гость';
|
||||
}
|
||||
|
||||
return user.name;
|
||||
};
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: лишний else после return усложняет чтение.
|
||||
const getName = (user?: { name: string }) => {
|
||||
if (user) {
|
||||
return user.name;
|
||||
} else {
|
||||
return 'Гость';
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## Форматирование объектов и массивов
|
||||
|
||||
- В многострочных объектах каждое свойство на новой строке.
|
||||
- В многострочных массивах каждый элемент на новой строке.
|
||||
- Объекты и массивы можно писать в одну строку, если длина строки не превышает 100 символов.
|
||||
- В однострочных объектах и массивах использовать пробелы после запятых.
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
const roles = ['admin', 'editor', 'viewer'];
|
||||
const options = { id: 1, name: 'User' };
|
||||
|
||||
const config = {
|
||||
url: '/api/users',
|
||||
method: 'GET',
|
||||
params: { page: 1, pageSize: 20 },
|
||||
};
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: нет пробелов после запятых и объект слишком длинный для одной строки.
|
||||
const roles = ['admin','editor','viewer'];
|
||||
const options = { id: 1,name: 'User' };
|
||||
const config = { url: '/api/users', method: 'GET', params: { page: 1, pageSize: 20 } };
|
||||
```
|
||||
134
ai/nextjs-style-guide/basics/documentation.md
Normal file
134
ai/nextjs-style-guide/basics/documentation.md
Normal file
@@ -0,0 +1,134 @@
|
||||
---
|
||||
title: Документирование
|
||||
description: Что и как документировать в коде.
|
||||
---
|
||||
|
||||
# Документирование
|
||||
|
||||
Что и как документировать в коде.
|
||||
|
||||
## Общие правила
|
||||
|
||||
- Документировать публичные функции, компоненты, типы, интерфейсы и enum.
|
||||
- Не документировать очевидное — если название говорит само за себя, комментарий не нужен.
|
||||
- Не документировать параметры, возвращаемые значения и типы пропсов — они видны из сигнатуры.
|
||||
- Описание через пользу и назначение, а не через внутреннюю реализацию.
|
||||
- Описание завершается точкой.
|
||||
|
||||
## Функции
|
||||
|
||||
Для документирования функций используется шаблон. Описание механики опционально —
|
||||
добавляется когда логика нетривиальна.
|
||||
|
||||
**Шаблон**
|
||||
```ts
|
||||
/**
|
||||
* <Что делает функция в 1 строке>.
|
||||
*
|
||||
* <Опционально: описание сложной механики или важных нюансов>.
|
||||
*/
|
||||
```
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
/**
|
||||
* Форматирует цену с символом валюты.
|
||||
*/
|
||||
export const formatPrice = (value: number): string => { ... }
|
||||
|
||||
/**
|
||||
* Рекурсивно собирает дерево категорий из плоского списка.
|
||||
*
|
||||
* Группирует элементы по parentId, начиная с корневых (parentId = null).
|
||||
* Категории без родителя попадают в корень дерева.
|
||||
*/
|
||||
export const buildCategoryTree = (categories: Category[]): CategoryTree[] => { ... }
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: дублирует сигнатуру.
|
||||
/**
|
||||
* @param value - число
|
||||
* @returns строка с ценой
|
||||
*/
|
||||
```
|
||||
|
||||
## Компоненты
|
||||
|
||||
Компонент описывает своё **назначение** и **сценарии применения** — это помогает понять, когда и где его использовать, без необходимости читать реализацию.
|
||||
|
||||
**Шаблон**
|
||||
```ts
|
||||
/**
|
||||
* <Назначение компонента в 1 строке>.
|
||||
*
|
||||
* Используется для:
|
||||
* - <сценарий 1>
|
||||
* - <сценарий 2>
|
||||
* - <сценарий 3>
|
||||
*/
|
||||
```
|
||||
|
||||
**Хорошо**
|
||||
```tsx
|
||||
/**
|
||||
* Контейнер с адаптивной максимальной шириной.
|
||||
*
|
||||
* Используется для:
|
||||
* - обёртки контента страниц с ограничением ширины
|
||||
* - центрирования блоков в лейауте
|
||||
*/
|
||||
export const Container = (props: ContainerProps) => { ... }
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```tsx
|
||||
// Плохо: описывает реализацию, а не назначение.
|
||||
/**
|
||||
* Рендерит div с className и htmlAttr.
|
||||
*/
|
||||
|
||||
// Плохо: нет описания вообще.
|
||||
export const Container = (props: ContainerProps) => { ... }
|
||||
```
|
||||
|
||||
## Типы, интерфейсы, enum
|
||||
|
||||
Документируются назначение сущности и каждое её поле.
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
/**
|
||||
* Фильтры списка задач.
|
||||
*/
|
||||
export enum TodoFilter {
|
||||
/** Все задачи. */
|
||||
ALL = 'all',
|
||||
/** Только активные. */
|
||||
ACTIVE = 'active',
|
||||
/** Только завершённые. */
|
||||
COMPLETED = 'completed',
|
||||
}
|
||||
|
||||
/**
|
||||
* Задача пользователя.
|
||||
*/
|
||||
export interface TodoItem {
|
||||
/** Уникальный идентификатор задачи. */
|
||||
id: string;
|
||||
/** Текст задачи. */
|
||||
text: string;
|
||||
/** Статус выполнения. */
|
||||
completed: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: описывает очевидное.
|
||||
export interface TodoItem {
|
||||
/** id — это id */
|
||||
id: string;
|
||||
}
|
||||
```
|
||||
146
ai/nextjs-style-guide/basics/naming.md
Normal file
146
ai/nextjs-style-guide/basics/naming.md
Normal file
@@ -0,0 +1,146 @@
|
||||
---
|
||||
title: Именование
|
||||
description: Как называть переменные, файлы и прочие сущности в коде.
|
||||
---
|
||||
|
||||
# Именование
|
||||
|
||||
Как называть переменные, файлы и прочие сущности в коде.
|
||||
|
||||
## Базовые правила
|
||||
|
||||
| Что | Рекомендуется |
|
||||
| ---------------- | ---------------------- |
|
||||
| Папки | `kebab-case` |
|
||||
| Файлы | `kebab-case` |
|
||||
| Переменные | `camelCase` |
|
||||
| Константы | `SCREAMING_SNAKE_CASE` |
|
||||
| Классы | `PascalCase` |
|
||||
| React-компоненты | `PascalCase` |
|
||||
| Хуки | `useSomething` |
|
||||
| CSS классы | `camelCase` |
|
||||
| Ключи enum | `SCREAMING_SNAKE_CASE` |
|
||||
|
||||
|
||||
## Именование файлов
|
||||
|
||||
Суффикс обозначает роль или тип файла. Пишется в единственном числе.
|
||||
Формат: `name.<suffix>.ts`.
|
||||
|
||||
**Хуки**
|
||||
- `use-name.hook.ts` — файл хука, функция именуется `useName`
|
||||
|
||||
**Логика**
|
||||
- `.store.ts` — стор
|
||||
- `.service.ts` — сервис
|
||||
|
||||
**Корневые компоненты слоёв**
|
||||
- `.screen.tsx` — корневой компонент screen-модуля: `screens/profile/profile.screen.tsx`, компонент `ProfileScreen`
|
||||
- `.layout.tsx` — корневой компонент layout-модуля: `layouts/main/main.layout.tsx`, компонент `MainLayout`
|
||||
|
||||
Обычные и вложенные модули не получают суффикс слоя: `ui/button/button.tsx`, `screens/profile/parts/activity-feed/activity-feed.tsx`.
|
||||
|
||||
**Типы и контракты**
|
||||
- `.type.ts` — типы и интерфейсы
|
||||
- `.interface.ts` — интерфейсы
|
||||
- `.enum.ts` — enum
|
||||
- `.dto.ts` — внешние DTO
|
||||
- `.schema.ts` — схемы валидации
|
||||
- `.constant.ts` — константы
|
||||
- `.config.ts` — конфигурация
|
||||
|
||||
**Утилиты**
|
||||
- `.util.ts` — утилиты
|
||||
- `.helper.ts` — вспомогательные функции
|
||||
- `.lib.ts` — библиотечный код
|
||||
|
||||
**Тесты**
|
||||
- `.test.ts` — тесты
|
||||
- `.mock.ts` — моки
|
||||
|
||||
**Хорошо**
|
||||
```text
|
||||
business/
|
||||
└── auth-by-email/
|
||||
├── ui/
|
||||
│ └── login-form.tsx
|
||||
├── hooks/
|
||||
│ └── use-auth.hook.ts
|
||||
├── stores/
|
||||
│ └── auth.store.ts
|
||||
├── types/
|
||||
│ └── auth.type.ts
|
||||
├── auth-by-email.tsx
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```text
|
||||
business/
|
||||
└── authByEmail/
|
||||
├── LoginForm.tsx
|
||||
├── useAuth.ts
|
||||
├── authStore.ts
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
## Булевы значения
|
||||
|
||||
- Использовать префиксы `is`, `has`, `can`, `should`.
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
const isReady = true;
|
||||
const hasAccess = false;
|
||||
const canSubmit = true;
|
||||
const shouldRedirect = false;
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: неясное булево значение без префикса.
|
||||
const ready = true;
|
||||
const access = false;
|
||||
const submit = true;
|
||||
```
|
||||
|
||||
## События и обработчики
|
||||
|
||||
- Обработчики начинать с `handle`.
|
||||
- События и колбэки начинать с `on`.
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
const handleSubmit = () => { ... };
|
||||
const onSubmit = () => { ... };
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: неочевидное назначение имени.
|
||||
const submitClick = () => { ... };
|
||||
```
|
||||
|
||||
## Коллекции
|
||||
|
||||
- Для массивов использовать имена во множественном числе.
|
||||
- Для словарей/мап — использовать суффиксы `ById`, `Map`, `Dict`.
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
const users = [];
|
||||
const usersById = {} as Record<string, User>;
|
||||
const userIds = ['u1', 'u2'];
|
||||
const ordersMap = new Map<string, Order>();
|
||||
const featureFlagsDict = { beta: true, legacy: false } as Record<string, boolean>;
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: имя не отражает, что это коллекция.
|
||||
const user = [];
|
||||
// Плохо: словарь назван как массив.
|
||||
const usersMap = [];
|
||||
// Плохо: по имени непонятно, что это словарь.
|
||||
const users = {} as Record<string, User>;
|
||||
```
|
||||
42
ai/nextjs-style-guide/basics/tech-stack.md
Normal file
42
ai/nextjs-style-guide/basics/tech-stack.md
Normal file
@@ -0,0 +1,42 @@
|
||||
---
|
||||
title: Технологии и библиотеки
|
||||
description: Какие библиотеки и инструменты используются в проекте.
|
||||
---
|
||||
|
||||
# Технологии и библиотеки
|
||||
|
||||
Какие библиотеки и инструменты используются в проекте.
|
||||
|
||||
## Что используем
|
||||
|
||||
### Стек
|
||||
- `React` / `TypeScript` — основной стек для UI и приложения.
|
||||
- `Next.js` — для продуктовых сайтов.
|
||||
|
||||
### Архитектура
|
||||
- `SLM Design` — собственная модульная архитектура проекта. Подробнее в разделе [Архитектура](./architecture/index.md).
|
||||
|
||||
### UI компоненты
|
||||
- `Mantine UI` — базовые UI-компоненты.
|
||||
|
||||
### Работа с данными (API)
|
||||
- `@gromlab/api-codegen` — генерация API‑клиентов и типов.
|
||||
- `SWR` — получение, кеширование, ревалидация, дедубликация.
|
||||
- `SWR (useSWRSubscription)` — сокеты, реалтайм подписки.
|
||||
|
||||
### Store
|
||||
- `Zustand` — глобальное состояние.
|
||||
|
||||
### Локализация
|
||||
- `i18next (i18n)` — локализация всех пользовательских текстов.
|
||||
|
||||
### Тестирование
|
||||
- `Vitest` — тестирование.
|
||||
|
||||
### Стили
|
||||
- `PostCSS Modules` — изоляция стилей.
|
||||
- `Mobile First` — подход к адаптивной верстке.
|
||||
- `clsx` — конкатенация CSS‑классов.
|
||||
|
||||
### Генерация
|
||||
- `@gromlab/create` — шаблонизатор для создания слоёв и других файлов из шаблонов.
|
||||
57
ai/nextjs-style-guide/basics/typing.md
Normal file
57
ai/nextjs-style-guide/basics/typing.md
Normal file
@@ -0,0 +1,57 @@
|
||||
---
|
||||
title: Типизация
|
||||
description: Как типизируется код в проекте.
|
||||
---
|
||||
|
||||
# Типизация
|
||||
|
||||
Как типизируется код в проекте.
|
||||
|
||||
## Общие правила
|
||||
|
||||
- Указывать типы для параметров компонентов, возвращаемых значений и параметров функций.
|
||||
- Предпочитать `type` для описания сущностей и `interface` для расширяемых контрактов.
|
||||
- Избегать `any` и `unknown` без необходимости.
|
||||
- Не использовать `ts-ignore`, кроме крайних случаев с явным комментарием причины.
|
||||
|
||||
## Функции
|
||||
|
||||
- Для публичных функций указывать возвращаемый тип.
|
||||
- Не полагаться на неявный вывод для важных API.
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
export const formatPrice = (value: number): string => {
|
||||
return `${value} ₽`;
|
||||
};
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: нет явного возвращаемого типа.
|
||||
export const formatPrice = (value: number) => {
|
||||
return `${value} ₽`;
|
||||
};
|
||||
```
|
||||
|
||||
## Работа с any/unknown
|
||||
|
||||
- `any` использовать только для временных заглушек.
|
||||
- `unknown` сужать через проверки перед использованием.
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
const parse = (value: unknown): string => {
|
||||
if (typeof value === 'string') {
|
||||
return value;
|
||||
}
|
||||
|
||||
return '';
|
||||
};
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: any отключает проверку типов.
|
||||
const parse = (value: any) => value;
|
||||
```
|
||||
51
ai/nextjs-style-guide/creating-project/from-template.md
Normal file
51
ai/nextjs-style-guide/creating-project/from-template.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: Создание проекта из шаблона
|
||||
description: Создание нового проекта на основе готового шаблона.
|
||||
keywords: [создать проект из шаблона, шаблон, template, tiged, degit, клонировать шаблон, эталонный шаблон, быстрый старт, scaffold, новый проект]
|
||||
---
|
||||
|
||||
# Создание проекта из шаблона
|
||||
|
||||
Создание нового проекта на основе готового шаблона.
|
||||
|
||||
## Что внутри
|
||||
|
||||
Шаблон — готовый скелет проекта с применёнными правилами стайлгайда:
|
||||
|
||||
- **Стек:** Next.js (App Router), TypeScript, React.
|
||||
- **Архитектура:** структура папок по SLM, алиасы импортов.
|
||||
- **Качество кода:** Biome (линтер и форматер), настройки VS Code.
|
||||
- **Стили:** PostCSS Modules с плагинами, токены, медиа-брейкпоинты.
|
||||
- **Ассеты:** генерация SVG-спрайтов.
|
||||
- **Кодогенерация:** шаблоны для страниц, компонентов, хуков, сторов.
|
||||
в
|
||||
## Установка
|
||||
|
||||
1. Склонировать шаблон в родительском каталоге будущего проекта:
|
||||
|
||||
```bash
|
||||
npx tiged git@gromlab.ru:templates/nextjs.git my-app
|
||||
```
|
||||
|
||||
`tiged` копирует снимок репозитория без истории git. Имя каталога (`my-app`) заменяется на нужное.
|
||||
|
||||
2. Установить зависимости:
|
||||
|
||||
```bash
|
||||
cd my-app
|
||||
npm install
|
||||
```
|
||||
|
||||
3. Проверить сборку:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
Сборка должна завершиться без ошибок.
|
||||
|
||||
## Правила
|
||||
|
||||
- **Шаблон — источник истины.** Не добавлять, не удалять и не переименовывать файлы шаблона «для приведения к канону»: шаблон уже канонический. Любое несоответствие — баг шаблона, а не проекта.
|
||||
- **Менеджер пакетов — npm.** Отклонение (pnpm, yarn, bun) — только по явному решению с пониманием, что стайлгайд этого не предусматривает.
|
||||
- **Не инициализировать git заново** автоматически. `tiged` намеренно не создаёт `.git/` — решение о репозитории принимает разработчик.
|
||||
90
ai/nextjs-style-guide/creating-project/manual.md
Normal file
90
ai/nextjs-style-guide/creating-project/manual.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
title: Создание проекта вручную
|
||||
description: Поэтапное создание нового проекта без использования шаблона.
|
||||
keywords: [создать проект, новый проект, с нуля, init, initialize, scaffold, create-next-app, начать проект, поднять проект, эталонный проект, ручная установка]
|
||||
---
|
||||
|
||||
# Создание проекта вручную
|
||||
|
||||
Поэтапное создание нового проекта без использования шаблона.
|
||||
|
||||
## Состав эталонного проекта
|
||||
|
||||
| Компонент | Роль | Раздел |
|
||||
|-----------|------|--------|
|
||||
| Next.js | Фреймворк (роутинг, сборка, SSR) | [Next.js](./nextjs.md) |
|
||||
| Алиасы | Импорты по слоям SLM | [Алиасы](../applied/aliases.md) |
|
||||
| Biome | Линтер и форматтер (замена ESLint + Prettier) | [Biome](../applied/biome.md) |
|
||||
| Стили | Глобальные токены и breakpoints | [Стили](../applied/styles/styles-setup.md) |
|
||||
| PostCSS | CSS-процессор для custom-media и вложенности | [PostCSS](../applied/postcss.md) |
|
||||
| SVG-спрайты | Иконки через `<SvgSprite/>`, управление цветом | [SVG-спрайты](../applied/svg-sprites/svg-sprites-setup.md) |
|
||||
| VS Code | Настройки редактора и расширения | [VS Code](../applied/vscode.md) |
|
||||
| Шаблоны генерации | `.templates/` для `@gromlab/create` | [Шаблоны генерации](../applied/templates/templates-setup.md) |
|
||||
|
||||
Убрать компонент из состава — значит согласованно отказаться от части стайлгайда. Частичные проекты возможны (только Next.js, Next.js + стили и т.п.), но не являются эталоном.
|
||||
|
||||
## Канон раскладки
|
||||
|
||||
В `src/` допустимы только слои SLM: `app/`, `layouts/`, `screens/`, `widgets/`, `business/`, `infrastructure/`, `ui/`, `shared/`. Любая другая папка в `src/` — нарушение канона ([Структура проекта](../applied/project-structure.md), [Архитектура](../basics/architecture/index.md)).
|
||||
|
||||
В частности: `src/app/` содержит только файлы роутинга Next.js и инициализации, без каталогов `styles/`, `assets/`, `components/`.
|
||||
|
||||
## Порядок установки
|
||||
|
||||
Подсистемы ставятся в фиксированном порядке — он отражает зависимости между шагами.
|
||||
|
||||
### 1. Next.js
|
||||
|
||||
Скелет фреймворка — обязательный первый шаг, остальное опирается на него.
|
||||
|
||||
См. [Next.js](./nextjs.md). После выполнения проверки этого раздела `npm run build` должен проходить.
|
||||
|
||||
### 2. Алиасы
|
||||
|
||||
Заменить дефолтный `"@/*"` в `tsconfig.json` на канонический список из восьми слой-префиксов.
|
||||
|
||||
См. [Алиасы](../applied/aliases.md).
|
||||
|
||||
### 3. Biome
|
||||
|
||||
Линтер и форматтер. Подключается **до** написания кода, иначе в проекте копятся несогласованные правки.
|
||||
|
||||
См. [Biome](../applied/biome.md).
|
||||
|
||||
### 4. Стили (базовая инфраструктура)
|
||||
|
||||
Файлы `variables.css`, `media.css`, `global.css` в `src/shared/styles/` и подключение `global.css` в `src/app/layout.tsx`. CSS-процессор на этом шаге не ставится.
|
||||
|
||||
См. [Стили](../applied/styles/styles-setup.md).
|
||||
|
||||
### 5. PostCSS
|
||||
|
||||
CSS-процессор поверх базовых стилей: `@custom-media`, вложенность, autoprefixer. Ставится **только после шага 4** — опирается на `src/shared/styles/media.css`.
|
||||
|
||||
См. [PostCSS](../applied/postcss.md).
|
||||
|
||||
### 6. SVG-спрайты
|
||||
|
||||
Пакет `@gromlab/svg-sprites`, генерация спрайт-файла и React-компонента `<SvgSprite/>`.
|
||||
|
||||
См. [SVG-спрайты](../applied/svg-sprites/svg-sprites-setup.md).
|
||||
|
||||
### 7. VS Code
|
||||
|
||||
Расширения и настройки редактора. Опирается на установленный Biome (форматирование при сохранении) и PostCSS (ассоциация `*.css`).
|
||||
|
||||
См. [VS Code](../applied/vscode.md).
|
||||
|
||||
### 8. Шаблоны генерации
|
||||
|
||||
Папка `.templates/` для генератора модулей `@gromlab/create`.
|
||||
|
||||
См. [Шаблоны генерации](../applied/templates/templates-setup.md).
|
||||
|
||||
## Правила
|
||||
|
||||
- **Порядок шагов фиксирован.** Перестановка ломает зависимости (PostCSS требует базовых стилей, VS Code — установленного Biome).
|
||||
- **Между шагами обязательна проверка** из соответствующего раздела. Не переходить дальше, пока чеклист текущего шага не пройден.
|
||||
- **Слои `src/`** (`layouts/`, `screens/`, `widgets/`, `business/`, `infrastructure/`, `ui/`) не создавать авансом. Появляются по мере первого модуля. Исключения — `src/app/` (создаётся `create-next-app`), `src/shared/styles/` (шаг 1) и `src/shared/sprites/icons/` (шаг 6).
|
||||
- **Посторонние каталоги в `src/`** (`assets/`, `utils/`, `lib/`, `components/` и т.п.) — запрещены.
|
||||
- **Подмножество шагов допустимо.** Можно ставить только Next.js и часть инструментов; полный набор — это эталон, а не обязательство.
|
||||
112
ai/nextjs-style-guide/creating-project/nextjs.md
Normal file
112
ai/nextjs-style-guide/creating-project/nextjs.md
Normal file
@@ -0,0 +1,112 @@
|
||||
---
|
||||
title: Чистая установка Next.js
|
||||
description: "Установка Next.js без лишнего шаблона — голый каркас под дальнейшую сборку."
|
||||
keywords: [next.js, create-next-app, npx, установка, инициализация, фреймворк, скаффолдинг, app router, typescript]
|
||||
---
|
||||
|
||||
# Чистая установка Next.js
|
||||
|
||||
Установка Next.js без лишнего шаблона — голый каркас под дальнейшую сборку.
|
||||
|
||||
## Требования
|
||||
|
||||
- Node.js 18.18+ (рекомендуется LTS 20+).
|
||||
- npm 10+.
|
||||
- Рабочая папка пуста, либо для установки выбрана подпапка (`create-next-app@16+` отказывается ставиться в непустую директорию).
|
||||
|
||||
## Установка
|
||||
|
||||
### 1. Инициализация через `create-next-app`
|
||||
|
||||
Флаги зафиксированы и не согласовываются — это канон стайлгайда:
|
||||
|
||||
```bash
|
||||
npx create-next-app@latest my-app \
|
||||
--typescript \
|
||||
--app \
|
||||
--src-dir \
|
||||
--import-alias "@/*" \
|
||||
--no-eslint \
|
||||
--no-tailwind \
|
||||
--use-npm
|
||||
```
|
||||
|
||||
| Флаг | Значение | Почему так |
|
||||
|------|----------|------------|
|
||||
| `--typescript` | TS включён | Стайлгайд требует TypeScript ([Типизация](../basics/typing.md)) |
|
||||
| `--app` | App Router | Pages Router не используется |
|
||||
| `--src-dir` | Код в `src/` | Архитектура SLM требует `src/` ([Структура проекта](../applied/project-structure.md)) |
|
||||
| `--import-alias "@/*"` | Placeholder | Требуется флагом; после установки `paths` полностью переписывается на слой-префиксы (см. [Алиасы](../applied/aliases.md)) |
|
||||
| `--no-eslint` | ESLint не ставится | Линтер и форматтер — Biome ([Biome](../applied/biome.md)) |
|
||||
| `--no-tailwind` | Tailwind не ставится | Стилизация — PostCSS Modules ([Стили](../applied/styles/styles-usage.md)) |
|
||||
| `--use-npm` | Пакетный менеджер — npm | Единый инструмент в проектах |
|
||||
|
||||
### 2. Очистить дефолтный шаблон
|
||||
|
||||
`create-next-app` генерирует демо-страницу со стилями и ассетами, а Next.js 16+ дополнительно кладёт в корень собственные `AGENTS.md` и `CLAUDE.md` — всё это удаляется.
|
||||
|
||||
```bash
|
||||
rm src/app/page.module.css
|
||||
rm src/app/globals.css
|
||||
rm public/next.svg public/vercel.svg public/file.svg public/globe.svg public/window.svg
|
||||
rm -f AGENTS.md CLAUDE.md
|
||||
```
|
||||
|
||||
Заменить `src/app/page.tsx` на минимальный:
|
||||
|
||||
```tsx
|
||||
// src/app/page.tsx
|
||||
export default function HomePage() {
|
||||
return <h1>Home</h1>
|
||||
}
|
||||
```
|
||||
|
||||
Очистить `src/app/layout.tsx` от импорта шрифтов и `globals.css`:
|
||||
|
||||
```tsx
|
||||
// src/app/layout.tsx
|
||||
import type { Metadata } from 'next'
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: 'App',
|
||||
description: '',
|
||||
}
|
||||
|
||||
export default function RootLayout({ children }: { children: React.ReactNode }) {
|
||||
return (
|
||||
<html lang="ru">
|
||||
<body>{children}</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Создать папку `src/shared/styles/`
|
||||
|
||||
Глобальные стили в SLM-архитектуре живут в слое `shared`, а не в `src/app/` ([Структура проекта](../applied/project-structure.md)).
|
||||
|
||||
```bash
|
||||
mkdir -p src/shared/styles
|
||||
```
|
||||
|
||||
Остальные слои (`layouts/`, `screens/`, `widgets/`, `business/`, `infrastructure/`, `ui/`) заводятся при появлении первого модуля в них. `src/shared/styles/` — единственный подкаталог `shared/`, который заводится сразу: без него не настроить стили на следующих шагах.
|
||||
|
||||
## Правила
|
||||
|
||||
- **Конфликт с непустой директорией** — не удалять файлы пользователя автоматически. Ставить в подпапку или временно перенести посторонние файлы.
|
||||
- **Отклонение от канонических флагов** (pnpm, Tailwind, ESLint и т.п.) — только осознанное, с пониманием, что стайлгайд этого не предусматривает.
|
||||
- **Слои `src/`** не создавать авансом — появляются при первом модуле. Алиасы прописываются сразу на все восемь слоёв (см. [Алиасы](../applied/aliases.md)).
|
||||
- **`AGENTS.md` от Next.js** удаляется в шаге 2. Повторно не создаётся.
|
||||
- **Biome, стили, PostCSS, SVG-спрайты, VS Code** — отдельные шаги установки, не в этом разделе.
|
||||
|
||||
## Проверка установки
|
||||
|
||||
- В корне проекта: `next.config.ts`, `tsconfig.json`, `package.json`.
|
||||
- В `package.json`: Next.js установлен, нет `eslint`, `tailwindcss`.
|
||||
- В `src/app/` присутствуют минимальные `page.tsx` и `layout.tsx`. `globals.css`, `page.module.css` отсутствуют. Каталогов `styles/`, `assets/`, `providers/`, `components/` в `src/app/` нет.
|
||||
- Папка `src/shared/styles/` создана (пустая).
|
||||
- В `src/` из слоёв SLM присутствуют только `app/` и `shared/` (с `styles/`). Посторонних каталогов нет.
|
||||
- В `public/` удалены `next.svg`, `vercel.svg`, `file.svg`, `globe.svg`, `window.svg`.
|
||||
- В корне проекта нет `AGENTS.md` и `CLAUDE.md` от Next.js.
|
||||
- `npm run build` завершается успешно.
|
||||
- Пакетный менеджер — npm (нет `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`).
|
||||
60
ai/nextjs-style-guide/data/index.md
Normal file
60
ai/nextjs-style-guide/data/index.md
Normal file
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Источники данных
|
||||
description: Какие источники данных используются в проекте и как с ними работать.
|
||||
keywords: [данные, api, rest, realtime, клиент, swr, infrastructure, введение, карта раздела]
|
||||
---
|
||||
|
||||
# Источники данных
|
||||
|
||||
Какие источники данных используются в проекте и как с ними работать.
|
||||
|
||||
## Принципы раздела
|
||||
|
||||
- **Клиент — в `infrastructure/`.** Каждый внешний сервис — отдельный модуль слоя `infrastructure/{service-name}/`.
|
||||
- **Прямой `fetch` запрещён.** Запросы идут только через клиент модуля. Исключения — точечные и обоснованные.
|
||||
- **Источник данных диктует канал.** REST, realtime и т.п. — независимые подразделы, у каждого своя модель клиента и своё потребление.
|
||||
- **Серверные и клиентские компоненты потребляют по-разному.** Server Components — прямой `await` метода клиента, клиентские — через готовые GET-хуки REST-клиента (`useGetUserList`, `useGetPostDetail` и т.п.). SWR инкапсулирован в хуке, компонент про него не знает.
|
||||
|
||||
## Карта раздела
|
||||
|
||||
### REST
|
||||
|
||||
Канал «запрос-ответ» по HTTP. Покрывает большинство API.
|
||||
|
||||
- [REST](./rest/index.md) — обзор раздела: создание клиента и использование.
|
||||
- **Создание клиента** — как оформляется REST API в проекте:
|
||||
- [Обзор](./rest/clients/index.md) — когда нужен клиент и как выбрать подход.
|
||||
- [Автогенерация из OpenAPI](./rest/clients/auto.md) — для API с OpenAPI-спецификацией, через `@gromlab/api-codegen`.
|
||||
- [Ручное создание](./rest/clients/manual.md) — для API без схемы, клиент пишется и поддерживается руками.
|
||||
- [GET-хуки REST-клиента](./rest/clients/hooks.md) — прозрачные SWR-обёртки над GET-методами клиента.
|
||||
- **Использование** — как получать данные через готовый клиент:
|
||||
- [Стратегии получения данных](./rest/strategies/index.md) — как выбрать способ получения данных под ситуацию.
|
||||
- [Серверный await](./rest/strategies/server-await.md) — прямой `await` метода клиента в Server Components.
|
||||
- [Параллельные серверные запросы](./rest/strategies/parallel-server-requests.md) — запуск независимых серверных запросов без waterfall.
|
||||
- [Передача промиса ниже](./rest/strategies/pass-promise-down.md) — серверный стриминг через промис и `Suspense`.
|
||||
- [Начальные данные для клиентских хуков](./rest/strategies/client-hooks-initial-data.md) — серверный промис в `SWRConfig fallback`.
|
||||
- [Клиентский GET-хук](./rest/strategies/client-get-hook.md) — получение данных в Client Components через готовый GET-хук.
|
||||
- [Business-композиция](./rest/strategies/business-composition.md) — доменная интерпретация и композиция REST-данных.
|
||||
|
||||
### Realtime
|
||||
|
||||
Канал push-данных: WebSocket, SSE, событийные шины. Транспорт не зашит в правила — важна абстракция «подписка».
|
||||
|
||||
- [Realtime](./realtime.md) — клиент realtime в `infrastructure/`, потребление через `useSWRSubscription` или прямые подписки.
|
||||
|
||||
## Что даёт раздел
|
||||
|
||||
После прочтения раздела понятно:
|
||||
|
||||
- Где живёт код работы с API и почему именно там.
|
||||
- Когда генерировать клиент автоматически, а когда писать вручную, и как структурирован каждый из вариантов.
|
||||
- Какие GET-хуки относятся к REST-клиенту и почему они живут в `infrastructure/{service-name}/hooks/`.
|
||||
- Как выбрать стратегию получения REST-данных под конкретную ситуацию.
|
||||
- Как подключать realtime-источники в общую модель работы с данными.
|
||||
- Какие правила обязательны и какие отклонения допустимы.
|
||||
|
||||
## Что не входит в раздел
|
||||
|
||||
- **Глобальное состояние UI** — Stores, формы, фичефлаги. Это [Stores](../applied/stores.md).
|
||||
- **Доменная логика** — как данные превращаются в сценарии бизнеса. Это слой `business/` в [Архитектуре](../basics/architecture/index.md).
|
||||
- **Хуки общего назначения** — переиспользуемые хуки UI, не привязанные к конкретному API. Отдельный прикладной раздел для них пока не ведётся.
|
||||
79
ai/nextjs-style-guide/data/realtime.md
Normal file
79
ai/nextjs-style-guide/data/realtime.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
title: Realtime
|
||||
description: "Работа с push-данными от сервера: подписки и события."
|
||||
keywords: [realtime, websocket, sse, подписка, swr subscription, useSWRSubscription, push, события]
|
||||
---
|
||||
|
||||
# Realtime
|
||||
|
||||
Работа с push-данными от сервера: подписки и события.
|
||||
|
||||
## Принципы
|
||||
|
||||
- **Клиент realtime — в `infrastructure/`** отдельным модулем по имени канала. То же правило, что и для REST: никаких прямых соединений в коде приложения.
|
||||
- **Подписка — единица потребления.** Клиент даёт функцию `subscribe(topic, handler) → unsubscribe`. Внутри — конкретный транспорт.
|
||||
- **Использование на клиенте — два сценария:**
|
||||
- **`useSWRSubscription`** — для данных, которые показываются в UI и должны кешироваться/синхронизироваться с REST.
|
||||
- **Прямая подписка** — для побочных эффектов (тосты, нотификации, аналитика), не привязанных к рендеру.
|
||||
|
||||
## Размещение клиента
|
||||
|
||||
```text
|
||||
src/infrastructure/
|
||||
└── {channel-name}/
|
||||
├── connection.ts # установление соединения, реконнект
|
||||
├── subscribe.ts # subscribe(topic, handler) → unsubscribe
|
||||
├── types.ts
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
## Использование через SWR
|
||||
|
||||
```tsx
|
||||
'use client'
|
||||
|
||||
import useSWRSubscription from 'swr/subscription'
|
||||
import { subscribe } from 'infrastructure/notifications'
|
||||
|
||||
export function NotificationCounter() {
|
||||
const { data: count } = useSWRSubscription(
|
||||
['notifications', 'count'],
|
||||
(key, { next }) =>
|
||||
subscribe('notifications.count', (value: number) => next(null, value)),
|
||||
)
|
||||
|
||||
return <span>{count ?? 0}</span>
|
||||
}
|
||||
```
|
||||
|
||||
Плюсы: кеш и дедупликация подписки между несколькими местами рендера; единая модель данных с REST.
|
||||
|
||||
## Прямая подписка
|
||||
|
||||
Для побочных эффектов, которые не влияют на состояние UI напрямую:
|
||||
|
||||
```tsx
|
||||
'use client'
|
||||
|
||||
import { useEffect } from 'react'
|
||||
import { subscribe } from 'infrastructure/notifications'
|
||||
import { showToast } from 'ui/toast'
|
||||
|
||||
export function NotificationsToaster() {
|
||||
useEffect(() => {
|
||||
return subscribe('notifications.new', (notification) => {
|
||||
showToast(notification.message)
|
||||
})
|
||||
}, [])
|
||||
|
||||
return null
|
||||
}
|
||||
```
|
||||
|
||||
Возврат `unsubscribe` из `useEffect` обязателен — иначе утечка подписки.
|
||||
|
||||
## Запрет прямых соединений
|
||||
|
||||
Создавать `new WebSocket(...)`, `new EventSource(...)` или подписываться на событийные шины напрямую в коде приложения — запрещено. Все соединения проходят через клиент в `infrastructure/`.
|
||||
|
||||
Исключения — точечные и обоснованные (например, диагностический скрипт), помечаются комментарием.
|
||||
193
ai/nextjs-style-guide/data/rest/clients/auto.md
Normal file
193
ai/nextjs-style-guide/data/rest/clients/auto.md
Normal file
@@ -0,0 +1,193 @@
|
||||
---
|
||||
title: Автогенерация из OpenAPI
|
||||
description: Генерация REST-клиента из OpenAPI-спецификации через @gromlab/api-codegen.
|
||||
keywords: [rest, openapi, api-codegen, автогенерация, generated, npx]
|
||||
---
|
||||
|
||||
# Автогенерация из OpenAPI
|
||||
|
||||
Автогенерация используется, когда у API есть актуальная OpenAPI-спецификация. Генератор создаёт TypeScript-клиент, типы и методы API, а разработчик вручную добавляет настройку клиента и GET-хуки.
|
||||
|
||||
## Пример API
|
||||
|
||||
В примерах используется Swagger Petstore:
|
||||
|
||||
```text
|
||||
https://petstore3.swagger.io/api/v3/openapi.json
|
||||
```
|
||||
|
||||
Имена модуля:
|
||||
|
||||
```text
|
||||
src/infrastructure/pet-store-api/
|
||||
petStoreApi
|
||||
pet-store-api.generated.ts
|
||||
```
|
||||
|
||||
## Скрипт генерации
|
||||
|
||||
`@gromlab/api-codegen` не устанавливается в `devDependencies`. Используем `npx @gromlab/api-codegen@latest`, чтобы запускать свежую версию.
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"codegen:pet-store-api": "npx @gromlab/api-codegen@latest -i https://petstore3.swagger.io/api/v3/openapi.json -o src/infrastructure/pet-store-api/generated -n pet-store-api.generated"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Параметры:
|
||||
|
||||
- `-i` — путь к OpenAPI-спецификации: URL или локальный файл.
|
||||
- `-o` — директория для сгенерированного файла.
|
||||
- `-n` — имя сгенерированного файла без `.ts`.
|
||||
|
||||
Ключ `--swr` не используется. GET-хуки REST-клиента пишутся вручную, чтобы сохранить проектный контракт: один GET-хук = один GET-метод, без бизнес-логики и композиции.
|
||||
|
||||
## Генерация
|
||||
|
||||
```bash
|
||||
npm run codegen:pet-store-api
|
||||
```
|
||||
|
||||
Ожидаемый результат:
|
||||
|
||||
```text
|
||||
src/infrastructure/pet-store-api/generated/
|
||||
└── pet-store-api.generated.ts
|
||||
```
|
||||
|
||||
Сгенерированный файл не правится руками и коммитится в репозиторий.
|
||||
|
||||
## Проверка методов
|
||||
|
||||
После генерации откройте `generated/pet-store-api.generated.ts` и проверьте фактические имена методов.
|
||||
|
||||
Для Petstore нужны GET-операции вида:
|
||||
|
||||
```ts
|
||||
petStoreApi.pet.findPetsByStatus(...)
|
||||
petStoreApi.pet.getPetById(...)
|
||||
```
|
||||
|
||||
Точные сигнатуры зависят от OpenAPI-схемы и версии генератора. В рабочих задачах всегда сверяйтесь с generated-файлом.
|
||||
|
||||
## `client.ts`
|
||||
|
||||
Сгенерированный код не должен напрямую использоваться из приложения. Сначала создаётся настроенный инстанс клиента.
|
||||
|
||||
```ts
|
||||
// src/infrastructure/pet-store-api/client.ts
|
||||
import { Api, HttpClient } from './generated/pet-store-api.generated'
|
||||
|
||||
const httpClient = new HttpClient({
|
||||
baseUrl: 'https://petstore3.swagger.io/api/v3',
|
||||
baseApiParams: {
|
||||
secure: false,
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
},
|
||||
},
|
||||
})
|
||||
|
||||
export const petStoreApi = new Api(httpClient)
|
||||
```
|
||||
|
||||
В реальном проекте вместо строки `baseUrl` обычно берётся из env-переменной, нормализуется в `client.ts` и передаётся в `HttpClient` через конфиг.
|
||||
|
||||
`client.ts` не содержит расширения типов, `declare module` и `Extended`-типы. Он только настраивает транспорт и экспортирует инстанс клиента.
|
||||
|
||||
## Расширение сгенерированных типов
|
||||
|
||||
Сгенерированный файл не правится руками. Если OpenAPI-спецификация неполная или генератор дал слишком общий тип (`object`, `unknown`, отсутствующее поле), расширения живут в `types/`.
|
||||
|
||||
```text
|
||||
src/infrastructure/biocad-less-api/
|
||||
├── generated/
|
||||
│ └── biocad-less-api.generated.ts
|
||||
├── types/
|
||||
│ ├── term.ts
|
||||
│ └── index.ts
|
||||
├── client.ts
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
Пример расширения generated-типа:
|
||||
|
||||
```ts
|
||||
// src/infrastructure/biocad-less-api/types/term.ts
|
||||
import type { TermRecordItem } from '../generated/biocad-less-api.generated'
|
||||
|
||||
declare module '../generated/biocad-less-api.generated' {
|
||||
interface TermRecordItem {
|
||||
media?: {
|
||||
file?: string
|
||||
title?: string
|
||||
url?: string
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export type TermRecordItemExtended = Omit<
|
||||
TermRecordItem,
|
||||
'categories' | 'tags' | 'fields'
|
||||
> & {
|
||||
categories?: Array<{
|
||||
_id?: string
|
||||
id?: string
|
||||
slug?: string
|
||||
name?: string
|
||||
}>
|
||||
tags?: Array<{
|
||||
_id?: string
|
||||
id?: string
|
||||
slug?: string
|
||||
name?: string
|
||||
}>
|
||||
fields?: Record<string, unknown>
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
// src/infrastructure/biocad-less-api/types/index.ts
|
||||
export type { TermRecordItemExtended } from './term'
|
||||
```
|
||||
|
||||
`declare module` используется для добавления отсутствующих полей в generated-интерфейс. `Extended`-тип используется, когда нужно переопределить неточные поля, не трогая generated-файл.
|
||||
|
||||
## Публичный API
|
||||
|
||||
```ts
|
||||
// src/infrastructure/pet-store-api/index.ts
|
||||
export { petStoreApi } from './client'
|
||||
export type { Pet } from './generated/pet-store-api.generated'
|
||||
export * from './hooks'
|
||||
```
|
||||
|
||||
Наружу импортируют только из `infrastructure/pet-store-api`, не из `generated/`.
|
||||
|
||||
Если у модуля есть расширенные типы, они тоже реэкспортируются через `index.ts`:
|
||||
|
||||
```ts
|
||||
// src/infrastructure/biocad-less-api/index.ts
|
||||
export type { TermRecordItemExtended } from './types'
|
||||
```
|
||||
|
||||
## Регенерация
|
||||
|
||||
При изменении OpenAPI-схемы:
|
||||
|
||||
```bash
|
||||
npm run codegen:pet-store-api
|
||||
```
|
||||
|
||||
Что меняется:
|
||||
|
||||
- `generated/pet-store-api.generated.ts` — перезаписывается генератором.
|
||||
- `client.ts`, `hooks/`, `types/`, `index.ts` — не трогаются автоматически.
|
||||
|
||||
Если после регенерации поменялись сигнатуры методов или типы, это исправляется в ручном коде модуля.
|
||||
|
||||
## Следующий шаг
|
||||
|
||||
После генерации и настройки `client.ts` проверьте серверный вызов метода клиента или добавьте [GET-хук REST-клиента](./hooks.md) для Client Components.
|
||||
206
ai/nextjs-style-guide/data/rest/clients/hooks.md
Normal file
206
ai/nextjs-style-guide/data/rest/clients/hooks.md
Normal file
@@ -0,0 +1,206 @@
|
||||
---
|
||||
title: GET-хуки REST-клиента
|
||||
description: Прозрачные SWR-обёртки над GET-методами REST-клиента.
|
||||
keywords: [rest, swr, get-хуки, client components, infrastructure]
|
||||
---
|
||||
|
||||
# GET-хуки REST-клиента
|
||||
|
||||
GET-хуки REST-клиента — прозрачные SWR-обёртки над GET-методами API-клиента. Они нужны, чтобы Client Components получали данные с кешированием, дедупликацией и ревалидацией, не работая с `useSWR` напрямую.
|
||||
|
||||
## Где лежат
|
||||
|
||||
GET-хуки принадлежат REST-клиенту конкретного сервиса и живут рядом с ним:
|
||||
|
||||
```text
|
||||
src/infrastructure/
|
||||
└── pet-store-api/
|
||||
├── client.ts
|
||||
├── generated/
|
||||
├── hooks/
|
||||
│ ├── use-get-pet-list.hook.ts
|
||||
│ ├── use-get-pet-detail.hook.ts
|
||||
│ └── index.ts
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
## Контракт
|
||||
|
||||
- Один GET-хук = один GET-метод клиента.
|
||||
- Имя GET-хука начинается с `useGet`: `useGetPetList`, `useGetPetDetail`.
|
||||
- Имя файла начинается с `use-get`: `use-get-pet-list.hook.ts`.
|
||||
- Хук принимает только параметры GET-метода и `config?: SWRConfiguration`.
|
||||
- Что передали хуку, то он передаёт в GET-метод.
|
||||
- Внутри только SWR-механика: key, fetcher, `useSWR`, `config`.
|
||||
- Хук возвращает тип ответа API: generated-тип или DTO из `types/`.
|
||||
- Хук не объединяет несколько запросов.
|
||||
- Хук не маппит DTO в доменную модель.
|
||||
- Хук не вычисляет бизнес-флаги: `isAuth`, `canEdit`, `hasAccess`, `hasPets`.
|
||||
- Хук не вызывает тосты, модалки, редиректы и не пишет UI-состояние.
|
||||
|
||||
## Пример списка
|
||||
|
||||
```ts
|
||||
// src/infrastructure/pet-store-api/hooks/use-get-pet-list.hook.ts
|
||||
import useSWR from 'swr'
|
||||
import type { SWRConfiguration } from 'swr'
|
||||
import { petStoreApi } from '../client'
|
||||
import type { Pet } from '../generated/pet-store-api.generated'
|
||||
|
||||
export type PetStatus = 'available' | 'pending' | 'sold'
|
||||
|
||||
export const getPetListKey = (status: PetStatus) =>
|
||||
['pet-store-api', 'pet', 'list', status] as const
|
||||
|
||||
/**
|
||||
* Получение списка питомцев по статусу.
|
||||
*/
|
||||
export const useGetPetList = (status: PetStatus | null, config?: SWRConfiguration) => {
|
||||
const isReady = status !== null
|
||||
const key = isReady ? getPetListKey(status) : null
|
||||
const fetcher = () => petStoreApi.pet.findPetsByStatus({ status })
|
||||
|
||||
return useSWR<Pet[]>(key, fetcher, config)
|
||||
}
|
||||
```
|
||||
|
||||
Функция `getPetListKey` нужна, чтобы один и тот же SWR-ключ использовался внутри GET-хука и при передаче начальных данных через `SWRConfig fallback`.
|
||||
|
||||
Пример начальных данных для клиентского хука:
|
||||
|
||||
```tsx
|
||||
import type { ReactNode } from 'react'
|
||||
import { SWRConfig, unstable_serialize } from 'swr'
|
||||
import {
|
||||
getPetListKey,
|
||||
petStoreApi,
|
||||
} from 'infrastructure/pet-store-api'
|
||||
|
||||
export default function PetsLayout({ children }: { children: ReactNode }) {
|
||||
const petsPromise = petStoreApi.pet.findPetsByStatus({ status: 'available' })
|
||||
|
||||
return (
|
||||
<SWRConfig
|
||||
value={{
|
||||
fallback: {
|
||||
[unstable_serialize(getPetListKey('available'))]: petsPromise,
|
||||
},
|
||||
}}
|
||||
>
|
||||
{children}
|
||||
</SWRConfig>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Клиентский компонент при этом ничего не знает про preload/fallback и продолжает вызывать обычный хук:
|
||||
|
||||
```tsx
|
||||
const { data: pets } = useGetPetList('available')
|
||||
```
|
||||
|
||||
## Пример detail-запроса
|
||||
|
||||
```ts
|
||||
// src/infrastructure/pet-store-api/hooks/use-get-pet-detail.hook.ts
|
||||
import useSWR from 'swr'
|
||||
import type { SWRConfiguration } from 'swr'
|
||||
import { petStoreApi } from '../client'
|
||||
import type { Pet } from '../generated/pet-store-api.generated'
|
||||
|
||||
export const getPetDetailKey = (id: number) =>
|
||||
['pet-store-api', 'pet', 'detail', id] as const
|
||||
|
||||
/**
|
||||
* Получение питомца по идентификатору.
|
||||
*/
|
||||
export const useGetPetDetail = (id: number | null, config?: SWRConfiguration) => {
|
||||
const isReady = id !== null
|
||||
const key = isReady ? getPetDetailKey(id) : null
|
||||
const fetcher = () => petStoreApi.pet.getPetById(id)
|
||||
|
||||
return useSWR<Pet>(key, fetcher, config)
|
||||
}
|
||||
```
|
||||
|
||||
## Отложенный запрос через `null`
|
||||
|
||||
GET-хук может принимать `null` для обязательного параметра. `null` означает, что параметр ещё не готов и запрос выполнять нельзя.
|
||||
|
||||
Внутри хука это выражается через `isReady`: если параметр не готов, ключ SWR становится `null`, и SWR не вызывает fetcher.
|
||||
|
||||
```ts
|
||||
const isReady = id !== null
|
||||
const key = isReady ? getPetDetailKey(id) : null
|
||||
```
|
||||
|
||||
`null` не передаётся в метод клиента. Key-функция принимает только готовые параметры, поэтому её можно безопасно использовать для начальных данных через `SWRConfig fallback`.
|
||||
|
||||
Для числовых идентификаторов не используйте проверку `if (id)`: значение `0` тоже валидное число. Проверяйте явно: `id !== null`.
|
||||
|
||||
## Экспорт
|
||||
|
||||
```ts
|
||||
// src/infrastructure/pet-store-api/hooks/index.ts
|
||||
export { getPetListKey, useGetPetList } from './use-get-pet-list.hook'
|
||||
export type { PetStatus } from './use-get-pet-list.hook'
|
||||
export { getPetDetailKey, useGetPetDetail } from './use-get-pet-detail.hook'
|
||||
```
|
||||
|
||||
```ts
|
||||
// src/infrastructure/pet-store-api/index.ts
|
||||
export { petStoreApi } from './client'
|
||||
export type { Pet } from './generated/pet-store-api.generated'
|
||||
export * from './hooks'
|
||||
```
|
||||
|
||||
## Где заканчивается infrastructure
|
||||
|
||||
```ts
|
||||
// Хорошо: infrastructure, прозрачный GET-хук
|
||||
const { data: pets } = useGetPetList('available')
|
||||
```
|
||||
|
||||
```ts
|
||||
// Хорошо: business, доменная интерпретация
|
||||
export const useAvailablePets = () => {
|
||||
const query = useGetPetList('available')
|
||||
|
||||
return {
|
||||
...query,
|
||||
hasPets: Boolean(query.data?.length),
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`hasPets` — не часть GET-запроса, поэтому он не добавляется в `useGetPetList`.
|
||||
|
||||
## Что запрещено
|
||||
|
||||
```ts
|
||||
// Плохо — useSWR в компоненте
|
||||
const { data } = useSWR(
|
||||
['pet-store-api', 'pet', 'list', status],
|
||||
() => petStoreApi.pet.findPetsByStatus({ status }),
|
||||
)
|
||||
|
||||
// Плохо — несколько GET внутри infrastructure-хука
|
||||
export const usePetDashboard = () => {
|
||||
const available = useGetPetList('available')
|
||||
const sold = useGetPetList('sold')
|
||||
|
||||
return { available, sold }
|
||||
}
|
||||
|
||||
// Плохо — бизнес-флаг внутри GET-хука REST-клиента
|
||||
export const useGetPetList = (status: PetStatus) => {
|
||||
const query = useSWR(...)
|
||||
|
||||
return {
|
||||
...query,
|
||||
hasPets: Boolean(query.data?.length),
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Подробное потребление таких хуков описано в стратегии [Клиентский GET-хук](../strategies/client-get-hook.md).
|
||||
75
ai/nextjs-style-guide/data/rest/clients/index.md
Normal file
75
ai/nextjs-style-guide/data/rest/clients/index.md
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
title: Создание клиента
|
||||
description: Из чего состоит REST-клиент и какие части нужно подготовить перед использованием API.
|
||||
keywords: [rest, клиент, infrastructure, методы, openapi, get-хуки, swr]
|
||||
---
|
||||
|
||||
# Создание клиента
|
||||
|
||||
REST-клиент — это infrastructure-модуль, через который проект работает с внешним REST API.
|
||||
|
||||
На этом этапе нужно подготовить клиент сервиса: создать оболочку клиента, получить методы API и добавить GET-хуки для клиентских компонентов.
|
||||
|
||||
## Из чего состоит клиент
|
||||
|
||||
REST-клиент состоит из трёх основных частей:
|
||||
|
||||
1. **Клиент** — самописная оболочка над транспортом.
|
||||
2. **Методы** — сгенерированные из OpenAPI или написанные вручную вызовы API.
|
||||
3. **GET-хуки** — SWR-обёртки для GET-запросов.
|
||||
|
||||
Эти части живут в одном REST-модуле, потому что относятся к одному внешнему сервису.
|
||||
|
||||
## Клиент
|
||||
|
||||
Клиент — ручной слой, который настраивает работу с API: `baseUrl`, заголовки, авторизацию, обработку ошибок и создание инстанса сервиса.
|
||||
|
||||
Даже если методы генерируются из OpenAPI, `client.ts` остаётся ручным файлом проекта.
|
||||
|
||||
`client.ts` — только сборочная точка клиента. В нём не размещаются DTO, `declare module`, `Extended`-типы, GET-хуки и бизнес-логика.
|
||||
|
||||
## Методы
|
||||
|
||||
Методы описывают конкретные запросы к API.
|
||||
|
||||
Они появляются одним из двух способов:
|
||||
|
||||
- генерируются из OpenAPI в `generated/`;
|
||||
- создаются вручную в `methods/`.
|
||||
|
||||
Подробности:
|
||||
|
||||
- [Автогенерация из OpenAPI](./auto.md)
|
||||
- [Ручное создание](./manual.md)
|
||||
|
||||
## GET-хуки
|
||||
|
||||
Для GET-запросов добавляются GET-хуки REST-клиента.
|
||||
|
||||
Это прозрачные SWR-обёртки над GET-методами клиента. Они живут в `hooks/` этого же REST-модуля и нужны для использования данных в Client Components.
|
||||
|
||||
GET-хуки именуются с префиксом `useGet`: `useGetPetList`, `useGetPetDetail`, `useGetCurrentUser`.
|
||||
|
||||
Подробности:
|
||||
|
||||
- [GET-хуки REST-клиента](./hooks.md)
|
||||
|
||||
## Структура модуля
|
||||
|
||||
```text
|
||||
src/infrastructure/{service-name}/
|
||||
├── client.ts # самописная оболочка и инстанс клиента
|
||||
├── generated/ или methods/ # методы API
|
||||
├── hooks/ # GET-хуки REST-клиента
|
||||
├── types/ # DTO, типы API и расширения типов
|
||||
├── errors/ # ошибки API, если нужны
|
||||
└── index.ts # публичный API
|
||||
```
|
||||
|
||||
`index.ts` — единственная точка входа в REST-модуль для внешнего кода.
|
||||
|
||||
## Что делаем дальше
|
||||
|
||||
1. Создайте методы клиента: [Автогенерация из OpenAPI](./auto.md) или [Ручное создание](./manual.md).
|
||||
2. Добавьте GET-хуки для GET-запросов: [GET-хуки REST-клиента](./hooks.md).
|
||||
3. После создания клиента переходите к [Стратегиям получения данных](../strategies/index.md).
|
||||
187
ai/nextjs-style-guide/data/rest/clients/manual.md
Normal file
187
ai/nextjs-style-guide/data/rest/clients/manual.md
Normal file
@@ -0,0 +1,187 @@
|
||||
---
|
||||
title: Ручное создание
|
||||
description: Создание REST-клиента вручную, когда OpenAPI нет или он неполный.
|
||||
keywords: [rest, ручной клиент, fetch, methods, dto, errors, infrastructure]
|
||||
---
|
||||
|
||||
# Ручное создание
|
||||
|
||||
Ручной REST-клиент используется, когда у API нет OpenAPI-спецификации или она недостаточно точная для автогенерации.
|
||||
|
||||
Задача ручного клиента — дать такую же точку входа, как у автогенерированного клиента: именованный API-объект, методы по сущностям, DTO и GET-хуки рядом с клиентом.
|
||||
|
||||
## Что нужно создать
|
||||
|
||||
```text
|
||||
src/infrastructure/
|
||||
└── pet-project-api/
|
||||
├── methods/
|
||||
│ └── posts.ts
|
||||
├── hooks/
|
||||
│ └── index.ts
|
||||
├── types/
|
||||
│ ├── client.ts
|
||||
│ ├── post.ts
|
||||
│ └── index.ts
|
||||
├── errors/
|
||||
│ └── pet-project-api.error.ts
|
||||
├── client.ts
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
| Файл | Роль |
|
||||
|------|------|
|
||||
| `client.ts` | Базовый транспорт и создание инстанса клиента |
|
||||
| `methods/` | Методы API по сущностям |
|
||||
| `types/` | DTO запросов, ответов и типы клиента |
|
||||
| `errors/` | Ошибки конкретного API |
|
||||
| `hooks/` | GET-хуки REST-клиента, если данные нужны в Client Components |
|
||||
| `index.ts` | Публичный API REST-модуля |
|
||||
|
||||
## DTO и типы API
|
||||
|
||||
DTO запросов и ответов живут в `types/`. `client.ts` не содержит DTO и доменные типы.
|
||||
|
||||
```ts
|
||||
// src/infrastructure/pet-project-api/types/post.ts
|
||||
export type PostDto = {
|
||||
id: string
|
||||
slug: string
|
||||
title: string
|
||||
}
|
||||
|
||||
export type PostListQueryDto = {
|
||||
limit?: number
|
||||
category?: string
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
// src/infrastructure/pet-project-api/types/index.ts
|
||||
export type { PostDto, PostListQueryDto } from './post'
|
||||
```
|
||||
|
||||
Типы, которые нужны только базовому транспорту, можно держать отдельно:
|
||||
|
||||
```ts
|
||||
// src/infrastructure/pet-project-api/types/client.ts
|
||||
export type QueryParams = Record<string, string | number | boolean>
|
||||
```
|
||||
|
||||
## Ошибка API
|
||||
|
||||
Ошибка API тоже относится к REST-модулю.
|
||||
|
||||
```ts
|
||||
// src/infrastructure/pet-project-api/errors/pet-project-api.error.ts
|
||||
export class PetProjectApiError extends Error {
|
||||
constructor(
|
||||
public readonly status: number,
|
||||
message: string,
|
||||
) {
|
||||
super(message)
|
||||
this.name = 'PetProjectApiError'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Базовый клиент
|
||||
|
||||
`client.ts` содержит только транспортную оболочку и сборку инстанса. Прямой `fetch` живёт здесь, а не в компонентах и не в методах верхних слоёв.
|
||||
|
||||
```ts
|
||||
// src/infrastructure/pet-project-api/client.ts
|
||||
import { PetProjectApiError } from './errors/pet-project-api.error'
|
||||
import type { QueryParams } from './types/client'
|
||||
|
||||
export class PetProjectApiClient {
|
||||
constructor(
|
||||
private readonly baseUrl: string,
|
||||
private readonly defaultHeaders: Record<string, string> = {},
|
||||
) {}
|
||||
|
||||
async get<T>(path: string, params: QueryParams = {}): Promise<T> {
|
||||
const base = `${this.baseUrl.replace(/\/+$/, '')}/`
|
||||
const url = new URL(path.replace(/^\/+/, ''), base)
|
||||
|
||||
Object.entries(params).forEach(([key, value]) => {
|
||||
url.searchParams.set(key, String(value))
|
||||
})
|
||||
|
||||
const response = await fetch(url, {
|
||||
headers: {
|
||||
Accept: 'application/json',
|
||||
...this.defaultHeaders,
|
||||
},
|
||||
})
|
||||
|
||||
if (!response.ok) {
|
||||
throw new PetProjectApiError(response.status, response.statusText)
|
||||
}
|
||||
|
||||
return response.json() as Promise<T>
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Это минимальный шаблон. Авторизация, дополнительные заголовки, `next.revalidate`, `post`, `formdata` и другие детали добавляются только когда они реально нужны API.
|
||||
|
||||
## Методы API
|
||||
|
||||
Методы группируются по сущностям в `methods/`. Они не знают про React, SWR и UI.
|
||||
|
||||
```ts
|
||||
// src/infrastructure/pet-project-api/methods/posts.ts
|
||||
import type { PetProjectApiClient } from '../client'
|
||||
import type { PostDto, PostListQueryDto } from '../types/post'
|
||||
|
||||
export function postsMethods(client: PetProjectApiClient) {
|
||||
return {
|
||||
/** GET /posts */
|
||||
list: (query: PostListQueryDto = {}) =>
|
||||
client.get<PostDto[]>('posts', query),
|
||||
|
||||
/** GET /posts/{slug} */
|
||||
get: (slug: string) =>
|
||||
client.get<PostDto>(`posts/${slug}`),
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Метод возвращает DTO в форме API. Если данным нужен доменный смысл, маппинг делается выше, в `business/`.
|
||||
|
||||
## Публичный API
|
||||
|
||||
`index.ts` собирает именованный API-объект и открывает наружу только публичные части модуля.
|
||||
|
||||
```ts
|
||||
// src/infrastructure/pet-project-api/index.ts
|
||||
import { PetProjectApiClient } from './client'
|
||||
import { postsMethods } from './methods/posts'
|
||||
|
||||
const client = new PetProjectApiClient(
|
||||
process.env.NEXT_PUBLIC_API_URL ?? '',
|
||||
{ 'Content-Type': 'application/json' },
|
||||
)
|
||||
|
||||
export const petProjectApi = {
|
||||
posts: postsMethods(client),
|
||||
}
|
||||
|
||||
export { PetProjectApiError } from './errors/pet-project-api.error'
|
||||
export type { PostDto, PostListQueryDto } from './types'
|
||||
export * from './hooks'
|
||||
```
|
||||
|
||||
Внешний код импортирует только из `infrastructure/pet-project-api`, не из внутренних файлов модуля.
|
||||
|
||||
## Правила
|
||||
|
||||
- `fetch` используется только внутри базового клиента.
|
||||
- DTO запросов и ответов живут в `types/`.
|
||||
- `client.ts` не содержит DTO, GET-хуки и бизнес-логику.
|
||||
- Методы лежат в `methods/` и возвращают DTO.
|
||||
- GET-хуки добавляются отдельно в `hooks/`, если данные нужны в Client Components.
|
||||
- Доменные типы и маппинг DTO живут не в REST-клиенте, а в `business/`.
|
||||
|
||||
Следующий шаг: [GET-хуки REST-клиента](./hooks.md) или [Стратегии получения данных](../strategies/index.md).
|
||||
74
ai/nextjs-style-guide/data/rest/index.md
Normal file
74
ai/nextjs-style-guide/data/rest/index.md
Normal file
@@ -0,0 +1,74 @@
|
||||
---
|
||||
title: REST
|
||||
description: Как правильно работать с REST API в проекте.
|
||||
keywords: [rest, api, данные, infrastructure, клиент, swr, стратегии]
|
||||
---
|
||||
|
||||
# REST
|
||||
|
||||
Раздел описывает, как правильно работать с REST API в проекте: создать клиент сервиса и выбрать способ получения данных в приложении.
|
||||
|
||||
REST в проекте проходит через два главных этапа:
|
||||
|
||||
1. Создание клиента.
|
||||
2. Использование.
|
||||
|
||||
## 1. Создание клиента
|
||||
|
||||
На этом этапе внешний API оформляется как модуль слоя `infrastructure/`.
|
||||
|
||||
Клиент отвечает за:
|
||||
|
||||
- генерацию или ручное описание методов API;
|
||||
- настройку `baseUrl`;
|
||||
- заголовки и авторизацию;
|
||||
- обработку ошибок;
|
||||
- кастомизацию и расширение типов;
|
||||
- GET-хуки для клиентских компонентов;
|
||||
- публичный API модуля.
|
||||
|
||||
Если у API есть OpenAPI-спецификация — клиент генерируется автоматически. Если OpenAPI нет или он неполный — клиент создаётся вручную.
|
||||
|
||||
GET-хуки относятся к клиенту, потому что это прозрачные SWR-обёртки над GET-методами этого клиента.
|
||||
|
||||
Подробнее:
|
||||
|
||||
- [Создание клиента](./clients/index.md)
|
||||
- [Автогенерация из OpenAPI](./clients/auto.md)
|
||||
- [Ручное создание](./clients/manual.md)
|
||||
- [GET-хуки REST-клиента](./clients/hooks.md)
|
||||
|
||||
## 2. Использование
|
||||
|
||||
После создания клиента нужно определить рендер страницы и выбрать, как получать данные в конкретном месте приложения.
|
||||
|
||||
Раздел использования отвечает на вопросы:
|
||||
|
||||
- как понять, можно ли сохранить static/ISR;
|
||||
- когда страница становится dynamic/SSR;
|
||||
- когда получать данные через серверный `await`;
|
||||
- когда запускать несколько серверных запросов параллельно;
|
||||
- когда передавать промис ниже по дереву;
|
||||
- когда передавать начальные данные клиентским GET-хукам;
|
||||
- когда использовать GET-хук в клиентском компоненте;
|
||||
- когда выносить композицию и бизнес-смысл в `business/`.
|
||||
|
||||
Подробнее:
|
||||
|
||||
- [Стратегии получения данных](./strategies/index.md)
|
||||
- [Серверный await](./strategies/server-await.md)
|
||||
- [Параллельные серверные запросы](./strategies/parallel-server-requests.md)
|
||||
- [Передача промиса ниже](./strategies/pass-promise-down.md)
|
||||
- [Начальные данные для клиентских хуков](./strategies/client-hooks-initial-data.md)
|
||||
- [Клиентский GET-хук](./strategies/client-get-hook.md)
|
||||
- [Business-композиция](./strategies/business-composition.md)
|
||||
|
||||
## Как читать раздел
|
||||
|
||||
Если API ещё не подключён — начните с [Создания клиента](./clients/index.md).
|
||||
|
||||
Если клиент уже есть, но непонятно как получить данные — начните со [Стратегий получения данных](./strategies/index.md).
|
||||
|
||||
Если данные нужны в Client Component — сначала проверьте, есть ли [GET-хук REST-клиента](./clients/hooks.md).
|
||||
|
||||
Если в коде появляется бизнес-смысл вроде `isAuth`, `canEdit`, `hasAccess` — это уже не REST-клиент, а `business/`.
|
||||
@@ -0,0 +1,121 @@
|
||||
---
|
||||
title: Business-композиция
|
||||
description: Когда REST-данные нужно объединить или интерпретировать в бизнес-модуле.
|
||||
keywords: [rest, business, композиция, hooks, domain, isAuth]
|
||||
---
|
||||
|
||||
# Business-композиция
|
||||
|
||||
Business-композиция используется, когда простого GET-метода или прозрачного GET-хука недостаточно: нужно объединить несколько источников, преобразовать DTO или вычислить доменное состояние.
|
||||
|
||||
## Когда использовать
|
||||
|
||||
- Нужно объединить несколько GET-запросов.
|
||||
- Нужно вычислить `isAuth`, `canEdit`, `hasAccess`, `hasPets`.
|
||||
- Нужно преобразовать DTO в доменную модель.
|
||||
- Нужно спрятать бизнес-сценарий за доменным API.
|
||||
|
||||
Такая логика не пишется в `infrastructure/`. REST-клиент остаётся прозрачным адаптером к API.
|
||||
|
||||
## Пример поверх одного GET-хука
|
||||
|
||||
```ts
|
||||
// src/business/pets/hooks/use-available-pets.hook.ts
|
||||
import { useGetPetList } from 'infrastructure/pet-store-api'
|
||||
|
||||
/**
|
||||
* Доменный список доступных питомцев.
|
||||
*/
|
||||
export const useAvailablePets = () => {
|
||||
const query = useGetPetList('available')
|
||||
|
||||
return {
|
||||
...query,
|
||||
hasPets: Boolean(query.data?.length),
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`useGetPetList` — infrastructure-хук. `hasPets` — бизнес-интерпретация, поэтому она появляется в `business/pets`.
|
||||
|
||||
## Пример композиции нескольких GET-хуков
|
||||
|
||||
```ts
|
||||
// src/business/pets/hooks/use-pets-dashboard.hook.ts
|
||||
import { useGetPetList } from 'infrastructure/pet-store-api'
|
||||
|
||||
/**
|
||||
* Данные dashboard по питомцам.
|
||||
*/
|
||||
export const usePetsDashboard = () => {
|
||||
const availablePets = useGetPetList('available')
|
||||
const pendingPets = useGetPetList('pending')
|
||||
const soldPets = useGetPetList('sold')
|
||||
|
||||
return {
|
||||
availablePets,
|
||||
pendingPets,
|
||||
soldPets,
|
||||
total:
|
||||
(availablePets.data?.length ?? 0) +
|
||||
(pendingPets.data?.length ?? 0) +
|
||||
(soldPets.data?.length ?? 0),
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Композиция нескольких запросов не добавляется в `infrastructure/pet-store-api/hooks/`, потому что это уже сценарий потребления данных.
|
||||
|
||||
## Пример auth-состояния
|
||||
|
||||
```ts
|
||||
// src/business/auth/hooks/use-auth-state.hook.ts
|
||||
import { useGetCurrentUser } from 'infrastructure/backend-api'
|
||||
|
||||
/**
|
||||
* Состояние авторизации текущего пользователя.
|
||||
*/
|
||||
export const useAuthState = () => {
|
||||
const currentUser = useGetCurrentUser()
|
||||
const user = currentUser.data
|
||||
|
||||
return {
|
||||
...currentUser,
|
||||
user,
|
||||
isAuth: Boolean(user),
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`isAuth` не является частью REST-клиента. Это доменный смысл результата запроса.
|
||||
|
||||
## Где размещать
|
||||
|
||||
```text
|
||||
src/business/
|
||||
└── pets/
|
||||
├── hooks/
|
||||
│ └── use-available-pets.hook.ts
|
||||
├── mappers/
|
||||
│ └── map-pet-dto-to-pet.ts
|
||||
├── types/
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
Модуль `business/` экспортирует наружу готовый доменный API через `index.ts`.
|
||||
|
||||
## Что запрещено
|
||||
|
||||
```ts
|
||||
// Плохо — business-смысл внутри infrastructure-хука
|
||||
export const useGetPetList = (status: PetStatus) => {
|
||||
const query = useSWR(...)
|
||||
|
||||
return {
|
||||
...query,
|
||||
hasPets: Boolean(query.data?.length),
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
REST-модуль отвечает за доступ к API. Business-модуль отвечает за смысл этих данных в продукте.
|
||||
@@ -0,0 +1,89 @@
|
||||
---
|
||||
title: Клиентский GET-хук
|
||||
description: Получение REST-данных в Client Components через готовые GET-хуки REST-клиента.
|
||||
keywords: [rest, client components, swr, get-хук, client state]
|
||||
---
|
||||
|
||||
# Клиентский GET-хук
|
||||
|
||||
Клиентский GET-хук используется, когда данные зависят от состояния браузера: вкладки, фильтра, поиска, пагинации, модалки или действия пользователя.
|
||||
|
||||
## Когда использовать
|
||||
|
||||
- Запрос зависит от client state.
|
||||
- Данные не обязательны для первого HTML.
|
||||
- Пользователь меняет параметры запроса на клиенте.
|
||||
- Нужны SWR-кеширование, дедупликация и ревалидация.
|
||||
|
||||
## Пример с вкладками
|
||||
|
||||
```tsx
|
||||
'use client'
|
||||
|
||||
import { useState } from 'react'
|
||||
import { useGetPetList } from 'infrastructure/pet-store-api'
|
||||
import type { PetStatus } from 'infrastructure/pet-store-api'
|
||||
|
||||
const statuses: PetStatus[] = ['available', 'pending', 'sold']
|
||||
|
||||
export function PetTabs() {
|
||||
const [status, setStatus] = useState<PetStatus>('available')
|
||||
const { data: pets, isLoading, error } = useGetPetList(status)
|
||||
|
||||
return (
|
||||
<section>
|
||||
<div>
|
||||
{statuses.map((item) => (
|
||||
<button key={item} type="button" onClick={() => setStatus(item)}>
|
||||
{item}
|
||||
</button>
|
||||
))}
|
||||
</div>
|
||||
|
||||
{isLoading && <div>Загрузка...</div>}
|
||||
{error && <div>Ошибка загрузки</div>}
|
||||
|
||||
<ul>
|
||||
{pets?.map((pet) => (
|
||||
<li key={pet.id}>{pet.name}</li>
|
||||
))}
|
||||
</ul>
|
||||
</section>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Компонент выбирает параметр `status`, но не знает про SWR-ключ и fetcher. Запрос выполняет готовый GET-хук REST-клиента.
|
||||
|
||||
## Если хука нет
|
||||
|
||||
Хук добавляется в REST-модуль сервиса:
|
||||
|
||||
```text
|
||||
src/infrastructure/pet-store-api/hooks/use-get-pet-list.hook.ts
|
||||
```
|
||||
|
||||
Не создавайте локальный `useSWR` в компоненте.
|
||||
|
||||
## Плохо
|
||||
|
||||
```tsx
|
||||
// Плохо — прямой вызов клиента в useEffect
|
||||
useEffect(() => {
|
||||
petStoreApi.pet.findPetsByStatus({ status }).then(setPets)
|
||||
}, [status])
|
||||
|
||||
// Плохо — useSWR в компоненте
|
||||
const { data } = useSWR(
|
||||
['pet-store-api', 'pet', 'list', status],
|
||||
() => petStoreApi.pet.findPetsByStatus({ status }),
|
||||
)
|
||||
```
|
||||
|
||||
Такой код теряет единое место для ключей, дублирует fetcher и разносит инфраструктурные детали по UI.
|
||||
|
||||
## Когда выбрать другую стратегию
|
||||
|
||||
- Данные нужны до первого HTML — [Серверный await](./server-await.md).
|
||||
- Клиентский хук должен получить начальные данные сразу — [Начальные данные для клиентских хуков](./client-hooks-initial-data.md).
|
||||
- Нужно вычислить бизнес-состояние — [Business-композиция](./business-composition.md).
|
||||
@@ -0,0 +1,109 @@
|
||||
---
|
||||
title: Начальные данные для клиентских хуков
|
||||
description: Как дать клиентским GET-хукам начальные REST-данные.
|
||||
keywords: [rest, swr, fallback, initial data, client hooks, unstable_serialize, isr, ssr]
|
||||
---
|
||||
|
||||
# Начальные данные для клиентских хуков
|
||||
|
||||
Как дать клиентским GET-хукам начальные REST-данные.
|
||||
|
||||
Эта стратегия используется, когда данные должны быть запущены на сервере, но потребляться на клиенте через GET-хуки REST-клиента.
|
||||
|
||||
Технически это делается через `SWRConfig fallback`: сервер передаёт промис в fallback, а клиентский хук использует тот же SWR-ключ.
|
||||
|
||||
## Когда использовать
|
||||
|
||||
- Внутри страницы есть Client Components с GET-хуками.
|
||||
- Нужно начать загрузку данных на сервере раньше.
|
||||
- Клиентский компонент должен остаться обычным потребителем `useGetPetList(...)`.
|
||||
- Не нужно писать отдельный prop-drilling для начальных данных.
|
||||
|
||||
## Рендер страницы
|
||||
|
||||
Перед этой стратегией сначала определите рендер маршрута. Серверный preload для `fallback` подчиняется тем же правилам, что и любой серверный запрос в `page.tsx` или `layout.tsx`.
|
||||
|
||||
Если данные общие и могут обновляться по интервалу, сохраняйте static/ISR. Если preload зависит от cookie, headers, `searchParams`, `no-store` или персональных данных пользователя, маршрут становится dynamic/SSR.
|
||||
|
||||
`SWRConfig fallback` не должен быть причиной отключать ISR на всякий случай. Он только передаёт клиентскому GET-хуку данные, которые уже были запущены на сервере.
|
||||
|
||||
## Ключ хука
|
||||
|
||||
```ts
|
||||
// src/infrastructure/pet-store-api/hooks/use-get-pet-list.hook.ts
|
||||
export const getPetListKey = (status: PetStatus) =>
|
||||
['pet-store-api', 'pet', 'list', status] as const
|
||||
```
|
||||
|
||||
Ключ экспортируется из REST-модуля, потому что он нужен и GET-хуку, и серверному `SWRConfig fallback`.
|
||||
|
||||
## Пример layout
|
||||
|
||||
```tsx
|
||||
// src/app/(routes)/pets/layout.tsx
|
||||
import type { ReactNode } from 'react'
|
||||
import { SWRConfig, unstable_serialize } from 'swr'
|
||||
import {
|
||||
getPetListKey,
|
||||
petStoreApi,
|
||||
} from 'infrastructure/pet-store-api'
|
||||
|
||||
type PetsLayoutProps = {
|
||||
children: ReactNode
|
||||
}
|
||||
|
||||
export default async function PetsLayout({ children }: PetsLayoutProps) {
|
||||
const availablePetsPromise = petStoreApi.pet.findPetsByStatus({
|
||||
status: 'available',
|
||||
})
|
||||
|
||||
return (
|
||||
<SWRConfig
|
||||
value={{
|
||||
fallback: {
|
||||
[unstable_serialize(getPetListKey('available'))]: availablePetsPromise,
|
||||
},
|
||||
}}
|
||||
>
|
||||
{children}
|
||||
</SWRConfig>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Если GET-хук использует array-key, ключ для `fallback` сериализуется через `unstable_serialize`.
|
||||
|
||||
## Клиентский компонент
|
||||
|
||||
```tsx
|
||||
'use client'
|
||||
|
||||
import { useGetPetList } from 'infrastructure/pet-store-api'
|
||||
|
||||
export function PetList() {
|
||||
const { data: pets, isLoading } = useGetPetList('available')
|
||||
|
||||
if (isLoading) return <div>Загрузка...</div>
|
||||
|
||||
return (
|
||||
<ul>
|
||||
{pets?.map((pet) => (
|
||||
<li key={pet.id}>{pet.name}</li>
|
||||
))}
|
||||
</ul>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Компонент не знает, что данные были запущены на сервере. Он использует обычный GET-хук REST-клиента.
|
||||
|
||||
## Что важно
|
||||
|
||||
- Ключ `fallback` должен совпадать с ключом GET-хука.
|
||||
- Серверный код вызывает метод клиента, а не GET-хук.
|
||||
- Клиентский компонент вызывает GET-хук, а не `useSWR` напрямую.
|
||||
- Эта стратегия не означает ручную работу с кешем в компонентах.
|
||||
|
||||
## Когда не использовать
|
||||
|
||||
Если данные нужны только серверному компоненту, используйте [Серверный await](./server-await.md). Если данные зависят от состояния браузера, используйте [Клиентский GET-хук](./client-get-hook.md).
|
||||
100
ai/nextjs-style-guide/data/rest/strategies/index.md
Normal file
100
ai/nextjs-style-guide/data/rest/strategies/index.md
Normal file
@@ -0,0 +1,100 @@
|
||||
---
|
||||
title: Стратегии получения данных
|
||||
description: Как выбрать получение REST-данных с учётом рендера страницы.
|
||||
keywords: [rest, стратегии, render, isr, ssr, server components, swr, promise, business]
|
||||
---
|
||||
|
||||
# Стратегии получения данных
|
||||
|
||||
Как выбрать получение REST-данных с учётом рендера страницы.
|
||||
|
||||
Перед выбором стратегии должен быть создан REST-клиент сервиса. Если клиента ещё нет, начните с раздела [Создание клиента](../clients/index.md).
|
||||
|
||||
## Сначала определите рендер страницы
|
||||
|
||||
В Next.js выбор начинается не с `await`, `Suspense` или SWR. Сначала нужно понять, какой рендер получится у маршрута: static/ISR или dynamic/SSR.
|
||||
|
||||
Next.js может перевести страницу в dynamic rendering автоматически, если в маршруте используются API текущего запроса. Поэтому первый вопрос такой:
|
||||
|
||||
```text
|
||||
Можно ли сохранить ISR, или странице нужны данные на каждый request?
|
||||
```
|
||||
|
||||
ISR — приоритет. Если данные общие для пользователей и их можно обновлять с интервалом, не переводите страницу в SSR без необходимости.
|
||||
|
||||
SSR/dynamic rendering выбирается только когда данные действительно зависят от текущего request или должны пересчитываться на каждый запрос.
|
||||
|
||||
## Что переводит страницу в dynamic rendering
|
||||
|
||||
Проверьте, нужны ли странице API и настройки, которые делают маршрут динамическим:
|
||||
|
||||
- `cookies()` — данные зависят от cookie текущего пользователя.
|
||||
- `headers()` — данные зависят от request headers.
|
||||
- `draftMode()` — нужен preview/draft-режим.
|
||||
- `searchParams` в `page.tsx` — данные зависят от query string.
|
||||
- `cache: 'no-store'` или `revalidate: 0` в методе клиента — запрос нельзя кешировать.
|
||||
- `connection()` — рендер явно ждёт request.
|
||||
- `export const dynamic = 'force-dynamic'` — SSR включён вручную.
|
||||
|
||||
Если ничего из этого не нужно, сначала проектируйте страницу как static/ISR. Серверный `await` сам по себе не означает SSR: режим зависит от кеширования запроса и dynamic API маршрута.
|
||||
|
||||
## Рендер перед стратегией
|
||||
|
||||
| Рендер | Когда подходит | Что выбирать дальше |
|
||||
|--------|----------------|---------------------|
|
||||
| Static/ISR | Данные общие и могут обновляться по интервалу | Серверные стратегии: `await`, `Promise.all`, передача промиса ниже, SWR `fallback` |
|
||||
| SSR/dynamic | Данные зависят от request, пользователя или должны быть свежими на каждый запрос | Серверные стратегии с учётом блокировки первого HTML |
|
||||
| После гидрации | Данные зависят от вкладки, фильтра, поиска, пагинации или действия пользователя | Клиентский GET-хук |
|
||||
|
||||
## Как выбрать стратегию
|
||||
|
||||
Когда режим рендера понятен, выбирайте конкретный способ получения данных:
|
||||
|
||||
| Ситуация после выбора рендера | Стратегия | Где читать |
|
||||
|-------------------------------|-----------|------------|
|
||||
| Данные обязательны для первого HTML, SEO, `notFound()` или `redirect()` | Серверный `await` | [Серверный await](./server-await.md) |
|
||||
| Несколько независимых данных нужны до рендера | Запуск промисов + `Promise.all` | [Параллельные серверные запросы](./parallel-server-requests.md) |
|
||||
| Часть UI можно загрузить отдельно | Передача промиса ниже + `Suspense` | [Передача промиса ниже](./pass-promise-down.md) |
|
||||
| Client Component должен получить данные сразу из SWR | Начальные данные для клиентских хуков | [Начальные данные для клиентских хуков](./client-hooks-initial-data.md) |
|
||||
| Данные зависят от client state | Клиентский GET-хук | [Клиентский GET-хук](./client-get-hook.md) |
|
||||
| Нужно объединить несколько запросов или вычислить `isAuth`, `canEdit`, `hasPets` | Business-композиция | [Business-композиция](./business-composition.md) |
|
||||
|
||||
## Правило выбора
|
||||
|
||||
Не выбирайте стратегию по любимому инструменту. Выбирайте её по двум вопросам:
|
||||
|
||||
```text
|
||||
Можно ли сохранить ISR?
|
||||
Где нужны данные и что должно произойти до первого HTML?
|
||||
```
|
||||
|
||||
Если данные можно кешировать между пользователями — сохраняйте static/ISR. Если данные request-specific — используйте SSR/dynamic rendering. Если данные зависят от состояния браузера — используйте GET-хук REST-клиента. Если простой GET превращается в доменный сценарий — переходите в `business/`.
|
||||
|
||||
## Общие запреты
|
||||
|
||||
```tsx
|
||||
// Плохо — SSR включён на всякий случай
|
||||
export const dynamic = 'force-dynamic'
|
||||
|
||||
// Плохо — ISR отключён без требования к свежести на каждый request
|
||||
export const revalidate = 0
|
||||
|
||||
// Плохо — прямой fetch в компоненте
|
||||
useEffect(() => {
|
||||
fetch('/api/pets').then(...)
|
||||
}, [])
|
||||
|
||||
// Плохо — useSWR в компоненте
|
||||
const { data } = useSWR(
|
||||
['pet-store-api', 'pet', 'list', status],
|
||||
() => petStoreApi.pet.findPetsByStatus({ status }),
|
||||
)
|
||||
|
||||
// Плохо — бизнес-флаг внутри GET-хука REST-клиента
|
||||
return {
|
||||
...query,
|
||||
hasPets: Boolean(query.data?.length),
|
||||
}
|
||||
```
|
||||
|
||||
Не отключайте ISR без причины. В компонентах используются готовые методы клиента или готовые хуки. SWR-ключи, fetcher и транспорт остаются внутри REST-модуля.
|
||||
@@ -0,0 +1,82 @@
|
||||
---
|
||||
title: Параллельные серверные запросы
|
||||
description: Как запускать независимые REST-запросы на сервере без waterfall.
|
||||
keywords: [rest, promise.all, параллельные запросы, server components]
|
||||
---
|
||||
|
||||
# Параллельные серверные запросы
|
||||
|
||||
Если серверному компоненту нужно несколько независимых данных, запускайте запросы до ожидания результата. Последовательный `await` создаёт waterfall и замедляет рендер.
|
||||
|
||||
## Когда использовать
|
||||
|
||||
- Запросы независимы друг от друга.
|
||||
- Все данные нужны текущему серверному компоненту перед возвратом UI.
|
||||
- Нельзя или не нужно стримить часть UI отдельно.
|
||||
|
||||
## Хорошо
|
||||
|
||||
```tsx
|
||||
import { petStoreApi } from 'infrastructure/pet-store-api'
|
||||
import { PetsDashboardScreen } from 'screens/pets-dashboard'
|
||||
|
||||
export default async function PetsDashboardPage() {
|
||||
const availablePetsPromise = petStoreApi.pet.findPetsByStatus({ status: 'available' })
|
||||
const pendingPetsPromise = petStoreApi.pet.findPetsByStatus({ status: 'pending' })
|
||||
const soldPetsPromise = petStoreApi.pet.findPetsByStatus({ status: 'sold' })
|
||||
|
||||
const [availablePets, pendingPets, soldPets] = await Promise.all([
|
||||
availablePetsPromise,
|
||||
pendingPetsPromise,
|
||||
soldPetsPromise,
|
||||
])
|
||||
|
||||
return (
|
||||
<PetsDashboardScreen
|
||||
availablePets={availablePets}
|
||||
pendingPets={pendingPets}
|
||||
soldPets={soldPets}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Плохо
|
||||
|
||||
```tsx
|
||||
export default async function PetsDashboardPage() {
|
||||
const availablePets = await petStoreApi.pet.findPetsByStatus({ status: 'available' })
|
||||
const pendingPets = await petStoreApi.pet.findPetsByStatus({ status: 'pending' })
|
||||
const soldPets = await petStoreApi.pet.findPetsByStatus({ status: 'sold' })
|
||||
|
||||
return (
|
||||
<PetsDashboardScreen
|
||||
availablePets={availablePets}
|
||||
pendingPets={pendingPets}
|
||||
soldPets={soldPets}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Во втором примере каждый следующий запрос ждёт предыдущий, хотя они независимы.
|
||||
|
||||
## Зависимые запросы
|
||||
|
||||
Если второй запрос зависит от результата первого, последовательный `await` допустим:
|
||||
|
||||
```tsx
|
||||
export default async function OrderPage({ params }: OrderPageProps) {
|
||||
const { id } = await params
|
||||
const order = await petStoreApi.store.getOrderById(Number(id))
|
||||
const pet = await petStoreApi.pet.getPetById(order.petId)
|
||||
|
||||
return <OrderScreen order={order} pet={pet} />
|
||||
}
|
||||
```
|
||||
|
||||
Не превращайте зависимый сценарий в `Promise.all` искусственно.
|
||||
|
||||
## Когда выбрать другую стратегию
|
||||
|
||||
Если часть данных не обязательна для первого блока UI, можно запустить промис выше и передать его ниже: [Передача промиса ниже](./pass-promise-down.md).
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: Передача промиса ниже
|
||||
description: Как запускать серверный REST-запрос выше и ожидать его во вложенном server-компоненте.
|
||||
keywords: [rest, promise, suspense, streaming, server components]
|
||||
---
|
||||
|
||||
# Передача промиса ниже
|
||||
|
||||
Серверный компонент может запустить запрос и передать промис вложенному server-компоненту. Это полезно, когда часть UI можно загрузить отдельно через `Suspense`.
|
||||
|
||||
## Когда использовать
|
||||
|
||||
- Верхняя часть страницы может отрендериться без этих данных.
|
||||
- Данные нужны только вложенному server-компоненту.
|
||||
- Нужна `Suspense`-граница и серверный стриминг.
|
||||
|
||||
## Пример
|
||||
|
||||
```tsx
|
||||
// src/app/(routes)/pets/page.tsx
|
||||
import { Suspense } from 'react'
|
||||
import { petStoreApi } from 'infrastructure/pet-store-api'
|
||||
import { PetListSection } from 'widgets/pet-list-section'
|
||||
import { PetListSkeleton } from 'widgets/pet-list-section'
|
||||
import type { Pet } from 'infrastructure/pet-store-api'
|
||||
|
||||
export default function PetsPage() {
|
||||
const petsPromise = petStoreApi.pet.findPetsByStatus({ status: 'available' })
|
||||
|
||||
return (
|
||||
<main>
|
||||
<h1>Питомцы</h1>
|
||||
<Suspense fallback={<PetListSkeleton />}>
|
||||
<AvailablePets petsPromise={petsPromise} />
|
||||
</Suspense>
|
||||
</main>
|
||||
)
|
||||
}
|
||||
|
||||
async function AvailablePets({ petsPromise }: { petsPromise: Promise<Pet[]> }) {
|
||||
const pets = await petsPromise
|
||||
|
||||
return <PetListSection pets={pets} />
|
||||
}
|
||||
```
|
||||
|
||||
Запрос стартует в `PetsPage`, но ожидание происходит внутри `AvailablePets`. `Suspense` управляет fallback для этой части UI.
|
||||
|
||||
## Граница стратегии
|
||||
|
||||
Эта стратегия остаётся серверной. Не используйте её как замену GET-хукам в Client Components.
|
||||
|
||||
Если данные должны попасть в клиентский SWR-хук, используйте [Начальные данные для клиентских хуков](./client-hooks-initial-data.md).
|
||||
|
||||
## Что не делать
|
||||
|
||||
```tsx
|
||||
// Плохо — передавать промис в произвольный клиентский компонент без ясной стратегии
|
||||
return <PetListClient petsPromise={petsPromise} />
|
||||
```
|
||||
|
||||
Для клиентского потребления есть отдельная стратегия через `SWRConfig fallback` и готовые GET-хуки REST-клиента.
|
||||
88
ai/nextjs-style-guide/data/rest/strategies/server-await.md
Normal file
88
ai/nextjs-style-guide/data/rest/strategies/server-await.md
Normal file
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: Серверный await
|
||||
description: Получение REST-данных на сервере до первого HTML.
|
||||
keywords: [rest, server components, await, nextjs, isr, ssr, notFound, redirect]
|
||||
---
|
||||
|
||||
# Серверный await
|
||||
|
||||
Получение REST-данных на сервере до первого HTML.
|
||||
|
||||
Серверный `await` — базовая стратегия для данных, которые нужны до рендера страницы или серверного блока.
|
||||
|
||||
## Когда использовать
|
||||
|
||||
- Данные нужны для первого HTML.
|
||||
- Данные влияют на `metadata`.
|
||||
- По результату запроса нужно вызвать `notFound()` или `redirect()`.
|
||||
- Компонент серверный и данные не зависят от состояния браузера.
|
||||
|
||||
## Влияние на рендер
|
||||
|
||||
Серверный `await` сам по себе не означает SSR. В App Router страница может остаться static/ISR, если маршрут не использует dynamic API и запросы можно кешировать.
|
||||
|
||||
ISR — приоритет для общих данных. Если список или детальная страница могут обновляться по интервалу, сохраняйте кеширование и не добавляйте `no-store`, `revalidate: 0` или `force-dynamic` без требования.
|
||||
|
||||
SSR/dynamic rendering нужен, когда данные зависят от текущего request: cookie, headers, `searchParams`, preview-режим или персональные данные пользователя.
|
||||
|
||||
## Пример страницы списка
|
||||
|
||||
```tsx
|
||||
// src/app/(routes)/pets/page.tsx
|
||||
import { petStoreApi } from 'infrastructure/pet-store-api'
|
||||
import { PetsScreen } from 'screens/pets'
|
||||
|
||||
export default async function PetsPage() {
|
||||
const pets = await petStoreApi.pet.findPetsByStatus({
|
||||
status: 'available',
|
||||
})
|
||||
|
||||
return <PetsScreen pets={pets} />
|
||||
}
|
||||
```
|
||||
|
||||
`page.tsx` получает данные первого рендера и передаёт их ниже. UI страницы остаётся в `screens/`, а не пишется прямо в `app/`.
|
||||
|
||||
## Пример детальной страницы
|
||||
|
||||
```tsx
|
||||
// src/app/(routes)/pets/[id]/page.tsx
|
||||
import { notFound } from 'next/navigation'
|
||||
import { petStoreApi } from 'infrastructure/pet-store-api'
|
||||
import { PetDetailScreen } from 'screens/pet-detail'
|
||||
|
||||
type PetPageProps = {
|
||||
params: Promise<{ id: string }>
|
||||
}
|
||||
|
||||
export default async function PetPage({ params }: PetPageProps) {
|
||||
const { id } = await params
|
||||
const pet = await petStoreApi.pet.getPetById(Number(id)).catch(() => null)
|
||||
|
||||
if (!pet) {
|
||||
notFound()
|
||||
}
|
||||
|
||||
return <PetDetailScreen pet={pet} />
|
||||
}
|
||||
```
|
||||
|
||||
Обработка 404 зависит от API-клиента и класса ошибок. В примере показана идея: решение о `notFound()` принимается на уровне маршрута, а не внутри REST-клиента.
|
||||
|
||||
## Что не делать
|
||||
|
||||
```tsx
|
||||
// Плохо — хуки нельзя вызывать в Server Component
|
||||
const { data } = useGetPetList('available')
|
||||
|
||||
// Плохо — прямой fetch в обход клиента
|
||||
const response = await fetch('https://petstore3.swagger.io/api/v3/pet/findByStatus')
|
||||
```
|
||||
|
||||
Если данные нужны на сервере, вызывайте метод REST-клиента напрямую.
|
||||
|
||||
## Когда выбрать другую стратегию
|
||||
|
||||
- Несколько независимых запросов — [Параллельные серверные запросы](./parallel-server-requests.md).
|
||||
- Часть UI можно грузить отдельно — [Передача промиса ниже](./pass-promise-down.md).
|
||||
- Данные нужны клиентскому хуку сразу после гидрации — [Начальные данные для клиентских хуков](./client-hooks-initial-data.md).
|
||||
8
ai/nextjs-style-guide/workflow.md
Normal file
8
ai/nextjs-style-guide/workflow.md
Normal file
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: Подсказки
|
||||
description: Короткие ответы на типовые вопросы и решения для спорных ситуаций.
|
||||
---
|
||||
|
||||
# Подсказки
|
||||
|
||||
Короткие ответы на типовые вопросы и решения для спорных ситуаций.
|
||||
@@ -33,6 +33,9 @@
|
||||
"recommended": true,
|
||||
"suspicious": {
|
||||
"noUnknownAtRules": "off"
|
||||
},
|
||||
"correctness": {
|
||||
"noUnknownMediaFeatureName": "off"
|
||||
}
|
||||
},
|
||||
"domains": {
|
||||
|
||||
497
package-lock.json
generated
497
package-lock.json
generated
File diff suppressed because it is too large
Load Diff
11
package.json
11
package.json
@@ -8,9 +8,12 @@
|
||||
"start": "next start",
|
||||
"lint": "biome check",
|
||||
"format": "biome format --write",
|
||||
"sprite": "node scripts/create-svg-sprite.js"
|
||||
"sprite": "svg-sprites",
|
||||
"predev": "svg-sprites",
|
||||
"prebuild": "svg-sprites"
|
||||
},
|
||||
"dependencies": {
|
||||
"@gromlab/svg-sprites": "^0.1.4",
|
||||
"@mantine/core": "^8.3.18",
|
||||
"@mantine/hooks": "^8.3.18",
|
||||
"clsx": "^2.1.1",
|
||||
@@ -22,13 +25,15 @@
|
||||
},
|
||||
"devDependencies": {
|
||||
"@biomejs/biome": "2.2.0",
|
||||
"@csstools/postcss-global-data": "^4.0.0",
|
||||
"@types/node": "^20",
|
||||
"@types/react": "^19",
|
||||
"@types/react-dom": "^19",
|
||||
"colorette": "^2.0.20",
|
||||
"autoprefixer": "^10.5.0",
|
||||
"postcss-custom-media": "^12.0.1",
|
||||
"postcss-nesting": "^14.0.0",
|
||||
"postcss-preset-mantine": "^1.18.0",
|
||||
"postcss-simple-vars": "^7.0.1",
|
||||
"svg-sprite": "^2.0.4",
|
||||
"typescript": "^5"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,6 +1,10 @@
|
||||
/** @type {import('postcss-load-config').Config} */
|
||||
const config = {
|
||||
plugins: {
|
||||
'@csstools/postcss-global-data': {
|
||||
files: ['src/shared/styles/media.css'],
|
||||
},
|
||||
'postcss-custom-media': {},
|
||||
'postcss-preset-mantine': {},
|
||||
'postcss-simple-vars': {
|
||||
variables: {
|
||||
@@ -11,6 +15,8 @@ const config = {
|
||||
'mantine-breakpoint-xl': '88em',
|
||||
},
|
||||
},
|
||||
'postcss-nesting': {},
|
||||
autoprefixer: {},
|
||||
},
|
||||
};
|
||||
|
||||
|
||||
@@ -1,161 +0,0 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>SVG stack preview | svg-sprite</title>
|
||||
<style>
|
||||
body {
|
||||
padding: 0;
|
||||
margin: 0;
|
||||
color: #666;
|
||||
background: #fafafa;
|
||||
font-family: Arial, Helvetica, sans-serif;
|
||||
font-size: 1em;
|
||||
line-height: 1.4;
|
||||
}
|
||||
|
||||
header {
|
||||
display: block;
|
||||
padding: 3em 3em 2em;
|
||||
background-color: #fff;
|
||||
}
|
||||
|
||||
header p {
|
||||
margin: 2em 0 0;
|
||||
}
|
||||
|
||||
section {
|
||||
border-top: 1px solid #eee;
|
||||
padding: 2em 3em 0;
|
||||
}
|
||||
|
||||
section ul {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
section li {
|
||||
display: inline-block;
|
||||
background-color: #fff;
|
||||
position: relative;
|
||||
margin: 0 2em 2em 0;
|
||||
vertical-align: top;
|
||||
border: 1px solid #ccc;
|
||||
padding: 1em 1em 3em;
|
||||
cursor: default;
|
||||
}
|
||||
|
||||
.icon-box {
|
||||
margin: 0;
|
||||
width: 144px;
|
||||
height: 144px;
|
||||
position: relative;
|
||||
background: #ccc url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12'%3E%3Cpath fill='%23fff' d='M6 0h6v6H6zM0 6h6v6H0z'/%3E%3C/svg%3E") top left repeat;
|
||||
border: 1px solid #ccc;
|
||||
display: table-cell;
|
||||
vertical-align: middle;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
.icon {
|
||||
display: inline-block;
|
||||
}
|
||||
|
||||
h1 {
|
||||
margin-top: 0;
|
||||
}
|
||||
|
||||
h2 {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
font-size: 1em;
|
||||
font-weight: 400;
|
||||
white-space: nowrap;
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
position: absolute;
|
||||
left: 1em;
|
||||
right: 1em;
|
||||
bottom: 1em;
|
||||
}
|
||||
|
||||
footer {
|
||||
display: block;
|
||||
margin: 0;
|
||||
padding: 0 3em 3em;
|
||||
}
|
||||
|
||||
footer p {
|
||||
margin: 0;
|
||||
font-size: .7em;
|
||||
}
|
||||
|
||||
footer a {
|
||||
color: #0f7595;
|
||||
margin-left: 0;
|
||||
}
|
||||
</style>
|
||||
|
||||
<!--
|
||||
Sprite shape dimensions
|
||||
====================================================================================================
|
||||
You will need to set the sprite shape dimensions via CSS when you use them as stack SVGs, otherwise
|
||||
they would become a huge 100% in size. You may use the following dimension classes for doing so.
|
||||
They might well be outsourced to an external stylesheet of course.
|
||||
-->
|
||||
|
||||
<style>
|
||||
.svg-arrow-down-dims { width: 24px; height: 24px; }
|
||||
.svg-arrow-right-dims { width: 20px; height: 20px; }
|
||||
</style>
|
||||
|
||||
<!--
|
||||
====================================================================================================
|
||||
-->
|
||||
|
||||
</head>
|
||||
<body>
|
||||
<header>
|
||||
<h1>SVG stack preview</h1>
|
||||
<p>This preview features an SVG stack. Please have a look at the HTML source for further details and be aware of the following constraints:</p>
|
||||
<ul>
|
||||
<li>Your browser has to <a href="https://caniuse.com/svg-fragment" target="_blank" rel="noopener noreferrer">support SVG fragment identifiers</a> for SVG stacks to work.</li>
|
||||
<li>Support for SVG fragment identifiers hasn't always been that decent. For older browsers you will have to use some prolyfill like <a href="https://github.com/preciousforever/SVG-Stacker/blob/master/fixsvgstack.jquery.js" target="_blank" rel="noopener noreferrer">fixsvgstack.jquery.js</a>.</li>
|
||||
</ul>
|
||||
</header>
|
||||
<section>
|
||||
|
||||
<!--
|
||||
SVG stack
|
||||
====================================================================================================
|
||||
These SVG images make use of fragment identifiers (IDs) to reference certain portions of the
|
||||
external sprite. By default, all shapes inside the sprite are hidden by CSS. The `:target` pseudo
|
||||
selector is used to show the very shape that is referenced by the fragment identifier.
|
||||
-->
|
||||
|
||||
<ul>
|
||||
|
||||
<li title="arrow-down">
|
||||
<div class="icon-box">
|
||||
<img src="sprite.stack.svg#arrow-down" class="svg-arrow-down-dims" alt="arrow-down">
|
||||
</div>
|
||||
<h2>arrow-down, </h2>
|
||||
</li>
|
||||
<li title="arrow-right">
|
||||
<div class="icon-box">
|
||||
<img src="sprite.stack.svg#arrow-right" class="svg-arrow-right-dims" alt="arrow-right">
|
||||
</div>
|
||||
<h2>arrow-right, </h2>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<!--
|
||||
====================================================================================================
|
||||
-->
|
||||
|
||||
</section>
|
||||
<footer>
|
||||
<p>Generated at Tue, 21 Apr 2026 18:16:57 GMT by <a href="https://github.com/svg-sprite/svg-sprite" target="_blank" rel="noopener noreferrer">svg-sprite</a>.</p>
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1 +0,0 @@
|
||||
<?xml version="1.0" encoding="utf-8"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"><style>:root>svg{display:none}:root>svg:target{display:block}</style><svg viewBox="0 0 24 24" fill="none" id="arrow-down" xmlns="http://www.w3.org/2000/svg"><path d="M18.07 14.43 12 20.5l-6.07-6.07M12 3.5v16.83" stroke="var(--icon-color-1, currentColor)" stroke-width="1.5" stroke-miterlimit="10" stroke-linecap="round" stroke-linejoin="round"/></svg><svg viewBox="0 0 20 20" fill="none" id="arrow-right" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M18.25 10a.75.75 0 0 1-.22.53l-5.833 5.834a.75.75 0 1 1-1.06-1.06l4.553-4.554H1.667a.75.75 0 0 1 0-1.5H15.69l-4.553-4.553a.75.75 0 0 1 1.06-1.06l5.834 5.833c.14.14.22.331.22.53Z" fill="var(--icon-color-1, currentColor)"/></svg></svg>
|
||||
|
Before Width: | Height: | Size: 843 B |
@@ -1,126 +0,0 @@
|
||||
/**
|
||||
* Генерация SVG-спрайтов и TypeScript-типов имён иконок.
|
||||
*
|
||||
* Читает подпапки из ASSETS_DIR, для каждой собирает SVG в спрайт (stack или symbol)
|
||||
* и генерирует .generated.ts файл с union-типом имён иконок.
|
||||
*
|
||||
* Режим спрайта определяется суффиксом папки: «icons?symbol» → symbol, иначе stack.
|
||||
*
|
||||
* Запуск: npm run sprite
|
||||
*/
|
||||
const fs = require('fs')
|
||||
const path = require('path')
|
||||
const SVGSpriter = require('svg-sprite')
|
||||
const color = require('colorette')
|
||||
|
||||
const ROOT = process.cwd()
|
||||
|
||||
/** Папка с исходными SVG-файлами. */
|
||||
const ASSETS_DIR = path.join(ROOT, 'src/shared/sprites')
|
||||
|
||||
/** Папка для сгенерированных спрайтов. */
|
||||
const DEST_DIR = path.join(ROOT, 'public/img/sprites')
|
||||
|
||||
/**
|
||||
* Преобразует kebab-case строку в PascalCase.
|
||||
*/
|
||||
const toPascalCase = (str) =>
|
||||
str.replace(/(^|[-_])([a-z])/g, (_, __, c) => c.toUpperCase())
|
||||
|
||||
/**
|
||||
* Возвращает конфигурацию режима для svg-sprite.
|
||||
*/
|
||||
const getModeConfig = (mode, destDir) => ({
|
||||
dest: destDir,
|
||||
sprite: `sprite.${mode}.svg`,
|
||||
example: true,
|
||||
rootviewbox: false,
|
||||
})
|
||||
|
||||
/**
|
||||
* Генерирует TypeScript-файл с union-типом имён иконок спрайта.
|
||||
*/
|
||||
const generateIconNames = (folderName, svgFiles) => {
|
||||
const names = svgFiles
|
||||
.map((filePath) => path.basename(filePath, '.svg'))
|
||||
.sort()
|
||||
|
||||
const typeName = `${toPascalCase(folderName)}IconName`
|
||||
|
||||
const content = [
|
||||
'/**',
|
||||
` * Имена иконок спрайта «${folderName}».`,
|
||||
' * @generated — файл создан автоматически (npm run sprite), не редактировать вручную.',
|
||||
' */',
|
||||
`export type ${typeName} =`,
|
||||
names.map((name) => ` | '${name}'`).join('\n'),
|
||||
'',
|
||||
].join('\n')
|
||||
|
||||
const outputPath = path.join(ASSETS_DIR, `${folderName}.generated.ts`)
|
||||
fs.writeFileSync(outputPath, content)
|
||||
console.log(
|
||||
color.green(`Generated types: ${folderName}.generated.ts (${names.length} icons)`),
|
||||
)
|
||||
}
|
||||
|
||||
/**
|
||||
* Обрабатывает одну папку со спрайтами.
|
||||
*/
|
||||
const processFolder = (fullFolderName) => {
|
||||
const folderPath = path.join(ASSETS_DIR, fullFolderName)
|
||||
|
||||
if (!fs.lstatSync(folderPath).isDirectory()) {
|
||||
return
|
||||
}
|
||||
|
||||
const hasCustomMode = fullFolderName.includes('?')
|
||||
const parts = fullFolderName.split('?')
|
||||
const mode = hasCustomMode ? parts.pop() : 'stack'
|
||||
const folderName = parts[0]
|
||||
|
||||
const svgFiles = fs
|
||||
.readdirSync(folderPath)
|
||||
.filter((file) => file.endsWith('.svg'))
|
||||
.map((file) => path.join(folderPath, file))
|
||||
|
||||
if (!svgFiles.length) {
|
||||
return
|
||||
}
|
||||
|
||||
const config = {
|
||||
log: 'debug',
|
||||
mode: {
|
||||
[mode]: getModeConfig(mode, path.join(DEST_DIR, folderName)),
|
||||
},
|
||||
}
|
||||
|
||||
const spriter = new SVGSpriter(config)
|
||||
|
||||
for (const fileName of svgFiles) {
|
||||
spriter.add(fileName, null, fs.readFileSync(fileName, 'utf-8'))
|
||||
}
|
||||
|
||||
spriter.compile((error, result) => {
|
||||
if (error) {
|
||||
console.log(color.red(error.message))
|
||||
return
|
||||
}
|
||||
|
||||
for (const modeResult of Object.values(result)) {
|
||||
for (const resource of Object.values(modeResult)) {
|
||||
fs.mkdirSync(path.dirname(resource.path), { recursive: true })
|
||||
fs.writeFileSync(resource.path, resource.contents)
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
generateIconNames(folderName, svgFiles)
|
||||
}
|
||||
|
||||
try {
|
||||
const entries = fs.readdirSync(ASSETS_DIR)
|
||||
entries.forEach(processFolder)
|
||||
} catch (err) {
|
||||
console.log(color.red(err.message))
|
||||
}
|
||||
@@ -1,9 +1,10 @@
|
||||
import '@mantine/core/styles.css';
|
||||
import 'shared/styles/global.css';
|
||||
|
||||
import { ColorSchemeScript } from '@mantine/core';
|
||||
import { MantineProvider } from 'infrastructure/mantine';
|
||||
import type { Metadata } from 'next';
|
||||
import type { PropsWithChildren } from 'react';
|
||||
import { MantineProvider } from './providers';
|
||||
import '@mantine/core/styles.css';
|
||||
import './styles/index.css';
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: {
|
||||
@@ -35,6 +36,7 @@ export default function RootLayout({ children }: PropsWithChildren) {
|
||||
<html lang="ru" suppressHydrationWarning>
|
||||
<head>
|
||||
<ColorSchemeScript />
|
||||
<link rel="preload" href="/sprites/icons.sprite.svg" as="image" />
|
||||
</head>
|
||||
<body>
|
||||
<MantineProvider>{children}</MantineProvider>
|
||||
|
||||
@@ -1,3 +0,0 @@
|
||||
@import "./variables.css";
|
||||
@import "./media.css";
|
||||
@import "./reset.css";
|
||||
@@ -1,6 +0,0 @@
|
||||
/* Медиа-запросы (Mobile First) */
|
||||
@custom-media --xs (min-width: 36em);
|
||||
@custom-media --sm (min-width: 48em);
|
||||
@custom-media --md (min-width: 62em);
|
||||
@custom-media --lg (min-width: 75em);
|
||||
@custom-media --xl (min-width: 88em);
|
||||
@@ -1,35 +0,0 @@
|
||||
/* Цвета */
|
||||
:root {
|
||||
--color-text: #1a1a1a;
|
||||
--color-text-secondary: #6b7280;
|
||||
--color-bg: #ffffff;
|
||||
--color-bg-secondary: #f9fafb;
|
||||
--color-border: #e5e7eb;
|
||||
--color-primary: #228be6;
|
||||
--color-error: #fa5252;
|
||||
--color-success: #40c057;
|
||||
--color-warning: #fab005;
|
||||
}
|
||||
|
||||
/* Отступы */
|
||||
:root {
|
||||
--space-1: 4px;
|
||||
--space-2: 8px;
|
||||
--space-3: 12px;
|
||||
--space-4: 16px;
|
||||
--space-5: 20px;
|
||||
--space-6: 24px;
|
||||
--space-8: 32px;
|
||||
--space-10: 40px;
|
||||
--space-12: 48px;
|
||||
--space-16: 64px;
|
||||
}
|
||||
|
||||
/* Скругления */
|
||||
:root {
|
||||
--radius-1: 4px;
|
||||
--radius-2: 8px;
|
||||
--radius-3: 12px;
|
||||
--radius-4: 16px;
|
||||
--radius-full: 9999px;
|
||||
}
|
||||
@@ -2,8 +2,4 @@
|
||||
display: flex;
|
||||
align-items: center;
|
||||
min-height: 100vh;
|
||||
|
||||
@media (--md) {
|
||||
display: none;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,7 +0,0 @@
|
||||
/**
|
||||
* Имена иконок спрайта «icons».
|
||||
* @generated — файл создан автоматически (npm run sprite), не редактировать вручную.
|
||||
*/
|
||||
export type IconsIconName =
|
||||
| 'arrow-down'
|
||||
| 'arrow-right'
|
||||
@@ -1,4 +0,0 @@
|
||||
<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<path d="M18.0701 14.4301L12.0001 20.5001L5.93005 14.4301" stroke="var(--icon-color-1, currentColor)" stroke-width="1.5" stroke-miterlimit="10" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
<path d="M12 3.5V20.33" stroke="var(--icon-color-1, currentColor)" stroke-width="1.5" stroke-miterlimit="10" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 431 B |
@@ -1,3 +0,0 @@
|
||||
<svg viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<path fill-rule="evenodd" clip-rule="evenodd" d="M18.2503 10.0003C18.2503 10.1992 18.1713 10.39 18.0307 10.5307L12.1973 16.364C11.9044 16.6569 11.4296 16.6569 11.1367 16.364C10.8438 16.0711 10.8438 15.5962 11.1367 15.3033L15.6897 10.7503L1.66699 10.7503C1.25278 10.7503 0.916992 10.4145 0.916992 10.0003C0.916992 9.58611 1.25278 9.25033 1.66699 9.25033L15.6897 9.25033L11.1367 4.69732C10.8438 4.40443 10.8438 3.92956 11.1367 3.63666C11.4296 3.34377 11.9044 3.34377 12.1973 3.63666L18.0307 9.47C18.1713 9.61065 18.2503 9.80141 18.2503 10.0003Z" fill="var(--icon-color-1, currentColor)"/>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 667 B |
5
src/shared/sprites/icons/clipboard-tick.svg
Normal file
5
src/shared/sprites/icons/clipboard-tick.svg
Normal file
@@ -0,0 +1,5 @@
|
||||
<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<path d="M13.965 22.05L16.215 24.3L22.215 18.3" stroke="#A93133" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
<path d="M15 9H21C24 9 24 7.5 24 6C24 3 22.5 3 21 3H15C13.5 3 12 3 12 6C12 9 13.5 9 15 9Z" stroke="#A93133" stroke-width="1.5" stroke-miterlimit="10" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
<path d="M24 6.03003C28.995 6.30003 31.5 8.14503 31.5 15V24C31.5 30 30 33 22.5 33H13.5C6 33 4.5 30 4.5 24V15C4.5 8.16003 7.005 6.30003 12 6.03003" stroke="#A93133" stroke-width="1.5" stroke-miterlimit="10" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 690 B |
3
src/shared/sprites/icons/doctor.svg
Normal file
3
src/shared/sprites/icons/doctor.svg
Normal file
@@ -0,0 +1,3 @@
|
||||
<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<path d="M9 6H7.5C6.70435 6 5.94129 6.31607 5.37868 6.87868C4.81607 7.44129 4.5 8.20435 4.5 9V14.25C4.5 16.438 5.36919 18.5365 6.91637 20.0836C8.46354 21.6308 10.562 22.5 12.75 22.5C14.938 22.5 17.0365 21.6308 18.5836 20.0836C20.1308 18.5365 21 16.438 21 14.25V9C21 8.20435 20.6839 7.44129 20.1213 6.87868C19.5587 6.31607 18.7956 6 18 6H16.5M12 22.5C12 23.6819 12.2328 24.8522 12.6851 25.9442C13.1374 27.0361 13.8003 28.0282 14.636 28.864C15.4718 29.6997 16.4639 30.3626 17.5558 30.8149C18.6478 31.2672 19.8181 31.5 21 31.5C22.1819 31.5 23.3522 31.2672 24.4442 30.8149C25.5361 30.3626 26.5282 29.6997 27.364 28.864C28.1997 28.0282 28.8626 27.0361 29.3149 25.9442C29.7672 24.8522 30 23.6819 30 22.5V18M30 18C29.2044 18 28.4413 17.6839 27.8787 17.1213C27.3161 16.5587 27 15.7956 27 15C27 14.2044 27.3161 13.4413 27.8787 12.8787C28.4413 12.3161 29.2044 12 30 12C30.7956 12 31.5587 12.3161 32.1213 12.8787C32.6839 13.4413 33 14.2044 33 15C33 15.7956 32.6839 16.5587 32.1213 17.1213C31.5587 17.6839 30.7956 18 30 18ZM16.5 4.5V7.5M9 4.5V7.5" stroke="#A93133" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 1.2 KiB |
3
src/shared/sprites/icons/people.svg
Normal file
3
src/shared/sprites/icons/people.svg
Normal file
@@ -0,0 +1,3 @@
|
||||
<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<path d="M25.455 21.66C27.51 22.005 29.775 21.645 31.365 20.58C33.48 19.17 33.48 16.86 31.365 15.45C29.76 14.385 27.465 14.025 25.41 14.385M10.5 21.66C8.44503 22.005 6.18003 21.645 4.59003 20.58C2.47503 19.17 2.47503 16.86 4.59003 15.45C6.19503 14.385 8.49003 14.025 10.545 14.385M27 10.74C26.91 10.725 26.805 10.725 26.715 10.74C24.645 10.665 22.995 8.97 22.995 6.87C22.995 4.725 24.72 3 26.865 3C29.01 3 30.735 4.74 30.735 6.87C30.72 8.97 29.07 10.665 27 10.74ZM8.95503 10.74C9.04503 10.725 9.15003 10.725 9.24003 10.74C11.31 10.665 12.96 8.97 12.96 6.87C12.96 4.725 11.235 3 9.09003 3C6.94503 3 5.22003 4.74 5.22003 6.87C5.23503 8.97 6.88503 10.665 8.95503 10.74ZM18 21.945C17.91 21.93 17.805 21.93 17.715 21.945C15.645 21.87 13.995 20.175 13.995 18.075C13.995 15.93 15.72 14.205 17.865 14.205C20.01 14.205 21.735 15.945 21.735 18.075C21.72 20.175 20.07 21.885 18 21.945ZM13.635 26.67C11.52 28.08 11.52 30.39 13.635 31.8C16.035 33.405 19.965 33.405 22.365 31.8C24.48 30.39 24.48 28.08 22.365 26.67C19.98 25.08 16.035 25.08 13.635 26.67Z" stroke="#A93133" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 1.2 KiB |
5
src/shared/sprites/icons/symptom.svg
Normal file
5
src/shared/sprites/icons/symptom.svg
Normal file
@@ -0,0 +1,5 @@
|
||||
<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<path fill-rule="evenodd" clip-rule="evenodd" d="M31.0013 17.0006V17.0006C31.0013 24.7331 24.7331 31.0013 17.0006 31.0013V31.0013C9.26812 31.0013 3 24.7331 3 17.0006V17.0006C3 9.26812 9.26812 3 17.0006 3V3C24.7331 3 31.0013 9.26812 31.0013 17.0006Z" stroke="#A93133" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
<path d="M33 33L26.9062 26.9062" stroke="#A93133" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
<path d="M3 17.0007H9.04125L12.1669 12.3132L16.3331 21.6882L19.4587 17.0007H23.625" stroke="#A93133" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 725 B |
8
src/shared/styles/global.css
Normal file
8
src/shared/styles/global.css
Normal file
@@ -0,0 +1,8 @@
|
||||
@import "./variables.css";
|
||||
@import "./reset.css";
|
||||
|
||||
/* Сюда же подключаются будущие глобалы через @import:
|
||||
* @import './typography.css';
|
||||
* @import './themes.css';
|
||||
* media.css НЕ импортируется — он работает через PostCSS.
|
||||
*/
|
||||
@@ -1,15 +1,17 @@
|
||||
@custom-media --xs (max-width: 575px);
|
||||
@custom-media --sm (min-width: 576px);
|
||||
@custom-media --md (min-width: 768px);
|
||||
@custom-media --lg (min-width: 992px);
|
||||
@custom-media --xl (min-width: 1200px);
|
||||
@custom-media --2xl (min-width: 1408px);
|
||||
@custom-media --3xl (min-width: 1920px);
|
||||
/* Ширина — Mobile First (min-width), кроме --xs (max-width) */
|
||||
@custom-media --xs (max-width: 35.9375rem);
|
||||
@custom-media --sm (min-width: 36rem);
|
||||
@custom-media --md (min-width: 48rem);
|
||||
@custom-media --lg (min-width: 62rem);
|
||||
@custom-media --xl (min-width: 75rem);
|
||||
@custom-media --2xl (min-width: 88rem);
|
||||
@custom-media --3xl (min-width: 120rem);
|
||||
|
||||
@custom-media --h-xs (min-height: 667px);
|
||||
@custom-media --h-sm (min-height: 702px);
|
||||
@custom-media --h-md (min-height: 810px);
|
||||
@custom-media --h-lg (min-height: 900px);
|
||||
@custom-media --h-xl (min-height: 1000px);
|
||||
@custom-media --h-xxl (min-height: 1100px);
|
||||
@custom-media --h-xxxl (min-height: 1200px);
|
||||
/* Высота — min-height */
|
||||
@custom-media --h-xs (min-height: 41.6875rem);
|
||||
@custom-media --h-sm (min-height: 43.875rem);
|
||||
@custom-media --h-md (min-height: 50.625rem);
|
||||
@custom-media --h-lg (min-height: 56.25rem);
|
||||
@custom-media --h-xl (min-height: 62.5rem);
|
||||
@custom-media --h-2xl (min-height: 68.75rem);
|
||||
@custom-media --h-3xl (min-height: 75rem);
|
||||
|
||||
@@ -1,4 +1,3 @@
|
||||
/* Базовые стили */
|
||||
html {
|
||||
height: 100%;
|
||||
}
|
||||
@@ -1,102 +1,31 @@
|
||||
:root {
|
||||
/* ========================================
|
||||
* Цвета
|
||||
* ======================================== */
|
||||
|
||||
/* Фоновые */
|
||||
/* Цвета */
|
||||
--color-primary: #3b82f6;
|
||||
--color-bg: #ffffff;
|
||||
--color-bg-hero: #edf3f9;
|
||||
--color-bg-accent: #f2f8fa;
|
||||
--color-bg-dark: #08050d;
|
||||
--color-bg-hover: #f5f5f5;
|
||||
--color-text: #1a1a1a;
|
||||
--color-text-secondary: #6b7280;
|
||||
--color-border: #e5e7eb;
|
||||
--color-error: #fa5252;
|
||||
--color-success: #40c057;
|
||||
--color-warning: #fab005;
|
||||
|
||||
/* Текстовые */
|
||||
--color-text: #08050d;
|
||||
--color-text-secondary: #4e5566;
|
||||
--color-text-tertiary: #8a8f9c;
|
||||
|
||||
/* Бордеры */
|
||||
--color-border: #d9dde5;
|
||||
--color-border-light: #e8ebf3;
|
||||
|
||||
/* Скроллбар */
|
||||
--color-scrollbar: #e1eff4;
|
||||
|
||||
/* Акцент */
|
||||
--color-accent: #129d9d;
|
||||
|
||||
/* ========================================
|
||||
* Шрифты
|
||||
* ======================================== */
|
||||
--font-display: 'Biocad Display', sans-serif;
|
||||
--font-serif: 'Lora', serif;
|
||||
--font-sans: 'Noto Sans', sans-serif;
|
||||
|
||||
/* ========================================
|
||||
* Отступы
|
||||
* ======================================== */
|
||||
/* Отступы */
|
||||
--space-1: 4px;
|
||||
--space-2: 8px;
|
||||
--space-3: 12px;
|
||||
--space-4: 16px;
|
||||
--space-5: 20px;
|
||||
--space-6: 24px;
|
||||
--space-7: 28px;
|
||||
--space-8: 32px;
|
||||
--space-9: 36px;
|
||||
--space-10: 40px;
|
||||
--space-11: 44px;
|
||||
--space-12: 48px;
|
||||
--space-13: 52px;
|
||||
--space-14: 56px;
|
||||
--space-15: 60px;
|
||||
--space-16: 64px;
|
||||
--space-17: 68px;
|
||||
--space-18: 72px;
|
||||
--space-19: 76px;
|
||||
--space-20: 80px;
|
||||
--space-21: 84px;
|
||||
--space-22: 88px;
|
||||
--space-23: 92px;
|
||||
--space-24: 96px;
|
||||
--space-25: 100px;
|
||||
--space-26: 104px;
|
||||
--space-27: 108px;
|
||||
--space-28: 112px;
|
||||
--space-29: 116px;
|
||||
--space-30: 120px;
|
||||
--space-31: 124px;
|
||||
--space-32: 128px;
|
||||
--space-33: 132px;
|
||||
--space-34: 136px;
|
||||
--space-35: 140px;
|
||||
--space-36: 144px;
|
||||
--space-37: 148px;
|
||||
--space-38: 152px;
|
||||
--space-39: 156px;
|
||||
--space-40: 160px;
|
||||
--space-41: 164px;
|
||||
--space-42: 168px;
|
||||
--space-43: 172px;
|
||||
--space-44: 176px;
|
||||
--space-45: 180px;
|
||||
--space-46: 184px;
|
||||
--space-47: 188px;
|
||||
--space-48: 192px;
|
||||
--space-49: 196px;
|
||||
--space-50: 200px;
|
||||
|
||||
/* ========================================
|
||||
* Скругления
|
||||
* ======================================== */
|
||||
--radius-1: 12px;
|
||||
--radius-2: 18px;
|
||||
--radius-3: 24px;
|
||||
--radius-4: 36px;
|
||||
--radius-full: 800px;
|
||||
|
||||
/* ========================================
|
||||
* Layout
|
||||
* ======================================== */
|
||||
--content-width: 1728px;
|
||||
--content-padding: 48px;
|
||||
/* Скругления */
|
||||
--radius-1: 4px;
|
||||
--radius-2: 8px;
|
||||
--radius-3: 12px;
|
||||
--radius-4: 16px;
|
||||
--radius-full: 9999px;
|
||||
}
|
||||
|
||||
8
svg-sprites.config.ts
Normal file
8
svg-sprites.config.ts
Normal file
@@ -0,0 +1,8 @@
|
||||
import { defineConfig } from '@gromlab/svg-sprites';
|
||||
|
||||
export default defineConfig({
|
||||
output: 'public/sprites',
|
||||
publicPath: '/sprites',
|
||||
react: 'src/ui/svg-sprite',
|
||||
sprites: [{ name: 'icons', input: 'src/shared/sprites/icons' }],
|
||||
});
|
||||
@@ -25,7 +25,7 @@
|
||||
"layouts/*": ["./src/layouts/*"],
|
||||
"screens/*": ["./src/screens/*"],
|
||||
"ui/*": ["./src/ui/*"],
|
||||
"shared/*": ["./src/ui/*"]
|
||||
"shared/*": ["./src/shared/*"]
|
||||
}
|
||||
},
|
||||
"include": [
|
||||
|
||||
Reference in New Issue
Block a user