docs: переработать заголовки и описания разделов
- Зафиксированы новые правила в CONTRIBUTING.md: заголовок и описание как навигационный маркер, запреты, тесты и подходящие формы - Описания во всех 26 разделах переписаны как короткий ответ на вопрос «когда сюда нужно?» - Заголовки приведены к самодостаточному виду: SLM Design, SVG-спрайты, VS Code, Чистая установка Next.js, Источники данных, Создание проекта вручную, Стили, Алиасы импортов - Описания добавлены в frontmatter (description) для согласованности с llms.txt и SEO - Удалены навигационные ссылки сразу после описания - Добавлен docs-overview.md — сводный обзор всех страниц - Обновлён сайдбар: ссылка «Алиасы» → «Алиасы импортов»
This commit is contained in:
@@ -40,7 +40,7 @@ const sidebar = [
|
||||
{
|
||||
text: 'Настройка',
|
||||
items: [
|
||||
{ text: 'Алиасы', link: '/docs/setup/aliases' },
|
||||
{ text: 'Алиасы импортов', link: '/docs/setup/aliases' },
|
||||
{ text: 'Biome', link: '/docs/setup/biome' },
|
||||
{ text: 'PostCSS', link: '/docs/setup/postcss' },
|
||||
{ text: 'Стили', link: '/docs/setup/styles' },
|
||||
|
||||
124
CONTRIBUTING.md
124
CONTRIBUTING.md
@@ -98,7 +98,8 @@ generate-llms.ts # Скрипт генерации llms.txt и R
|
||||
```markdown
|
||||
# {Название}
|
||||
|
||||
Краткое описание: о чём раздел и какие аспекты работы с областью он охватывает.
|
||||
{Одно-два предложения, по которым читатель за секунду решает, нужен ли ему раздел.
|
||||
Правила оформления — секция «Заголовок и описание» ниже.}
|
||||
|
||||
## Что нужно знать
|
||||
|
||||
@@ -183,58 +184,127 @@ title: Название раздела
|
||||
|
||||
Значение `title` совпадает с текстом `h1`-заголовка в файле.
|
||||
|
||||
### Заголовки
|
||||
### Заголовок и описание
|
||||
|
||||
- Один `h1` на файл — совпадает с `title` из frontmatter.
|
||||
- Сразу после `h1` — вводный абзац (одно-два предложения).
|
||||
Каждая страница начинается с `h1`-заголовка и абзаца-описания сразу под ним.
|
||||
Эта пара — **навигационный маркер**: попадает в сайдбар, `llms.txt`,
|
||||
`README.md` архива и должна за секунду давать читателю или LLM понять,
|
||||
**когда сюда нужно идти**.
|
||||
|
||||
#### Структура заголовков
|
||||
|
||||
- Один `h1` на файл, совпадает с `title` во frontmatter.
|
||||
- Сразу после `h1` — описание (одно-два предложения, см. ниже).
|
||||
- Основные секции — `h2`.
|
||||
- Подсекции внутри `h2` — `h3`.
|
||||
- `h4` не используется.
|
||||
|
||||
### Вводный абзац
|
||||
#### Имя `h1` (заголовок страницы)
|
||||
|
||||
Абзац сразу после `h1` отвечает на вопрос «о чём этот раздел?».
|
||||
Он попадает в `llms.txt` и `README.md` архива как краткое описание,
|
||||
поэтому должен быть плотным и без воды.
|
||||
- Называет предметную область, а не реализацию.
|
||||
- Без имён пакетов, опций, конфигов и путей.
|
||||
- Самодостаточен — читается без контекста сайдбара.
|
||||
- Исключение: имя инструмента допустимо, если оно — единственное
|
||||
устойчивое имя самой области (`PostCSS`, `Biome`, `VS Code`).
|
||||
|
||||
**Правила:**
|
||||
**Хорошо:** «Алиасы импортов», «Структура проекта», «SVG-спрайты».
|
||||
|
||||
- Не начинать с «Раздел описывает», «Этот раздел», «В этом разделе»,
|
||||
«Здесь рассмотрено», «В этом документе».
|
||||
- Начинать с подлежащего — самой темы (`Слои SLM:`, `Соглашения об именовании:`).
|
||||
- Двоеточие или тире для перечисления **категорий и областей**, а не
|
||||
конкретных значений из содержимого.
|
||||
- Не дублировать содержимое: если внутри раздела 12 правил —
|
||||
не перечислять их во вводном абзаце.
|
||||
- Не аргументировать («единые правила делают код предсказуемым»).
|
||||
- 1–2 предложения.
|
||||
**Плохо:** «Установка и настройка» (что устанавливаем?),
|
||||
«Использование» (что используем?), «Введение» (во что?).
|
||||
|
||||
**Проверка:** если при добавлении нового правила/инструмента/раздела
|
||||
вводный абзац придётся править — он слишком конкретный.
|
||||
#### Описание
|
||||
|
||||
Описание — короткий ответ на вопрос «у меня задача X, мне сюда?».
|
||||
Не аннотация. Не оглавление.
|
||||
|
||||
**Запреты:**
|
||||
|
||||
- Не упоминать конкретные пакеты, библиотеки, инструменты
|
||||
(`@gromlab/svg-sprites`, `Mantine`, `Zustand`).
|
||||
- Не упоминать конкретные файлы и пути
|
||||
(`postcss.config.mjs`, `.templates/`, `biome.json`).
|
||||
- Не упоминать конкретные опции, ключи API, имена функций
|
||||
(`baseUrl`, `cl()`, `useStore`).
|
||||
- Не начинать с «Раздел описывает», «Этот раздел»,
|
||||
«В этом разделе», «Здесь рассмотрено».
|
||||
- Не использовать дежурные префиксы как шаблон
|
||||
(«Правила работы с...», «Правила написания...») — само то,
|
||||
что раздел про правила, и так понятно из секции и заголовка.
|
||||
- Не пересказывать содержимое перечислением подсекций
|
||||
(«организация, реализация, делегирование, метаданные»).
|
||||
- Не аргументировать пользу
|
||||
(«обеспечит единообразие», «упростит поддержку»).
|
||||
|
||||
**Требования:**
|
||||
|
||||
- 1 предложение, обычно 5–12 слов.
|
||||
- Звучит как ответ человека другу, а не как техспек.
|
||||
- Описание читается **самостоятельно**, без контекста сайдбара.
|
||||
- Если страница вложена в семантическую группу
|
||||
(например, `Данные → REST → Клиенты → ...`) и её заголовок
|
||||
без этой группы теряет смысл — описание явно содержит имя
|
||||
родительской области, чтобы читалось без сайдбара.
|
||||
|
||||
**Подходящие формы:**
|
||||
|
||||
- «Как X.»
|
||||
- «Что такое X.»
|
||||
- «Из чего состоит X.»
|
||||
- «Установка X.»
|
||||
- «Какие X есть и как ими пользоваться.»
|
||||
|
||||
Перечисление аспектов через двоеточие — только если без него читатель
|
||||
не сможет различить раздел от соседнего.
|
||||
|
||||
**Тест навигации.** Читатель видит описание — за секунду должен понять
|
||||
«мне сюда» или «нет, не сюда». Если приходится перечитывать —
|
||||
описание слишком длинное.
|
||||
|
||||
**Тест на изменение.** Если в разделе сменится пакет, переименуется
|
||||
файл или добавится правило — придётся ли править описание?
|
||||
Если да — оно слишком конкретное.
|
||||
|
||||
**Хорошо:**
|
||||
|
||||
```markdown
|
||||
Слои SLM: назначение, классификация, направление зависимостей, правила.
|
||||
Какие алиасы импортов есть в проекте и как ими пользоваться.
|
||||
```
|
||||
|
||||
```markdown
|
||||
Базовый стек проекта по областям: UI, архитектура, данные, состояние,
|
||||
локализация, тестирование, стили, генерация кода.
|
||||
Установка и настройка линтера-форматтера в новом проекте.
|
||||
```
|
||||
|
||||
```markdown
|
||||
Из чего состоит проект и где что лежит.
|
||||
```
|
||||
|
||||
```markdown
|
||||
Получение REST-данных в серверных компонентах.
|
||||
```
|
||||
|
||||
**Плохо:**
|
||||
|
||||
```markdown
|
||||
Раздел описывает слои SLM: что такое слой, какие бывают, как между
|
||||
ними направлены зависимости и какие правила действуют на каждом.
|
||||
Раздел описывает, какие алиасы используются в проекте: их полный список,
|
||||
где они объявлены и как ими пользоваться между модулями и внутри модуля.
|
||||
```
|
||||
|
||||
_Начинается с «Раздел описывает», пересказывает содержимое._
|
||||
|
||||
```markdown
|
||||
Этот раздел описывает базовый стек технологий и библиотек, принятый в
|
||||
проекте. React, TypeScript, Next.js, SWR, Zustand, i18next.
|
||||
Установка и настройка CSS-процессора PostCSS в проекте: набор плагинов,
|
||||
конфиг `postcss.config.mjs`. Выполняется один раз при заведении проекта.
|
||||
```
|
||||
|
||||
_Упомянут конкретный файл, перечисление аспектов превратилось в оглавление._
|
||||
|
||||
```markdown
|
||||
Правила работы с React-компонентами: файловая структура,
|
||||
типизация пропсов, документирование, реализация.
|
||||
```
|
||||
|
||||
_Дежурный префикс «Правила работы с...» плюс оглавление подсекций._
|
||||
|
||||
### Примеры кода
|
||||
|
||||
- Блоки кода с указанием языка: ` ```tsx `, ` ```css `, ` ```bash `, ` ```text `.
|
||||
|
||||
174
docs-overview.md
Normal file
174
docs-overview.md
Normal file
@@ -0,0 +1,174 @@
|
||||
# Обзор страниц документации
|
||||
|
||||
Список всех `.md`-страниц в `docs/docs/` в порядке сайдбара (`.vitepress/config.ts`).
|
||||
Поля: путь к файлу, заголовок (`h1`), описание (абзац под заголовком).
|
||||
|
||||
## Главная
|
||||
|
||||
### docs/docs/index.md
|
||||
**Заголовок:** NextJS Style Guide
|
||||
**Описание:** Стандарты разработки фронтенд-приложений на Next.js и TypeScript.
|
||||
|
||||
## Подсказки
|
||||
|
||||
### docs/docs/workflow.md
|
||||
**Заголовок:** Подсказки
|
||||
**Описание:** Короткие ответы на типовые вопросы и решения для спорных ситуаций.
|
||||
|
||||
## Базовые правила
|
||||
|
||||
### docs/docs/basics/tech-stack.md
|
||||
**Заголовок:** Технологии и библиотеки
|
||||
**Описание:** Какие библиотеки и инструменты используются в проекте.
|
||||
|
||||
### docs/docs/basics/naming.md
|
||||
**Заголовок:** Именование
|
||||
**Описание:** Как называть переменные, файлы и прочие сущности в коде.
|
||||
|
||||
### docs/docs/basics/architecture/index.md
|
||||
**Заголовок:** SLM Design
|
||||
**Описание:** Архитектурный подход проекта: что такое SLM и как он устроен.
|
||||
|
||||
### docs/docs/basics/architecture/reference/layers.md
|
||||
**Заголовок:** Слои
|
||||
**Описание:** Из каких слоёв состоит архитектура и как они связаны.
|
||||
|
||||
### docs/docs/basics/architecture/reference/modules.md
|
||||
**Заголовок:** Модули
|
||||
**Описание:** Что такое модуль в архитектуре и как он устроен.
|
||||
|
||||
### docs/docs/basics/architecture/reference/segments.md
|
||||
**Заголовок:** Сегменты
|
||||
**Описание:** Что такое сегмент модуля и какие они бывают.
|
||||
|
||||
### docs/docs/basics/code-style.md
|
||||
**Заголовок:** Стиль кода
|
||||
**Описание:** Как оформляется код в проекте.
|
||||
|
||||
### docs/docs/basics/documentation.md
|
||||
**Заголовок:** Документирование
|
||||
**Описание:** Что и как документировать в коде.
|
||||
|
||||
### docs/docs/basics/typing.md
|
||||
**Заголовок:** Типизация
|
||||
**Описание:** Как типизируется код в проекте.
|
||||
|
||||
## Создание проекта
|
||||
|
||||
### docs/docs/creating-project/from-template.md
|
||||
**Заголовок:** Создание проекта из шаблона
|
||||
**Описание:** Создание нового проекта на основе готового шаблона.
|
||||
|
||||
### docs/docs/creating-project/manual.md
|
||||
**Заголовок:** Создание проекта вручную
|
||||
**Описание:** Поэтапное создание нового проекта без использования шаблона.
|
||||
|
||||
### docs/docs/creating-project/nextjs.md
|
||||
**Заголовок:** Чистая установка Next.js
|
||||
**Описание:** Установка Next.js без лишнего шаблона — голый каркас под дальнейшую сборку.
|
||||
|
||||
## Настройка
|
||||
|
||||
### docs/docs/setup/aliases.md
|
||||
**Заголовок:** Алиасы импортов
|
||||
**Описание:** Какие алиасы импортов есть в проекте и как ими пользоваться.
|
||||
|
||||
### docs/docs/setup/biome.md
|
||||
**Заголовок:** Biome
|
||||
**Описание:** Установка и настройка линтера-форматтера в новом проекте.
|
||||
|
||||
### docs/docs/setup/postcss.md
|
||||
**Заголовок:** PostCSS
|
||||
**Описание:** Установка и настройка CSS-процессора в новом проекте.
|
||||
|
||||
### docs/docs/setup/styles.md
|
||||
**Заголовок:** Стили
|
||||
**Описание:** Подготовка стилевой основы проекта: токены, медиа-запросы, глобальные стили.
|
||||
|
||||
### docs/docs/setup/svg-sprites.md
|
||||
**Заголовок:** SVG-спрайты
|
||||
**Описание:** Подключение SVG-спрайтов в новом проекте.
|
||||
|
||||
### docs/docs/setup/templates.md
|
||||
**Заголовок:** Шаблоны генерации
|
||||
**Описание:** Подключение шаблонов кодогенерации в новом проекте.
|
||||
|
||||
### docs/docs/setup/vscode.md
|
||||
**Заголовок:** VS Code
|
||||
**Описание:** Единые настройки редактора и расширений для команды.
|
||||
|
||||
## Использование
|
||||
|
||||
### docs/docs/usage/project-structure.md
|
||||
**Заголовок:** Структура проекта
|
||||
**Описание:** Из чего состоит проект и где что лежит.
|
||||
|
||||
### docs/docs/usage/components.md
|
||||
**Заголовок:** Компоненты
|
||||
**Описание:** Как устроен и пишется React-компонент в проекте.
|
||||
|
||||
### docs/docs/usage/page-level.md
|
||||
**Заголовок:** Файлы роутинга
|
||||
**Описание:** Что должно лежать в файлах роутинга, а что — в экранах.
|
||||
|
||||
### docs/docs/usage/templates-generation.md
|
||||
**Заголовок:** Шаблоны и генерация кода
|
||||
**Описание:** Как устроены шаблоны кодогенерации и как ими пользоваться.
|
||||
|
||||
### docs/docs/usage/styles.md
|
||||
**Заголовок:** Стили
|
||||
**Описание:** Как пишутся стили в проекте.
|
||||
|
||||
### docs/docs/usage/images-sprites.md
|
||||
**Заголовок:** —
|
||||
**Описание:** _(файл пустой)_
|
||||
|
||||
### docs/docs/usage/svg-sprites.md
|
||||
**Заголовок:** SVG-спрайты
|
||||
**Описание:** Как добавлять и использовать SVG-иконки в коде.
|
||||
|
||||
### docs/docs/usage/video.md
|
||||
**Заголовок:** —
|
||||
**Описание:** _(файл пустой)_
|
||||
|
||||
### docs/docs/usage/stores.md
|
||||
**Заголовок:** —
|
||||
**Описание:** _(файл пустой)_
|
||||
|
||||
### docs/docs/usage/hooks.md
|
||||
**Заголовок:** —
|
||||
**Описание:** _(файл пустой)_
|
||||
|
||||
### docs/docs/usage/fonts.md
|
||||
**Заголовок:** —
|
||||
**Описание:** _(файл пустой)_
|
||||
|
||||
### docs/docs/usage/localization.md
|
||||
**Заголовок:** —
|
||||
**Описание:** _(файл пустой)_
|
||||
|
||||
## Данные
|
||||
|
||||
### docs/docs/usage/data/index.md
|
||||
**Заголовок:** Источники данных
|
||||
**Описание:** Какие источники данных используются в проекте и как с ними работать.
|
||||
|
||||
### docs/docs/usage/data/rest/clients/auto.md
|
||||
**Заголовок:** Автоматическая генерация
|
||||
**Описание:** Генерация REST-клиента из OpenAPI-спецификации.
|
||||
|
||||
### docs/docs/usage/data/rest/clients/manual.md
|
||||
**Заголовок:** Ручное создание
|
||||
**Описание:** Создание REST-клиента вручную, когда нет OpenAPI-спецификации.
|
||||
|
||||
### docs/docs/usage/data/rest/fetching/server.md
|
||||
**Заголовок:** Серверные компоненты
|
||||
**Описание:** Получение REST-данных в серверных компонентах.
|
||||
|
||||
### docs/docs/usage/data/rest/fetching/client.md
|
||||
**Заголовок:** Клиентские компоненты
|
||||
**Описание:** Получение REST-данных в клиентских компонентах.
|
||||
|
||||
### docs/docs/usage/data/realtime.md
|
||||
**Заголовок:** Realtime
|
||||
**Описание:** Работа с push-данными от сервера: подписки и события.
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
title: Архитектура
|
||||
title: SLM Design
|
||||
description: "Архитектурный подход проекта: что такое SLM и как он устроен."
|
||||
---
|
||||
|
||||
# SLM Design
|
||||
Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.
|
||||
|
||||
Архитектурный подход проекта: что такое SLM и как он устроен.
|
||||
|
||||
## Преимущества
|
||||
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
title: Слои
|
||||
description: Из каких слоёв состоит архитектура и как они связаны.
|
||||
---
|
||||
|
||||
# Слои
|
||||
|
||||
Слои SLM: назначение, классификация, направление зависимостей, правила.
|
||||
Из каких слоёв состоит архитектура и как они связаны.
|
||||
|
||||
## Определение
|
||||
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
title: Модули
|
||||
description: Что такое модуль в архитектуре и как он устроен.
|
||||
---
|
||||
|
||||
# Модули
|
||||
|
||||
Модули SLM: состав, границы, взаимодействие с остальным кодом.
|
||||
Что такое модуль в архитектуре и как он устроен.
|
||||
|
||||
## Определение
|
||||
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
title: Сегменты
|
||||
description: Что такое сегмент модуля и какие они бывают.
|
||||
---
|
||||
|
||||
# Сегменты
|
||||
|
||||
Сегменты SLM: типы, назначение, что лежит внутри каждого.
|
||||
Что такое сегмент модуля и какие они бывают.
|
||||
|
||||
## Определение
|
||||
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
title: Стиль кода
|
||||
description: Как оформляется код в проекте.
|
||||
---
|
||||
|
||||
# Стиль кода
|
||||
|
||||
Единые правила оформления кода: форматирование, импорты, читаемость.
|
||||
Как оформляется код в проекте.
|
||||
|
||||
## Отступы
|
||||
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
title: Документирование
|
||||
description: Что и как документировать в коде.
|
||||
---
|
||||
|
||||
# Документирование
|
||||
|
||||
Правила документирования кода: что и когда документировать через JSDoc.
|
||||
Что и как документировать в коде.
|
||||
|
||||
## Общие правила
|
||||
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
title: Именование
|
||||
description: Как называть переменные, файлы и прочие сущности в коде.
|
||||
---
|
||||
|
||||
# Именование
|
||||
|
||||
Соглашения об именовании в коде: что и как называть.
|
||||
Как называть переменные, файлы и прочие сущности в коде.
|
||||
|
||||
## Базовые правила
|
||||
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
title: Технологии и библиотеки
|
||||
description: Какие библиотеки и инструменты используются в проекте.
|
||||
---
|
||||
|
||||
# Технологии и библиотеки
|
||||
|
||||
Базовый стек проекта по областям: UI, архитектура, данные, состояние, локализация, тестирование, стили, генерация кода.
|
||||
Какие библиотеки и инструменты используются в проекте.
|
||||
|
||||
## Что используем
|
||||
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
title: Типизация
|
||||
description: Как типизируется код в проекте.
|
||||
---
|
||||
|
||||
# Типизация
|
||||
|
||||
Правила типизации в TypeScript: общие принципы и работа с динамическими типами.
|
||||
Как типизируется код в проекте.
|
||||
|
||||
## Общие правила
|
||||
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
---
|
||||
title: Создание проекта из шаблона
|
||||
description: Создание нового проекта на основе готового шаблона.
|
||||
keywords: [создать проект из шаблона, шаблон, template, tiged, degit, клонировать шаблон, эталонный шаблон, быстрый старт, scaffold, новый проект]
|
||||
---
|
||||
|
||||
# Создание проекта из шаблона
|
||||
|
||||
Раздел описывает процесс создания нового проекта на основе готового шаблона.
|
||||
Шаблоны включают преднастроенный код-стайл, структуру проекта и необходимые конфигурации, что позволяет начать работу без дополнительной настройки.
|
||||
Создание нового проекта на основе готового шаблона.
|
||||
|
||||
## Что внутри
|
||||
|
||||
|
||||
@@ -1,15 +1,12 @@
|
||||
---
|
||||
title: Вручную
|
||||
title: Создание проекта вручную
|
||||
description: Поэтапное создание нового проекта без использования шаблона.
|
||||
keywords: [создать проект, новый проект, с нуля, init, initialize, scaffold, create-next-app, начать проект, поднять проект, эталонный проект, ручная установка]
|
||||
---
|
||||
|
||||
# Создание проекта вручную
|
||||
|
||||
Раздел описывает процесс поэтапного создания Next.js-проекта без использования шаблона.Все настройки, включая структуру проекта, код-стайл и конфигурацию, выполняются вручную, что позволяет полностью контролировать каждый шаг.
|
||||
|
||||
Рекомендуется использовать этот подход, если требуется тонкая настройка проекта или шаблон недоступен. В остальных случаях проще воспользоваться созданием проекта из шаблона.
|
||||
|
||||
Если шаблон доступен — быстрее использовать [Создание проекта из шаблона](/docs/creating-project/from-template).
|
||||
Поэтапное создание нового проекта без использования шаблона.
|
||||
|
||||
## Состав эталонного проекта
|
||||
|
||||
|
||||
@@ -1,11 +1,12 @@
|
||||
---
|
||||
title: Next.js
|
||||
title: Чистая установка Next.js
|
||||
description: "Установка Next.js без лишнего шаблона — голый каркас под дальнейшую сборку."
|
||||
keywords: [next.js, create-next-app, npx, установка, инициализация, фреймворк, скаффолдинг, app router, typescript]
|
||||
---
|
||||
|
||||
# Чистая установка Next.js (App Router + TypeScript)
|
||||
# Чистая установка Next.js
|
||||
|
||||
Раздел описывает установку Next.js через create-next-app с последующей очисткой стандартного шаблона. В результате создаётся минимальный проект со включёнными App Router и TypeScript, без лишнего кода и зависимостей.
|
||||
Установка Next.js без лишнего шаблона — голый каркас под дальнейшую сборку.
|
||||
|
||||
## Требования
|
||||
|
||||
|
||||
@@ -1,6 +1,11 @@
|
||||
---
|
||||
title: NextJS Style Guide
|
||||
description: Стандарты разработки фронтенд-приложений на Next.js и TypeScript.
|
||||
---
|
||||
|
||||
# NextJS Style Guide
|
||||
|
||||
Соглашения по разработке Next.js проектов: архитектура и слои приложения, структура кода, организация модулей, стилизация, типизация и инфраструктура.
|
||||
Стандарты разработки фронтенд-приложений на Next.js и TypeScript.
|
||||
|
||||
## Использование
|
||||
|
||||
|
||||
@@ -1,13 +1,12 @@
|
||||
---
|
||||
title: Алиасы
|
||||
title: Алиасы импортов
|
||||
description: Какие алиасы импортов есть в проекте и как ими пользоваться.
|
||||
keywords: [алиасы, aliases, paths, tsconfig, импорты, baseUrl, app, layouts, screens, widgets, business, infrastructure, ui, shared]
|
||||
---
|
||||
|
||||
# Алиасы
|
||||
# Алиасы импортов
|
||||
|
||||
Импорты в проекте идут через алиасы слоёв SLM-архитектуры — по одному на каждый слой `src/`. Префикс `@/` **не используется**: имя слоя само по себе однозначно адресует код.
|
||||
|
||||
Слои и направление зависимостей — [Архитектура: слои](/docs/basics/architecture/reference/layers).
|
||||
Какие алиасы импортов есть в проекте и как ими пользоваться.
|
||||
|
||||
## Конфиг
|
||||
|
||||
|
||||
@@ -1,11 +1,12 @@
|
||||
---
|
||||
title: Biome
|
||||
description: Установка и настройка линтера-форматтера в новом проекте.
|
||||
keywords: [biome, линтер, форматтер, lint, format, biome.json, "@biomejs/biome", замена eslint, замена prettier]
|
||||
---
|
||||
|
||||
# Biome
|
||||
|
||||
Единый линтер и форматтер для JS/TS/JSON в проекте. Заменяет связку ESLint + Prettier одним инструментом.
|
||||
Установка и настройка линтера-форматтера в новом проекте.
|
||||
|
||||
## Требования
|
||||
|
||||
|
||||
@@ -1,13 +1,12 @@
|
||||
---
|
||||
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 в проекте: набор плагинов, конфиг `postcss.config.mjs`. Выполняется один раз при заведении проекта.
|
||||
|
||||
Правила написания CSS в компонентах — [Использование](/docs/usage/styles).
|
||||
Установка и настройка CSS-процессора в новом проекте.
|
||||
|
||||
## Зачем PostCSS
|
||||
|
||||
|
||||
@@ -1,13 +1,12 @@
|
||||
---
|
||||
title: Стили
|
||||
description: "Подготовка стилевой основы проекта: токены, медиа-запросы, глобальные стили."
|
||||
keywords: [variables.css, media.css, global.css, shared/styles, токены, переменные, custom-media, breakpoints, подключение стилей, базовые стили, инициализация]
|
||||
---
|
||||
|
||||
# Стили
|
||||
|
||||
Базовая стилевая инфраструктура: токены, breakpoints и точка сборки глобальных стилей в `src/shared/styles/`.
|
||||
|
||||
CSS-процессор — отдельный шаг ([PostCSS](/docs/setup/postcss)). Правила написания CSS в компонентах — [Стили: использование](/docs/usage/styles).
|
||||
Подготовка стилевой основы проекта: токены, медиа-запросы, глобальные стили.
|
||||
|
||||
## Требования
|
||||
|
||||
|
||||
@@ -1,13 +1,12 @@
|
||||
---
|
||||
title: Установка и настройка
|
||||
title: SVG-спрайты
|
||||
description: Подключение SVG-спрайтов в новом проекте.
|
||||
keywords: [svg-sprites, установка, настройка, config, пакет, "@gromlab/svg-sprites", svg-sprites.config.ts]
|
||||
---
|
||||
|
||||
# Установка и настройка
|
||||
# SVG-спрайты
|
||||
|
||||
Первичная настройка пакета `@gromlab/svg-sprites` в проекте. Выполняется один раз при заведении проекта и при смене мажорной версии пакета.
|
||||
|
||||
Что такое спрайты, как с ними работать и как управлять цветом — [Использование](/docs/usage/svg-sprites).
|
||||
Подключение SVG-спрайтов в новом проекте.
|
||||
|
||||
## Требования
|
||||
|
||||
|
||||
@@ -1,13 +1,12 @@
|
||||
---
|
||||
title: Шаблоны генерации
|
||||
description: Подключение шаблонов кодогенерации в новом проекте.
|
||||
keywords: [шаблоны, templates, .templates, tiged, generator, генератор шаблонов, добавить шаблон, скачать шаблоны, scaffold]
|
||||
---
|
||||
|
||||
# Шаблоны генерации
|
||||
|
||||
Папка `.templates/` в корне проекта для генератора модулей `@gromlab/create`.
|
||||
|
||||
Синтаксис шаблонов и работа генератора — [Шаблоны и генерация кода](/docs/usage/templates-generation).
|
||||
Подключение шаблонов кодогенерации в новом проекте.
|
||||
|
||||
## Требования
|
||||
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
title: Настройка VS Code
|
||||
title: VS Code
|
||||
description: Единые настройки редактора и расширений для команды.
|
||||
---
|
||||
|
||||
# Настройка VS Code
|
||||
# VS Code
|
||||
|
||||
Каждый проект содержит папку `.vscode/` с конфигурацией редактора. Это гарантирует, что все участники команды работают с одинаковыми настройками форматирования, линтинга и расширениями.
|
||||
Единые настройки редактора и расширений для команды.
|
||||
|
||||
## Структура `.vscode/`
|
||||
|
||||
|
||||
@@ -1,13 +1,11 @@
|
||||
---
|
||||
title: Компоненты
|
||||
description: Как устроен и пишется React-компонент в проекте.
|
||||
---
|
||||
|
||||
# Компоненты
|
||||
|
||||
Правила написания React-компонентов: файловая структура модуля, типизация пропсов, документирование и реализация. Раздел охватывает компоненты всех слоёв — от `shared/ui` до `screens`.
|
||||
|
||||
Архитектурные слои и их назначение описаны в разделе [Архитектура](/docs/basics/architecture/).
|
||||
|
||||
Как устроен и пишется React-компонент в проекте.
|
||||
|
||||
## Правила организации
|
||||
|
||||
|
||||
@@ -1,11 +1,12 @@
|
||||
---
|
||||
title: Введение
|
||||
title: Источники данных
|
||||
description: Какие источники данных используются в проекте и как с ними работать.
|
||||
keywords: [данные, api, rest, realtime, клиент, swr, infrastructure, введение, карта раздела]
|
||||
---
|
||||
|
||||
# Введение
|
||||
# Источники данных
|
||||
|
||||
Работа с источниками данных в проекте: REST, realtime и любые другие каналы, которые появятся в будущем. Раздел описывает, как создаются клиенты для API и как полученные данные доходят до страниц и компонентов.
|
||||
Какие источники данных используются в проекте и как с ними работать.
|
||||
|
||||
## Принципы раздела
|
||||
|
||||
|
||||
@@ -1,13 +1,12 @@
|
||||
---
|
||||
title: Realtime
|
||||
description: "Работа с push-данными от сервера: подписки и события."
|
||||
keywords: [realtime, websocket, sse, подписка, swr subscription, useSWRSubscription, push, события]
|
||||
---
|
||||
|
||||
# Realtime
|
||||
|
||||
Канал для push-данных: WebSocket, SSE, событийные шины и любой другой источник, инициирующий передачу со стороны сервера. Транспорт не зашит в правила — важна абстракция «подписка».
|
||||
|
||||
Получение REST-данных — [REST](/docs/usage/data/rest/clients/auto).
|
||||
Работа с push-данными от сервера: подписки и события.
|
||||
|
||||
## Принципы
|
||||
|
||||
|
||||
@@ -1,13 +1,12 @@
|
||||
---
|
||||
title: Автоматическая генерация
|
||||
description: Генерация REST-клиента из OpenAPI-спецификации.
|
||||
keywords: [api, rest, openapi, codegen, генерация, клиент, api-codegen, gromlab, infrastructure, swagger-typescript-api]
|
||||
---
|
||||
|
||||
# Автоматическая генерация
|
||||
|
||||
Если у API есть OpenAPI-спецификация — клиент генерируется утилитой [@gromlab/api-codegen](https://gromlab.ru/gromov/api-codegen) (обёртка над `swagger-typescript-api`). Ручной код для таких API не пишется.
|
||||
|
||||
Когда схемы нет — [Ручное создание](/docs/usage/data/rest/clients/manual).
|
||||
Генерация REST-клиента из OpenAPI-спецификации.
|
||||
|
||||
В примерах ниже используется условный API `pet-project-api` (kebab-case в путях) / `petProjectApi` (camelCase в коде). В реальном проекте имена выбираются по конкретному API.
|
||||
|
||||
|
||||
@@ -1,13 +1,12 @@
|
||||
---
|
||||
title: Ручное создание
|
||||
description: "Создание REST-клиента вручную, когда нет OpenAPI-спецификации."
|
||||
keywords: [api, rest, клиент, ручной, fetch, infrastructure, api-клиент]
|
||||
---
|
||||
|
||||
# Ручное создание
|
||||
|
||||
Если у API нет OpenAPI-спецификации — клиент пишется и поддерживается вручную. Цель та же, что и у автогенерации: единая точка работы с API, без прямых `fetch` в коде приложения.
|
||||
|
||||
Когда схема есть — [Автоматическая генерация](/docs/usage/data/rest/clients/auto).
|
||||
Создание REST-клиента вручную, когда нет OpenAPI-спецификации.
|
||||
|
||||
В примерах ниже используется условный API `pet-project-api` / `petProjectApi`. В реальном проекте имена выбираются по конкретному API.
|
||||
|
||||
|
||||
@@ -1,13 +1,12 @@
|
||||
---
|
||||
title: Клиентские компоненты
|
||||
description: Получение REST-данных в клиентских компонентах.
|
||||
keywords: [swr, клиентские компоненты, useSWR, хук, мутация, useSWRMutation, кеш, ревалидация]
|
||||
---
|
||||
|
||||
# Клиентские компоненты
|
||||
|
||||
В клиентских компонентах данные получаются через **готовые хуки**, которые экспортируются из модуля API. SWR инкапсулирован в хуке — компонент не знает про `useSWR`, ключи и fetcher.
|
||||
|
||||
Создание клиента и хуков — [Автоматическая](/docs/usage/data/rest/clients/auto) / [Ручная](/docs/usage/data/rest/clients/manual) генерация.
|
||||
Получение REST-данных в клиентских компонентах.
|
||||
|
||||
## Правила
|
||||
|
||||
|
||||
@@ -1,13 +1,12 @@
|
||||
---
|
||||
title: Серверные компоненты
|
||||
description: Получение REST-данных в серверных компонентах.
|
||||
keywords: [server components, rsc, серверные компоненты, fetch, api, app router, прямой вызов]
|
||||
---
|
||||
|
||||
# Серверные компоненты
|
||||
|
||||
В серверных компонентах (Server Components App Router) данные получаются **прямым вызовом метода API-клиента**. SWR и хуки здесь не применяются — они для клиентского кода.
|
||||
|
||||
Создание клиента — [Автоматическая](/docs/usage/data/rest/clients/auto) / [Ручная](/docs/usage/data/rest/clients/manual) генерация.
|
||||
Получение REST-данных в серверных компонентах.
|
||||
|
||||
## Правила
|
||||
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
title: Файлы роутинга
|
||||
description: "Что должно лежать в файлах роутинга, а что — в экранах."
|
||||
---
|
||||
|
||||
# Файлы роутинга
|
||||
|
||||
Правила для специальных файлов App Router (`page.tsx`, `layout.tsx`, `error.tsx`, `not-found.tsx` и др.) — чем наш подход отличается от дефолтного.
|
||||
Что должно лежать в файлах роутинга, а что — в экранах.
|
||||
|
||||
## Организация
|
||||
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
title: Структура проекта
|
||||
description: Из чего состоит проект и где что лежит.
|
||||
---
|
||||
|
||||
# Структура проекта
|
||||
|
||||
Файловая организация Next.js-проекта по архитектуре SLM.
|
||||
Из чего состоит проект и где что лежит.
|
||||
|
||||
## Корень репозитория
|
||||
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
title: Использование
|
||||
title: Стили
|
||||
description: Как пишутся стили в проекте.
|
||||
---
|
||||
|
||||
# Использование
|
||||
# Стили
|
||||
|
||||
Правила написания CSS: PostCSS Modules, форматирование, переменные. Установка и настройка процессора — [PostCSS](/docs/setup/postcss).
|
||||
Как пишутся стили в проекте.
|
||||
|
||||
## Общие правила
|
||||
|
||||
|
||||
@@ -1,11 +1,12 @@
|
||||
---
|
||||
title: Использование
|
||||
title: SVG-спрайты
|
||||
description: Как добавлять и использовать SVG-иконки в коде.
|
||||
keywords: [svg, спрайт, sprite, иконка, icon, SvgSprite, превью, preview, цвет, color]
|
||||
---
|
||||
|
||||
# Использование
|
||||
# SVG-спрайты
|
||||
|
||||
Работа с SVG-иконками через сгенерированный компонент `<SvgSprite/>`. Установка пакета — [Установка и настройка](/docs/setup/svg-sprites).
|
||||
Как добавлять и использовать SVG-иконки в коде.
|
||||
|
||||
## Шаги
|
||||
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
title: Шаблоны и генерация кода
|
||||
description: Как устроены шаблоны кодогенерации и как ими пользоваться.
|
||||
---
|
||||
|
||||
<!-- @formatter:off -->
|
||||
@@ -7,7 +8,7 @@ title: Шаблоны и генерация кода
|
||||
|
||||
# Шаблоны и генерация кода
|
||||
|
||||
Как работают шаблоны, как их создавать, синтаксис переменных и как генерировать код с помощью расширения VS Code и CLI.
|
||||
Как устроены шаблоны кодогенерации и как ими пользоваться.
|
||||
|
||||
## Структура шаблонов
|
||||
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
title: Подсказки
|
||||
description: Короткие ответы на типовые вопросы и решения для спорных ситуаций.
|
||||
---
|
||||
|
||||
# Подсказки
|
||||
|
||||
Короткие ответы на типовые вопросы и направления в противоречивых ситуациях.
|
||||
Короткие ответы на типовые вопросы и решения для спорных ситуаций.
|
||||
|
||||
Reference in New Issue
Block a user