docs: объединены 9 страниц workflow в один файл
- Создан единый docs/ru/workflow.md с форматом: заголовок, описание, этапы, комментарий - Пересобраны generated/ru/RULES.md и generated/en/RULES.md - Старые файлы в docs/ru/workflow/ сохранены, но убраны из навигации
This commit is contained in:
95
docs/ru/workflow.md
Normal file
95
docs/ru/workflow.md
Normal 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.
|
||||
@@ -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
|
||||
|
||||
<!-- /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 -->
|
||||
## Tech Stack
|
||||
|
||||
|
||||
@@ -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. Заполнить экран логикой и стилями.
|
||||
3. Создать `page.tsx` в нужном маршруте `src/app/`.
|
||||
|
||||
3. Создать `page.tsx` в нужном маршруте `src/app/`. Файл страницы должен быть тонким — только `metadata` и рендер экрана. Никакой логики, стилей и хуков в `page.tsx` не размещается — всё это живёт в экране.
|
||||
`page.tsx` — тонкая обёртка: только `metadata` и рендер экрана.
|
||||
Логика, стили и хуки размещаются в экране, не в `page.tsx`.
|
||||
|
||||
### Правила
|
||||
### Добавление UI-модуля
|
||||
|
||||
- Ручное создание файловой структуры экрана запрещено — только [генерация](/applied/templates-generation) из шаблона.
|
||||
- Логика, стили и зависимости размещаются в экране, не в `page.tsx`.
|
||||
- Каждая страница содержит `metadata` с `title` и `description`.
|
||||
Создание компонента, фичи, виджета, сущности или layout.
|
||||
|
||||
Примеры `page.tsx` и `metadata` — [Page-level компоненты](/applied/page-level).
|
||||
|
||||
<!-- /workflow/creating-components -->
|
||||
## Добавление UI-модуля
|
||||
|
||||
Как создать компонент, фичу, виджет, сущность или layout в проекте.
|
||||
|
||||
### Что нужно знать
|
||||
|
||||
Все UI-модули создаются только из шаблонов `.templates/`. Ручное создание файловой структуры запрещено. Если подходящего шаблона нет — сначала создать шаблон в `.templates/`, затем использовать его.
|
||||
|
||||
### Порядок действий
|
||||
|
||||
1. [Сгенерировать](/applied/templates-generation) модуль из соответствующего шаблона в целевой слой.
|
||||
1. Сгенерировать модуль из соответствующего шаблона в целевой слой.
|
||||
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).
|
||||
|
||||
<!-- /workflow/data-fetching -->
|
||||
## Получение данных
|
||||
|
||||
Как получать данные с сервера — SWR, генерация API-клиентов, сокеты.
|
||||
|
||||
<!-- /workflow/state-management -->
|
||||
## Управление состоянием
|
||||
|
||||
Как работать с состоянием — когда создавать стор, что хранить локально и глобально.
|
||||
|
||||
<!-- /workflow/localization -->
|
||||
## Локализация
|
||||
|
||||
Как добавлять переводы и подключать локализацию через i18next.
|
||||
*Раздел в разработке* — переводы и i18next.
|
||||
|
||||
<!-- /basics/tech-stack -->
|
||||
## Технологии и библиотеки
|
||||
|
||||
Reference in New Issue
Block a user