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

sync (черновик)

Browse Source
This commit is contained in:
Сергей Громов
2026-04-28 10:52:09 +03:00
parent 7965ec2a96
commit a9ea898220
19 changed files with 69 additions and 322 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
.vitepress/config.ts
View File

@@ -6,7 +6,7 @@ const sidebar = [
link: '/docs/',
},
{
text: 'Workflow',
text: 'Подсказки',
link: '/docs/workflow',
},
{
@@ -29,22 +29,21 @@ const sidebar = [
{ text: 'Типизация', link: '/docs/basics/typing' },
],
},
{
text: 'Установка и настройка',
items: [
{
text: 'Создание проекта',
collapsed: true,
items: [
{ text: 'Из шаблона', link: '/docs/setup/project-from-template' },
{ text: 'Вручную', link: '/docs/setup/project-manual' },
{ text: 'Из шаблона', link: '/docs/creating-project/from-template' },
{ text: 'По гайду вручную', link: '/docs/creating-project/manual' },
{ text: 'Чистый Next.js', link: '/docs/creating-project/nextjs' },
],
},
{ text: 'Next.js', link: '/docs/setup/nextjs' },
{
text: 'Настройка',
items: [
{ text: 'Алиасы', link: '/docs/setup/aliases' },
{ text: 'Biome', link: '/docs/setup/biome' },
{ text: 'Стили', link: '/docs/setup/styles' },
{ text: 'PostCSS', link: '/docs/setup/postcss' },
{ text: 'Стили', link: '/docs/setup/styles' },
{ text: 'SVG-спрайты', link: '/docs/setup/svg-sprites' },
{ text: 'Шаблоны генерации', link: '/docs/setup/templates' },
{ text: 'VS Code', link: '/docs/setup/vscode' },
@@ -56,9 +55,21 @@ const sidebar = [
{ text: 'Структура проекта', link: '/docs/usage/project-structure' },
{ text: 'Компоненты', link: '/docs/usage/components' },
{ text: 'Страницы (App Router)', link: '/docs/usage/page-level' },
{ text: 'Шаблоны и генерация кода', link: '/docs/usage/templates-generation' },
{ text: 'Стили', link: '/docs/usage/styles' },
// Неактивные разделы: страницы существуют, но пока пустые.
// Оставляем в sidebar без `link`, чтобы видеть план, но без перехода.
{ text: 'Изображения · в разработке' },
{ text: 'SVG-спрайты', link: '/docs/usage/svg-sprites' },
{ text: 'Видео · в разработке' },
{ text: 'Stores · в разработке' },
{ text: 'Хуки · в разработке' },
{ text: 'Шрифты · в разработке' },
{ text: 'Локализация · в разработке' },
],
},
{
text: 'Данные',
collapsed: true,
items: [
{ text: 'Введение', link: '/docs/usage/data/' },
{
@@ -70,7 +81,7 @@ const sidebar = [
collapsed: true,
items: [
{ text: 'Автоматическая генерация', link: '/docs/usage/data/rest/clients/auto' },
{ text: 'Ручная генерация', link: '/docs/usage/data/rest/clients/manual' },
{ text: 'Ручное создание', link: '/docs/usage/data/rest/clients/manual' },
],
},
{
@@ -86,20 +97,6 @@ const sidebar = [
{ text: 'Realtime', link: '/docs/usage/data/realtime' },
],
},
{ text: 'Шаблоны и генерация кода', link: '/docs/usage/templates-generation' },
{ text: 'Стили', link: '/docs/usage/styles' },
// Неактивные разделы: страницы существуют, но пока пустые.
// Оставляем в sidebar без `link`, чтобы видеть план, но без перехода.
{ text: 'Изображения · в разработке' },
{ text: 'SVG-спрайты', link: '/docs/usage/svg-sprites' },
{ text: 'Видео · в разработке' },
{ text: 'Stores · в разработке' },
{ text: 'Хуки · в разработке' },
{ text: 'Шрифты · в разработке' },
{ text: 'Локализация · в разработке' },
],
},
];
/**

2
README.md
View File

@@ -65,7 +65,7 @@
| Страницы (App Router) | Как описывать layout, page, loading, error, not-found? |
| Данные: Введение | Как устроена работа с данными в проекте? |
| Данные: REST: Клиенты: Автоматическая генерация | Как сгенерировать REST-клиент автоматически из OpenAPI? |
| Данные: REST: Клиенты: Ручная генерация | Как написать REST-клиент вручную? |
| Данные: REST: Клиенты: Ручное создание | Как написать REST-клиент вручную? |
| Данные: REST: Получение данных: Серверные компоненты | Как получать данные в серверных компонентах? |
| Данные: REST: Получение данных: Клиентские компоненты | Как получать данные в клиентских компонентах (SWR)? |
| Данные: Realtime | Как работать с realtime-каналами и сокетами? |

20
docs/docs/setup/project-from-template.md → docs/docs/creating-project/from-template.md
View File

@@ -1,20 +1,24 @@
---
title: Из шаблона
title: Создание проекта из шаблона
keywords: [создать проект из шаблона, шаблон, template, tiged, degit, клонировать шаблон, эталонный шаблон, быстрый старт, scaffold, новый проект]
---
# Создание проекта из шаблона
Клонирование эталонного шаблона стайлгайда одной командой. Дефолтный сценарий создания проекта.
Раздел описывает процесс создания нового проекта на основе готового шаблона.
Шаблоны включают преднастроенный код-стайл, структуру проекта и необходимые конфигурации, что позволяет начать работу без дополнительной настройки.
В шаблоне уже настроены Next.js, Biome, стили, PostCSS, SVG-спрайты, VS Code и шаблоны генерации. Если нужен контроль над каждым шагом или шаблон недоступен — [Создание проекта вручную](/docs/setup/project-manual).
## Что внутри
## Требования
- Node.js 18.18+ (рекомендуется LTS 20+).
- npm 10+.
- Доступ к `gromlab.ru` (SSH-ключ добавлен).
Шаблон — готовый скелет проекта с применёнными правилами стайлгайда:
- **Стек:** Next.js (App Router), TypeScript, React.
- **Архитектура:** структура папок по SLM, алиасы импортов.
- **Качество кода:** Biome (линтер и форматер), настройки VS Code.
- **Стили:** PostCSS Modules с плагинами, токены, медиа-брейкпоинты.
- **Ассеты:** генерация SVG-спрайтов.
- **Кодогенерация:** шаблоны для страниц, компонентов, хуков, сторов.
в
## Установка
1. Склонировать шаблон в родительском каталоге будущего проекта:

10
docs/docs/setup/project-manual.md → docs/docs/creating-project/manual.md
View File

@@ -5,15 +5,17 @@ keywords: [создать проект, новый проект, с нуля, in
# Создание проекта вручную
Сборка эталонного Next.js-проекта шаг за шагом — для случаев, когда нужен контроль над каждым шагом или шаблон недоступен.
Раздел описывает процесс поэтапного создания Next.js-проекта без использования шаблона.Все настройки, включая структуру проекта, код-стайл и конфигурацию, выполняются вручную, что позволяет полностью контролировать каждый шаг.
Если шаблон доступен — быстрее использовать [Создание проекта из шаблона](/docs/setup/project-from-template).
Рекомендуется использовать этот подход, если требуется тонкая настройка проекта или шаблон недоступен. В остальных случаях проще воспользоваться созданием проекта из шаблона.
Если шаблон доступен — быстрее использовать [Создание проекта из шаблона](/docs/creating-project/from-template).
## Состав эталонного проекта
| Компонент | Роль | Раздел |
|-----------|------|--------|
| Next.js | Фреймворк (роутинг, сборка, SSR) | [Next.js](/docs/setup/nextjs) |
| Next.js | Фреймворк (роутинг, сборка, SSR) | [Next.js](/docs/creating-project/nextjs) |
| Алиасы | Импорты по слоям SLM | [Алиасы](/docs/setup/aliases) |
| Biome | Линтер и форматтер (замена ESLint + Prettier) | [Biome](/docs/setup/biome) |
| Стили | Глобальные токены и breakpoints | [Стили](/docs/setup/styles) |
@@ -38,7 +40,7 @@ keywords: [создать проект, новый проект, с нуля, in
Скелет фреймворка — обязательный первый шаг, остальное опирается на него.
См. [Next.js](/docs/setup/nextjs). После выполнения проверки этого раздела `npm run build` должен проходить.
См. [Next.js](/docs/creating-project/nextjs). После выполнения проверки этого раздела `npm run build` должен проходить.
### 2. Алиасы

4
docs/docs/setup/nextjs.md → docs/docs/creating-project/nextjs.md
View File

@@ -3,9 +3,9 @@ title: Next.js
keywords: [next.js, create-next-app, npx, установка, инициализация, фреймворк, скаффолдинг, app router, typescript]
---
# Next.js
# Чистая установка Next.js (App Router + TypeScript)
Установка фреймворка через `create-next-app` и очистка дефолтного шаблона. На выходе — чистый скелет с App Router и TypeScript.
Раздел описывает установку Next.js через create-next-app с последующей очисткой стандартного шаблона. В результате создаётся минимальный проект со включёнными App Router и TypeScript, без лишнего кода и зависимостей.
## Требования

2
docs/docs/index.md
View File

@@ -63,7 +63,7 @@
| Страницы (App Router) | Как описывать layout, page, loading, error, not-found? |
| Данные: Введение | Как устроена работа с данными в проекте? |
| Данные: REST: Клиенты: Автоматическая генерация | Как сгенерировать REST-клиент автоматически из OpenAPI? |
| Данные: REST: Клиенты: Ручная генерация | Как написать REST-клиент вручную? |
| Данные: REST: Клиенты: Ручное создание | Как написать REST-клиент вручную? |
| Данные: REST: Получение данных: Серверные компоненты | Как получать данные в серверных компонентах? |
| Данные: REST: Получение данных: Клиентские компоненты | Как получать данные в клиентских компонентах (SWR)? |
| Данные: Realtime | Как работать с realtime-каналами и сокетами? |

2
docs/docs/usage/data/index.md
View File

@@ -22,7 +22,7 @@ keywords: [данные, api, rest, realtime, клиент, swr, infrastructure,
- **Клиенты** — как создаётся клиент REST API:
- [Автоматическая генерация](/docs/usage/data/rest/clients/auto) — для API с OpenAPI-спецификацией, через `@gromlab/api-codegen`.
- [Ручная генерация](/docs/usage/data/rest/clients/manual) — для API без схемы, клиент пишется и поддерживается руками.
- [Ручное создание](/docs/usage/data/rest/clients/manual) — для API без схемы, клиент пишется и поддерживается руками.
- **Получение данных** — как клиент используется в приложении:
- [Серверные компоненты](/docs/usage/data/rest/fetching/server) — прямой `await` метода клиента в Server Components.
- [Клиентские компоненты](/docs/usage/data/rest/fetching/client) — через готовые хуки модуля API; SWR с кешем, дедупликацией и ревалидацией скрыт внутри хука.

2
docs/docs/usage/data/rest/clients/auto.md
View File

@@ -7,7 +7,7 @@ keywords: [api, rest, openapi, codegen, генерация, клиент, api-co
Если у API есть OpenAPI-спецификация — клиент генерируется утилитой [@gromlab/api-codegen](https://gromlab.ru/gromov/api-codegen) (обёртка над `swagger-typescript-api`). Ручной код для таких API не пишется.
Когда схемы нет — [Ручная генерация](/docs/usage/data/rest/clients/manual).
Когда схемы нет — [Ручное создание](/docs/usage/data/rest/clients/manual).
В примерах ниже используется условный API `pet-project-api` (kebab-case в путях) / `petProjectApi` (camelCase в коде). В реальном проекте имена выбираются по конкретному API.

4
docs/docs/usage/data/rest/clients/manual.md
View File

@@ -1,9 +1,9 @@
---
title: Ручная генерация
title: Ручное создание
keywords: [api, rest, клиент, ручной, fetch, infrastructure, api-клиент]
---
# Ручная генерация
# Ручное создание
Если у API нет OpenAPI-спецификации — клиент пишется и поддерживается вручную. Цель та же, что и у автогенерации: единая точка работы с API, без прямых `fetch` в коде приложения.

85
docs/docs/workflow.md
View File

@@ -1,86 +1,7 @@
---
title: Workflow
title: Подсказки
---
# Workflow
# Подсказки
Порядок действий при разработке — от создания проекта до реализации фич.
## Создание проекта
Инициализация нового проекта из готового шаблона.
1. Создать проект из шаблона:
```bash
npx tiged git@gromlab.ru:templates/nextjs.git my-app
cd my-app
npm install
```
2. Проект готов к разработке — стек, структура SLM, конфигурация
редактора и шаблоны генерации уже настроены.
## Генерация кода
Создание модулей из шаблонов `.templates/` вместо ручного создания файлов.
1. Определить тип модуля и соответствующий шаблон:
| Модуль | Слой | Шаблон |
|------------|--------------|-------------|
| Компонент | `ui/` | `component` |
| Бизнес-модуль | `business/` | `module` |
| Виджет | `widgets/` | `widget` |
| Layout | `layouts/` | `layout` |
| Экран | `screens/` | `screen` |
| Стор | `stores/` | `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.
Короткие ответы на типовые вопросы и направления в противоречивых ситуациях.

31
docs/docs/workflow/code-generation.md
View File

@@ -1,31 +0,0 @@
---
title: Генерация кода
---
# Генерация кода
Как создавать модули в проекте с помощью шаблонов — какие модули покрыты генерацией и когда стоит создавать новые шаблоны.
## Какие модули генерируются из шаблонов
| Модуль | Слой | Шаблон |
|---|---|---|
| Компонент | `ui/` | `component` |
| Бизнес-модуль | `business/` | `module` |
| Виджет | `widgets/` | `widget` |
| Layout | `layouts/` | `layout` |
| Экран | `screens/` | `screen` |
| Стор | `stores/` | `store` |
## Что нужно знать
В проекте принято создавать модули из шаблонов `.templates/`. Шаблоны задают единообразную файловую структуру и сокращают рутину — не нужно вручную создавать папки, файлы типов, стилей и экспорты.
Если для нужного модуля нет подходящего шаблона — стоит сначала создать шаблон, а затем использовать его.
## Когда создавать новый шаблон
- Повторяющаяся структура появляется больше одного раза.
- Существующий шаблон не покрывает нужный тип модуля.
Инструменты и синтаксис шаблонов — [Шаблоны и генерация кода](/docs/usage/templates-generation).

31
docs/docs/workflow/creating-app.md
View File

@@ -1,31 +0,0 @@
---
title: Создание проекта
---
# Создание проекта
Как начать новый проект, соответствующий стандартам этого руководства.
## Что нужно знать
Новый проект создаётся из готового шаблона. Шаблон содержит настроенный стек, структуру SLM, конфигурацию редактора и шаблоны генерации кода — проект готов к разработке сразу после установки зависимостей.
### Создание из шаблона
```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
- Структура SLM (`layouts/`, `screens/`, `widgets/`, `business/`, `infrastructure/`, `ui/`, `shared/`)
- Шаблоны генерации (`.templates/`)
- Конфигурация VS Code (`.vscode/`)
- CSS-токены (цвета, отступы, радиусы, медиа)
- Open Graph метаданные

22
docs/docs/workflow/creating-components.md
View File

@@ -1,22 +0,0 @@
---
title: Добавление UI-модуля
---
# Добавление UI-модуля
Как создать компонент, бизнес-модуль, виджет или layout в проекте.
## Что нужно знать
Все UI-модули создаются только из шаблонов `.templates/`. Ручное создание файловой структуры запрещено. Если подходящего шаблона нет — сначала создать шаблон в `.templates/`, затем использовать его.
## Порядок действий
1. [Сгенерировать](/docs/usage/templates-generation) модуль из соответствующего шаблона в целевой слой.
2. Заполнить модуль логикой и стилями.
## Дочерние компоненты
Если модулю нужны внутренние подкомпоненты — [генерировать](/docs/usage/templates-generation) их из шаблона `component` в папку `ui/` внутри родительского модуля. Дочерние компоненты не экспортируются через `index.ts` родителя.
Правила написания компонентов — [Компоненты](/docs/usage/components).

27
docs/docs/workflow/creating-pages.md
View File

@@ -1,27 +0,0 @@
---
title: Добавление страницы
---
# Добавление страницы
Как добавить новую страницу в проект по стандартам этого руководства.
## Что нужно знать
Страница в проекте — это два файла: экран в `src/screens/` (вся логика, стили, зависимости) и `page.tsx` в `src/app/` (точка входа для роутинга Next.js). Экран генерируется из шаблона, `page.tsx` создаётся вручную.
## Порядок действий
1. [Сгенерировать](/docs/usage/templates-generation) экран из шаблона `screen` в папку `src/screens/`.
2. Заполнить экран логикой и стилями.
3. Создать `page.tsx` в нужном маршруте `src/app/`. Файл страницы должен быть тонким — только `metadata` и рендер экрана. Никакой логики, стилей и хуков в `page.tsx` не размещается — всё это живёт в экране.
## Правила
- Ручное создание файловой структуры экрана запрещено — только [генерация](/docs/usage/templates-generation) из шаблона.
- Логика, стили и зависимости размещаются в экране, не в `page.tsx`.
- Каждая страница содержит `metadata` с `title` и `description`.
Примеры `page.tsx` и `metadata` — [Page-level компоненты](/docs/usage/page-level).

7
docs/docs/workflow/data-fetching.md
View File

@@ -1,7 +0,0 @@
---
title: Получение данных
---
# Получение данных
Как получать данные с сервера — SWR, генерация API-клиентов, сокеты.

22
docs/docs/workflow/getting-started.md
View File

@@ -1,22 +0,0 @@
---
title: Начало работы
---
# Начало работы
Что нужно знать перед началом разработки в проекте.
## Стек проекта
**Next.js** (App Router), **Mantine**, **Zustand**, **SLM Design**.
Подробнее — [Технологии и библиотеки](/docs/basics/tech-stack).
## Ключевые особенности
- **Генерация вместо ручного создания** — компоненты, бизнес-модули, виджеты, сторы и другие модули не создаются вручную. Файловая структура генерируется из шаблонов `.templates/`. Ручное создание файловой структуры модулей запрещено.
- **Biome вместо ESLint + Prettier** — один инструмент для линтинга и форматирования. Автофикс и сортировка импортов происходят автоматически при сохранении файла.
## Настройка окружения
Открыть проект в VS Code и установить рекомендуемые расширения — редактор предложит это автоматически. Подробнее — [Настройка VS Code](/docs/setup/vscode).

7
docs/docs/workflow/localization.md
View File

@@ -1,7 +0,0 @@
---
title: Локализация
---
# Локализация
Как добавлять переводы и подключать локализацию через i18next.

7
docs/docs/workflow/state-management.md
View File

@@ -1,7 +0,0 @@
---
title: Управление состоянием
---
# Управление состоянием
Как работать с состоянием — когда создавать стор, что хранить локально и глобально.

23
docs/docs/workflow/styling.md
View File

@@ -1,23 +0,0 @@
---
title: Стилизация
---
# Стилизация
Как стилизовать компоненты в проекте — приоритет инструментов и правила их применения.
## Приоритет стилизации
Основной UI-фреймворк проекта — **Mantine**. При стилизации компонентов придерживаться следующего приоритета:
1. **Mantine-компоненты и их пропсы** — в первую очередь использовать встроенные возможности Mantine (пропсы, `classNames`, `styles`).
2. **Глобальные CSS-токены** (`--color-*`, `--space-*`, `--radius-*`) — для значений, которые не покрываются Mantine.
3. **PostCSS Modules** — когда Mantine не покрывает задачу и нужна кастомная стилизация.
## Что запрещено
- **Инлайн-стили** — использование атрибута `style` в компонентах строго запрещено.
- **Магические значения** — произвольные цвета, отступы и скругления запрещены, использовать токены.
- **Глобальные стили** вне `app/styles/` запрещены.
Правила написания CSS, вложенность, медиа-запросы и токены — [Стили: использование](/docs/usage/styles).