docs/nextjs-style-guide
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: объединены 9 страниц workflow в один файл
All checks were successful
CI/CD Pipeline / docker (push) Successful in 40s
Details
CI/CD Pipeline / deploy (push) Successful in 6s
Details

Browse Source 
- Создан единый docs/ru/workflow.md с форматом: заголовок, описание, этапы, комментарий
- Пересобраны generated/ru/RULES.md и generated/en/RULES.md
- Старые файлы в docs/ru/workflow/ сохранены, но убраны из навигации
This commit is contained in:
S.Gromov
2026-03-29 14:04:25 +03:00
parent 93684be5bd
commit dadfa83df5
3 changed files with 154 additions and 166 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
docs/ru/workflow.md Normal file
View File

@@ -0,0 +1,95 @@
---
title: Workflow
---
# Workflow
Порядок действий при разработке — от создания проекта до реализации фич.
## Начало работы
Подготовка окружения перед началом разработки.
1. Открыть проект в VS Code.
2. Установить рекомендуемые расширения (редактор предложит автоматически).
3. Ознакомиться со стеком: Next.js (App Router), Mantine, Zustand, FSD.
## Создание проекта
Инициализация нового проекта из готового шаблона.
1. Создать проект из шаблона:
```bash
npx tiged git@gromlab.ru:templates/nextjs.git my-app
cd my-app
npm install
```
2. Проект готов к разработке — стек, структура FSD, конфигурация
редактора и шаблоны генерации уже настроены.
## Генерация кода
Создание модулей из шаблонов `.templates/` вместо ручного создания файлов.
1. Определить тип модуля и соответствующий шаблон:
| Модуль | Слой | Шаблон |
|------------|--------------|-------------|
| Компонент | `shared/ui/` | `component` |
| Фича | `features/` | `feature` |
| Виджет | `widgets/` | `widget` |
| Сущность | `entities/` | `entity` |
| Layout | `layouts/` | `layout` |
| Экран | `screens/` | `screen` |
| Стор | `model/` | `store` |
2. Сгенерировать модуль из шаблона.
3. Если подходящего шаблона нет — сначала создать шаблон, затем использовать.
Ручное создание файловой структуры модулей запрещено.
## Добавление страницы
Создание нового маршрута: экран + точка входа для роутинга.
1. Сгенерировать экран из шаблона `screen` в `src/screens/`.
2. Заполнить экран логикой и стилями.
3. Создать `page.tsx` в нужном маршруте `src/app/`.
`page.tsx` — тонкая обёртка: только `metadata` и рендер экрана.
Логика, стили и хуки размещаются в экране, не в `page.tsx`.
## Добавление UI-модуля
Создание компонента, фичи, виджета, сущности или layout.
1. Сгенерировать модуль из соответствующего шаблона в целевой слой.
2. Заполнить модуль логикой и стилями.
3. Дочерние компоненты — генерировать из шаблона `component` в папку `ui/`
внутри родителя.
Дочерние компоненты не экспортируются через `index.ts` родителя.
## Стилизация
Выбор инструмента стилизации по приоритету.
1. Использовать Mantine-компоненты и их пропсы.
2. Если Mantine не покрывает — использовать CSS-токены
(`--color-*`, `--space-*`, `--radius-*`).
3. Если нужна кастомная стилизация — PostCSS Modules.
Инлайн-стили (`style`), магические значения и глобальные стили
вне `app/styles/` запрещены.
## Получение данных
*Раздел в разработке* — SWR, генерация API-клиентов, сокеты.
## Управление состоянием
*Раздел в разработке* — когда создавать стор, что хранить локально и глобально.
## Локализация
*Раздел в разработке* — переводы и i18next.

40
generated/en/RULES.md
View File

@@ -57,46 +57,6 @@ Rules and standards for NextJS and TypeScript development: architecture, typing,
Full documentation in a single MD file: https://gromlab.ru/docs/frontend-style-guide/raw/branch/main/generated/en/RULES.md Full documentation in a single MD file: https://gromlab.ru/docs/frontend-style-guide/raw/branch/main/generated/en/RULES.md
<!-- /workflow/getting-started -->
## Getting Started
Setting up the environment and installing tools before starting development.
<!-- /workflow/creating-app -->
## Creating an App
How to create a new application: choosing a project template and initialization.
<!-- /workflow/creating-pages -->
## Creating Pages
Page creation pattern: routing (page.tsx) and screen.
<!-- /workflow/creating-components -->
## Creating Components
Generating components using templates, working with child components.
<!-- /workflow/styling -->
## Styling
Styling tools priority and rules for their application.
<!-- /workflow/data-fetching -->
## Data Fetching
How to fetch data: SWR, API client codegen, sockets.
<!-- /workflow/state-management -->
## State Management
When and how to create a store (Zustand), what to store locally vs globally.
<!-- /workflow/localization -->
## Localization
How to add translations and work with i18next.
<!-- /basics/tech-stack --> <!-- /basics/tech-stack -->
## Tech Stack ## Tech Stack

