diff --git a/docs/ru/workflow.md b/docs/ru/workflow.md new file mode 100644 index 0000000..0771fc7 --- /dev/null +++ b/docs/ru/workflow.md @@ -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. diff --git a/generated/en/RULES.md b/generated/en/RULES.md index 1176c05..e83887b 100644 --- a/generated/en/RULES.md +++ b/generated/en/RULES.md @@ -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 - -## Getting Started - -Setting up the environment and installing tools before starting development. - - -## Creating an App - -How to create a new application: choosing a project template and initialization. - - -## Creating Pages - -Page creation pattern: routing (page.tsx) and screen. - - -## Creating Components - -Generating components using templates, working with child components. - - -## Styling - -Styling tools priority and rules for their application. - - -## Data Fetching - -How to fetch data: SWR, API client codegen, sockets. - - -## State Management - -When and how to create a store (Zustand), what to store locally vs globally. - - -## Localization - -How to add translations and work with i18next. - ## Tech Stack diff --git a/generated/ru/RULES.md b/generated/ru/RULES.md index e1220fd..0beac83 100644 --- a/generated/ru/RULES.md +++ b/generated/ru/RULES.md @@ -59,165 +59,98 @@ | Шрифты | _(не заполнен)_ | | Локализация | _(не заполнен)_ | - -## Начало работы + +## 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). +### Генерация кода - -## Создание проекта +Создание модулей из шаблонов `.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 метаданные - - -## Генерация кода - -Как создавать модули в проекте с помощью шаблонов — какие модули покрыты генерацией и когда стоит создавать новые шаблоны. - -### Какие модули генерируются из шаблонов - -| Модуль | Слой | Шаблон | -|---|---|---| -| Компонент | `shared/ui/` | `component` | -| Фича | `features/` | `feature` | -| Виджет | `widgets/` | `widget` | -| Сущность | `entities/` | `entity` | -| Layout | `layouts/` | `layout` | -| Экран | `screens/` | `screen` | -| Стор | `model/` | `store` | - -### Что нужно знать - -В проекте принято создавать модули из шаблонов `.templates/`. Шаблоны задают единообразную файловую структуру и сокращают рутину — не нужно вручную создавать папки, файлы типов, стилей и экспорты. - -Если для нужного модуля нет подходящего шаблона — стоит сначала создать шаблон, а затем использовать его. - -### Когда создавать новый шаблон - -- Повторяющаяся структура появляется больше одного раза. -- Существующий шаблон не покрывает нужный тип модуля. - -Инструменты и синтаксис шаблонов — [Шаблоны и генерация кода](/applied/templates-generation). - - -## Добавление страницы - -Как добавить новую страницу в проект по стандартам этого руководства. - -### Что нужно знать - -Страница в проекте — это два файла: экран в `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). - - -## Добавление 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). +Выбор инструмента стилизации по приоритету. - -## Стилизация +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). - - -## Получение данных - -Как получать данные с сервера — SWR, генерация API-клиентов, сокеты. - - -## Управление состоянием - -Как работать с состоянием — когда создавать стор, что хранить локально и глобально. - - -## Локализация - -Как добавлять переводы и подключать локализацию через i18next. +*Раздел в разработке* — переводы и i18next. ## Технологии и библиотеки