diff --git a/.vitepress/config.ts b/.vitepress/config.ts index 01a18b4..a617ee7 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -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' }, diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index df87192..fc6d3d8 100644 --- a/CONTRIBUTING.md +++ b/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 `. diff --git a/docs-overview.md b/docs-overview.md new file mode 100644 index 0000000..394ccc8 --- /dev/null +++ b/docs-overview.md @@ -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-данными от сервера: подписки и события. diff --git a/docs/docs/basics/architecture/index.md b/docs/docs/basics/architecture/index.md index eb15f39..4653ce2 100644 --- a/docs/docs/basics/architecture/index.md +++ b/docs/docs/basics/architecture/index.md @@ -1,9 +1,11 @@ --- -title: Архитектура +title: SLM Design +description: "Архитектурный подход проекта: что такое SLM и как он устроен." --- # SLM Design -Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили. + +Архитектурный подход проекта: что такое SLM и как он устроен. ## Преимущества diff --git a/docs/docs/basics/architecture/reference/layers.md b/docs/docs/basics/architecture/reference/layers.md index 56457d2..5bb065d 100644 --- a/docs/docs/basics/architecture/reference/layers.md +++ b/docs/docs/basics/architecture/reference/layers.md @@ -1,10 +1,11 @@ --- title: Слои +description: Из каких слоёв состоит архитектура и как они связаны. --- # Слои -Слои SLM: назначение, классификация, направление зависимостей, правила. +Из каких слоёв состоит архитектура и как они связаны. ## Определение diff --git a/docs/docs/basics/architecture/reference/modules.md b/docs/docs/basics/architecture/reference/modules.md index bd71c9d..224f5c8 100644 --- a/docs/docs/basics/architecture/reference/modules.md +++ b/docs/docs/basics/architecture/reference/modules.md @@ -1,10 +1,11 @@ --- title: Модули +description: Что такое модуль в архитектуре и как он устроен. --- # Модули -Модули SLM: состав, границы, взаимодействие с остальным кодом. +Что такое модуль в архитектуре и как он устроен. ## Определение diff --git a/docs/docs/basics/architecture/reference/segments.md b/docs/docs/basics/architecture/reference/segments.md index 0d095f9..92ebf39 100644 --- a/docs/docs/basics/architecture/reference/segments.md +++ b/docs/docs/basics/architecture/reference/segments.md @@ -1,10 +1,11 @@ --- title: Сегменты +description: Что такое сегмент модуля и какие они бывают. --- # Сегменты -Сегменты SLM: типы, назначение, что лежит внутри каждого. +Что такое сегмент модуля и какие они бывают. ## Определение diff --git a/docs/docs/basics/code-style.md b/docs/docs/basics/code-style.md index 232f0ee..e47e625 100644 --- a/docs/docs/basics/code-style.md +++ b/docs/docs/basics/code-style.md @@ -1,10 +1,11 @@ --- title: Стиль кода +description: Как оформляется код в проекте. --- # Стиль кода -Единые правила оформления кода: форматирование, импорты, читаемость. +Как оформляется код в проекте. ## Отступы diff --git a/docs/docs/basics/documentation.md b/docs/docs/basics/documentation.md index bfed283..81abcf1 100644 --- a/docs/docs/basics/documentation.md +++ b/docs/docs/basics/documentation.md @@ -1,10 +1,11 @@ --- title: Документирование +description: Что и как документировать в коде. --- # Документирование -Правила документирования кода: что и когда документировать через JSDoc. +Что и как документировать в коде. ## Общие правила diff --git a/docs/docs/basics/naming.md b/docs/docs/basics/naming.md index b4148a0..71e4a45 100644 --- a/docs/docs/basics/naming.md +++ b/docs/docs/basics/naming.md @@ -1,10 +1,11 @@ --- title: Именование +description: Как называть переменные, файлы и прочие сущности в коде. --- # Именование -Соглашения об именовании в коде: что и как называть. +Как называть переменные, файлы и прочие сущности в коде. ## Базовые правила diff --git a/docs/docs/basics/tech-stack.md b/docs/docs/basics/tech-stack.md index b894be0..a42d452 100644 --- a/docs/docs/basics/tech-stack.md +++ b/docs/docs/basics/tech-stack.md @@ -1,10 +1,11 @@ --- title: Технологии и библиотеки +description: Какие библиотеки и инструменты используются в проекте. --- # Технологии и библиотеки -Базовый стек проекта по областям: UI, архитектура, данные, состояние, локализация, тестирование, стили, генерация кода. +Какие библиотеки и инструменты используются в проекте. ## Что используем diff --git a/docs/docs/basics/typing.md b/docs/docs/basics/typing.md index c125e51..c14743d 100644 --- a/docs/docs/basics/typing.md +++ b/docs/docs/basics/typing.md @@ -1,10 +1,11 @@ --- title: Типизация +description: Как типизируется код в проекте. --- # Типизация -Правила типизации в TypeScript: общие принципы и работа с динамическими типами. +Как типизируется код в проекте. ## Общие правила diff --git a/docs/docs/creating-project/from-template.md b/docs/docs/creating-project/from-template.md index 58e25fd..c549640 100644 --- a/docs/docs/creating-project/from-template.md +++ b/docs/docs/creating-project/from-template.md @@ -1,12 +1,12 @@ --- title: Создание проекта из шаблона +description: Создание нового проекта на основе готового шаблона. keywords: [создать проект из шаблона, шаблон, template, tiged, degit, клонировать шаблон, эталонный шаблон, быстрый старт, scaffold, новый проект] --- # Создание проекта из шаблона -Раздел описывает процесс создания нового проекта на основе готового шаблона. -Шаблоны включают преднастроенный код-стайл, структуру проекта и необходимые конфигурации, что позволяет начать работу без дополнительной настройки. +Создание нового проекта на основе готового шаблона. ## Что внутри diff --git a/docs/docs/creating-project/manual.md b/docs/docs/creating-project/manual.md index 47052dc..774d26b 100644 --- a/docs/docs/creating-project/manual.md +++ b/docs/docs/creating-project/manual.md @@ -1,15 +1,12 @@ --- -title: Вручную +title: Создание проекта вручную +description: Поэтапное создание нового проекта без использования шаблона. keywords: [создать проект, новый проект, с нуля, init, initialize, scaffold, create-next-app, начать проект, поднять проект, эталонный проект, ручная установка] --- # Создание проекта вручную -Раздел описывает процесс поэтапного создания Next.js-проекта без использования шаблона.Все настройки, включая структуру проекта, код-стайл и конфигурацию, выполняются вручную, что позволяет полностью контролировать каждый шаг. - -Рекомендуется использовать этот подход, если требуется тонкая настройка проекта или шаблон недоступен. В остальных случаях проще воспользоваться созданием проекта из шаблона. - -Если шаблон доступен — быстрее использовать [Создание проекта из шаблона](/docs/creating-project/from-template). +Поэтапное создание нового проекта без использования шаблона. ## Состав эталонного проекта diff --git a/docs/docs/creating-project/nextjs.md b/docs/docs/creating-project/nextjs.md index b56fb92..f37abbe 100644 --- a/docs/docs/creating-project/nextjs.md +++ b/docs/docs/creating-project/nextjs.md @@ -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 без лишнего шаблона — голый каркас под дальнейшую сборку. ## Требования diff --git a/docs/docs/index.md b/docs/docs/index.md index b88fa92..2448d4f 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -1,6 +1,11 @@ +--- +title: NextJS Style Guide +description: Стандарты разработки фронтенд-приложений на Next.js и TypeScript. +--- + # NextJS Style Guide -Соглашения по разработке Next.js проектов: архитектура и слои приложения, структура кода, организация модулей, стилизация, типизация и инфраструктура. +Стандарты разработки фронтенд-приложений на Next.js и TypeScript. ## Использование diff --git a/docs/docs/setup/aliases.md b/docs/docs/setup/aliases.md index 0dc2c09..2fcb6c1 100644 --- a/docs/docs/setup/aliases.md +++ b/docs/docs/setup/aliases.md @@ -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). +Какие алиасы импортов есть в проекте и как ими пользоваться. ## Конфиг diff --git a/docs/docs/setup/biome.md b/docs/docs/setup/biome.md index e96389f..791dc62 100644 --- a/docs/docs/setup/biome.md +++ b/docs/docs/setup/biome.md @@ -1,11 +1,12 @@ --- title: Biome +description: Установка и настройка линтера-форматтера в новом проекте. keywords: [biome, линтер, форматтер, lint, format, biome.json, "@biomejs/biome", замена eslint, замена prettier] --- # Biome -Единый линтер и форматтер для JS/TS/JSON в проекте. Заменяет связку ESLint + Prettier одним инструментом. +Установка и настройка линтера-форматтера в новом проекте. ## Требования diff --git a/docs/docs/setup/postcss.md b/docs/docs/setup/postcss.md index 3f0e120..bb80eae 100644 --- a/docs/docs/setup/postcss.md +++ b/docs/docs/setup/postcss.md @@ -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 diff --git a/docs/docs/setup/styles.md b/docs/docs/setup/styles.md index b70dce6..f73e19e 100644 --- a/docs/docs/setup/styles.md +++ b/docs/docs/setup/styles.md @@ -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). +Подготовка стилевой основы проекта: токены, медиа-запросы, глобальные стили. ## Требования diff --git a/docs/docs/setup/svg-sprites.md b/docs/docs/setup/svg-sprites.md index b1f63fc..df6ce08 100644 --- a/docs/docs/setup/svg-sprites.md +++ b/docs/docs/setup/svg-sprites.md @@ -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-спрайтов в новом проекте. ## Требования diff --git a/docs/docs/setup/templates.md b/docs/docs/setup/templates.md index 7e75a1d..acb5cfb 100644 --- a/docs/docs/setup/templates.md +++ b/docs/docs/setup/templates.md @@ -1,13 +1,12 @@ --- title: Шаблоны генерации +description: Подключение шаблонов кодогенерации в новом проекте. keywords: [шаблоны, templates, .templates, tiged, generator, генератор шаблонов, добавить шаблон, скачать шаблоны, scaffold] --- # Шаблоны генерации -Папка `.templates/` в корне проекта для генератора модулей `@gromlab/create`. - -Синтаксис шаблонов и работа генератора — [Шаблоны и генерация кода](/docs/usage/templates-generation). +Подключение шаблонов кодогенерации в новом проекте. ## Требования diff --git a/docs/docs/setup/vscode.md b/docs/docs/setup/vscode.md index f9d7607..f844ead 100644 --- a/docs/docs/setup/vscode.md +++ b/docs/docs/setup/vscode.md @@ -1,10 +1,11 @@ --- -title: Настройка VS Code +title: VS Code +description: Единые настройки редактора и расширений для команды. --- -# Настройка VS Code +# VS Code -Каждый проект содержит папку `.vscode/` с конфигурацией редактора. Это гарантирует, что все участники команды работают с одинаковыми настройками форматирования, линтинга и расширениями. +Единые настройки редактора и расширений для команды. ## Структура `.vscode/` diff --git a/docs/docs/usage/components.md b/docs/docs/usage/components.md index fd2d07c..1717228 100644 --- a/docs/docs/usage/components.md +++ b/docs/docs/usage/components.md @@ -1,13 +1,11 @@ --- title: Компоненты +description: Как устроен и пишется React-компонент в проекте. --- # Компоненты -Правила написания React-компонентов: файловая структура модуля, типизация пропсов, документирование и реализация. Раздел охватывает компоненты всех слоёв — от `shared/ui` до `screens`. - -Архитектурные слои и их назначение описаны в разделе [Архитектура](/docs/basics/architecture/). - +Как устроен и пишется React-компонент в проекте. ## Правила организации diff --git a/docs/docs/usage/data/index.md b/docs/docs/usage/data/index.md index 35c3702..062e426 100644 --- a/docs/docs/usage/data/index.md +++ b/docs/docs/usage/data/index.md @@ -1,11 +1,12 @@ --- -title: Введение +title: Источники данных +description: Какие источники данных используются в проекте и как с ними работать. keywords: [данные, api, rest, realtime, клиент, swr, infrastructure, введение, карта раздела] --- -# Введение +# Источники данных -Работа с источниками данных в проекте: REST, realtime и любые другие каналы, которые появятся в будущем. Раздел описывает, как создаются клиенты для API и как полученные данные доходят до страниц и компонентов. +Какие источники данных используются в проекте и как с ними работать. ## Принципы раздела diff --git a/docs/docs/usage/data/realtime.md b/docs/docs/usage/data/realtime.md index 8d736e0..7463cfe 100644 --- a/docs/docs/usage/data/realtime.md +++ b/docs/docs/usage/data/realtime.md @@ -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-данными от сервера: подписки и события. ## Принципы diff --git a/docs/docs/usage/data/rest/clients/auto.md b/docs/docs/usage/data/rest/clients/auto.md index c242820..4de1ac8 100644 --- a/docs/docs/usage/data/rest/clients/auto.md +++ b/docs/docs/usage/data/rest/clients/auto.md @@ -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. diff --git a/docs/docs/usage/data/rest/clients/manual.md b/docs/docs/usage/data/rest/clients/manual.md index 390558e..80f03c6 100644 --- a/docs/docs/usage/data/rest/clients/manual.md +++ b/docs/docs/usage/data/rest/clients/manual.md @@ -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. diff --git a/docs/docs/usage/data/rest/fetching/client.md b/docs/docs/usage/data/rest/fetching/client.md index 501eb2b..8160caf 100644 --- a/docs/docs/usage/data/rest/fetching/client.md +++ b/docs/docs/usage/data/rest/fetching/client.md @@ -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-данных в клиентских компонентах. ## Правила diff --git a/docs/docs/usage/data/rest/fetching/server.md b/docs/docs/usage/data/rest/fetching/server.md index c9bb91c..d119ebb 100644 --- a/docs/docs/usage/data/rest/fetching/server.md +++ b/docs/docs/usage/data/rest/fetching/server.md @@ -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-данных в серверных компонентах. ## Правила diff --git a/docs/docs/usage/page-level.md b/docs/docs/usage/page-level.md index e9a8585..f7e1e48 100644 --- a/docs/docs/usage/page-level.md +++ b/docs/docs/usage/page-level.md @@ -1,10 +1,11 @@ --- title: Файлы роутинга +description: "Что должно лежать в файлах роутинга, а что — в экранах." --- # Файлы роутинга -Правила для специальных файлов App Router (`page.tsx`, `layout.tsx`, `error.tsx`, `not-found.tsx` и др.) — чем наш подход отличается от дефолтного. +Что должно лежать в файлах роутинга, а что — в экранах. ## Организация diff --git a/docs/docs/usage/project-structure.md b/docs/docs/usage/project-structure.md index f85fdc9..ae4751a 100644 --- a/docs/docs/usage/project-structure.md +++ b/docs/docs/usage/project-structure.md @@ -1,10 +1,11 @@ --- title: Структура проекта +description: Из чего состоит проект и где что лежит. --- # Структура проекта -Файловая организация Next.js-проекта по архитектуре SLM. +Из чего состоит проект и где что лежит. ## Корень репозитория diff --git a/docs/docs/usage/styles.md b/docs/docs/usage/styles.md index 039e7d5..8972a75 100644 --- a/docs/docs/usage/styles.md +++ b/docs/docs/usage/styles.md @@ -1,10 +1,11 @@ --- -title: Использование +title: Стили +description: Как пишутся стили в проекте. --- -# Использование +# Стили -Правила написания CSS: PostCSS Modules, форматирование, переменные. Установка и настройка процессора — [PostCSS](/docs/setup/postcss). +Как пишутся стили в проекте. ## Общие правила diff --git a/docs/docs/usage/svg-sprites.md b/docs/docs/usage/svg-sprites.md index 28f8d4c..2f37f26 100644 --- a/docs/docs/usage/svg-sprites.md +++ b/docs/docs/usage/svg-sprites.md @@ -1,11 +1,12 @@ --- -title: Использование +title: SVG-спрайты +description: Как добавлять и использовать SVG-иконки в коде. keywords: [svg, спрайт, sprite, иконка, icon, SvgSprite, превью, preview, цвет, color] --- -# Использование +# SVG-спрайты -Работа с SVG-иконками через сгенерированный компонент ``. Установка пакета — [Установка и настройка](/docs/setup/svg-sprites). +Как добавлять и использовать SVG-иконки в коде. ## Шаги diff --git a/docs/docs/usage/templates-generation.md b/docs/docs/usage/templates-generation.md index 0344a86..58b690e 100644 --- a/docs/docs/usage/templates-generation.md +++ b/docs/docs/usage/templates-generation.md @@ -1,5 +1,6 @@ --- title: Шаблоны и генерация кода +description: Как устроены шаблоны кодогенерации и как ими пользоваться. --- @@ -7,7 +8,7 @@ title: Шаблоны и генерация кода # Шаблоны и генерация кода -Как работают шаблоны, как их создавать, синтаксис переменных и как генерировать код с помощью расширения VS Code и CLI. +Как устроены шаблоны кодогенерации и как ими пользоваться. ## Структура шаблонов diff --git a/docs/docs/workflow.md b/docs/docs/workflow.md index 45c28a6..c060231 100644 --- a/docs/docs/workflow.md +++ b/docs/docs/workflow.md @@ -1,7 +1,8 @@ --- title: Подсказки +description: Короткие ответы на типовые вопросы и решения для спорных ситуаций. --- # Подсказки -Короткие ответы на типовые вопросы и направления в противоречивых ситуациях. +Короткие ответы на типовые вопросы и решения для спорных ситуаций.