185
generated/ru/RULES.md
View File

@@ -59,165 +59,98 @@
| Шрифты | _(не заполнен)_ | | Шрифты | _(не заполнен)_ |
| Локализация | _(не заполнен)_ | | Локализация | _(не заполнен)_ |
<!-- /workflow/getting-started --> <!-- /workflow -->
## Начало работы ## Workflow
Что нужно знать перед началом разработки в проекте. Порядок действий при разработке — от создания проекта до реализации фич.
### Стек проекта ### Начало работы
**Next.js** (App Router), **Mantine**, **Zustand**, **FSD**. Подготовка окружения перед началом разработки.
Подробнее — [Технологии и библиотеки](/basics/tech-stack). 1. Открыть проект в VS Code.
2. Установить рекомендуемые расширения (редактор предложит автоматически).
3. Ознакомиться со стеком: Next.js (App Router), Mantine, Zustand, FSD.
### Ключевые особенности ### Создание проекта
- **Генерация вместо ручного создания** — компоненты, фичи, виджеты, сторы и другие модули не создаются вручную. Файловая структура генерируется из шаблонов `.templates/`. Ручное создание файловой структуры модулей запрещено. Инициализация нового проекта из готового шаблона.
- **Biome вместо ESLint + Prettier** — один инструмент для линтинга и форматирования. Автофикс и сортировка импортов происходят автоматически при сохранении файла.
### Настройка окружения 1. Создать проект из шаблона:
```bash
npx tiged git@gromlab.ru:templates/nextjs.git my-app
cd my-app
npm install
```
2. Проект готов к разработке — стек, структура FSD, конфигурация
редактора и шаблоны генерации уже настроены.
Открыть проект в VS Code и установить рекомендуемые расширения — редактор предложит это автоматически. Подробнее — [Настройка VS Code](/applied/vscode). ### Генерация кода
<!-- /workflow/creating-app --> Создание модулей из шаблонов `.templates/` вместо ручного создания файлов.
## Создание проекта
Как начать новый проект, соответствующий стандартам этого руководства. 1. Определить тип модуля и соответствующий шаблон:
### Что нужно знать | Модуль | Слой | Шаблон |
|------------|--------------|-------------|
| Компонент | `shared/ui/` | `component` |
| Фича | `features/` | `feature` |
| Виджет | `widgets/` | `widget` |
| Сущность | `entities/` | `entity` |
| Layout | `layouts/` | `layout` |
| Экран | `screens/` | `screen` |
| Стор | `model/` | `store` |
Новый проект создаётся из готового шаблона. Шаблон содержит настроенный стек, структуру FSD, конфигурацию редактора и шаблоны генерации кода — проект готов к разработке сразу после установки зависимостей. 2. Сгенерировать модуль из шаблона.
3. Если подходящего шаблона нет — сначала создать шаблон, затем использовать.
#### Создание из шаблона Ручное создание файловой структуры модулей запрещено.
```bash ### Добавление страницы
npx tiged git@gromlab.ru:templates/nextjs.git my-app
cd my-app
npm install
```
### Что входит в шаблон Создание нового маршрута: экран + точка входа для роутинга.
- Next.js + TypeScript (App Router)
- Mantine UI + PostCSS Modules
- Biome (линтинг и форматирование)
- Zustand, SWR
- Структура FSD (`screens/`, `widgets/`, `features/`, `entities/`, `shared/`)
- Шаблоны генерации (`.templates/`)
- Конфигурация VS Code (`.vscode/`)
- CSS-токены (цвета, отступы, радиусы, медиа)
- Open Graph метаданные
<!-- /workflow/code-generation -->
## Генерация кода
Как создавать модули в проекте с помощью шаблонов — какие модули покрыты генерацией и когда стоит создавать новые шаблоны.
### Какие модули генерируются из шаблонов
| Модуль | Слой | Шаблон |
|---|---|---|
| Компонент | `shared/ui/` | `component` |
| Фича | `features/` | `feature` |
| Виджет | `widgets/` | `widget` |
| Сущность | `entities/` | `entity` |
| Layout | `layouts/` | `layout` |
| Экран | `screens/` | `screen` |
| Стор | `model/` | `store` |
### Что нужно знать
В проекте принято создавать модули из шаблонов `.templates/`. Шаблоны задают единообразную файловую структуру и сокращают рутину — не нужно вручную создавать папки, файлы типов, стилей и экспорты.
Если для нужного модуля нет подходящего шаблона — стоит сначала создать шаблон, а затем использовать его.
### Когда создавать новый шаблон
- Повторяющаяся структура появляется больше одного раза.
- Существующий шаблон не покрывает нужный тип модуля.
Инструменты и синтаксис шаблонов — [Шаблоны и генерация кода](/applied/templates-generation).
<!-- /workflow/creating-pages -->
## Добавление страницы
Как добавить новую страницу в проект по стандартам этого руководства.
### Что нужно знать
Страница в проекте — это два файла: экран в `src/screens/` (вся логика, стили, зависимости) и `page.tsx` в `src/app/` (точка входа для роутинга Next.js). Экран генерируется из шаблона, `page.tsx` создаётся вручную.
### Порядок действий
1. [Сгенерировать](/applied/templates-generation) экран из шаблона `screen` в папку `src/screens/`.
1. Сгенерировать экран из шаблона `screen` в `src/screens/`.
2. Заполнить экран логикой и стилями. 2. Заполнить экран логикой и стилями.
3. Создать `page.tsx` в нужном маршруте `src/app/`.
3. Создать `page.tsx` в нужном маршруте `src/app/`. Файл страницы должен быть тонким — только `metadata` и рендер экрана. Никакой логики, стилей и хуков в `page.tsx` не размещается — всё это живёт в экране. `page.tsx` — тонкая обёртка: только `metadata` и рендер экрана.
Логика, стили и хуки размещаются в экране, не в `page.tsx`.
### Правила ### Добавление UI-модуля
- Ручное создание файловой структуры экрана запрещено — только [генерация](/applied/templates-generation) из шаблона. Создание компонента, фичи, виджета, сущности или layout.
- Логика, стили и зависимости размещаются в экране, не в `page.tsx`.
- Каждая страница содержит `metadata` с `title` и `description`.
Примеры `page.tsx` и `metadata` — [Page-level компоненты](/applied/page-level). 1. Сгенерировать модуль из соответствующего шаблона в целевой слой.
<!-- /workflow/creating-components -->
## Добавление UI-модуля
Как создать компонент, фичу, виджет, сущность или layout в проекте.
### Что нужно знать
Все UI-модули создаются только из шаблонов `.templates/`. Ручное создание файловой структуры запрещено. Если подходящего шаблона нет — сначала создать шаблон в `.templates/`, затем использовать его.
### Порядок действий
1. [Сгенерировать](/applied/templates-generation) модуль из соответствующего шаблона в целевой слой.
2. Заполнить модуль логикой и стилями. 2. Заполнить модуль логикой и стилями.
3. Дочерние компоненты — генерировать из шаблона `component` в папку `ui/`
внутри родителя.
### Дочерние компоненты Дочерние компоненты не экспортируются через `index.ts` родителя.
Если модулю нужны внутренние подкомпоненты — [генерировать](/applied/templates-generation) их из шаблона `component` в папку `ui/` внутри родительского модуля. Дочерние компоненты не экспортируются через `index.ts` родителя. ### Стилизация
Правила написания компонентов — [Компоненты](/applied/components). Выбор инструмента стилизации по приоритету.
<!-- /workflow/styling --> 1. Использовать Mantine-компоненты и их пропсы.
## Стилизация 2. Если Mantine не покрывает — использовать CSS-токены
(`--color-*`, `--space-*`, `--radius-*`).
3. Если нужна кастомная стилизация — PostCSS Modules.
Как стилизовать компоненты в проекте — приоритет инструментов и правила их применения. Инлайн-стили (`style`), магические значения и глобальные стили
вне `app/styles/` запрещены.
### Приоритет стилизации ### Получение данных
Основной UI-фреймворк проекта — **Mantine**. При стилизации компонентов придерживаться следующего приоритета: *Раздел в разработке* — SWR, генерация API-клиентов, сокеты.
1. **Mantine-компоненты и их пропсы** — в первую очередь использовать встроенные возможности Mantine (пропсы, `classNames`, `styles`). ### Управление состоянием
2. **Глобальные CSS-токены** (`--color-*`, `--space-*`, `--radius-*`) — для значений, которые не покрываются Mantine.
3. **PostCSS Modules** — когда Mantine не покрывает задачу и нужна кастомная стилизация.
### Что запрещено *Раздел в разработке* — когда создавать стор, что хранить локально и глобально.
- **Инлайн-стили** — использование атрибута `style` в компонентах строго запрещено. ### Локализация
- **Магические значения** — произвольные цвета, отступы и скругления запрещены, использовать токены.
- **Глобальные стили** вне `app/styles/` запрещены.
Правила написания CSS, вложенность, медиа-запросы и токены — [Стили](/applied/styles). *Раздел в разработке* — переводы и i18next.
<!-- /workflow/data-fetching -->
## Получение данных
Как получать данные с сервера — SWR, генерация API-клиентов, сокеты.
<!-- /workflow/state-management -->
## Управление состоянием
Как работать с состоянием — когда создавать стор, что хранить локально и глобально.
<!-- /workflow/localization -->
## Локализация
Как добавлять переводы и подключать локализацию через i18next.
<!-- /basics/tech-stack --> <!-- /basics/tech-stack -->
## Технологии и библиотеки ## Технологии и библиотеки