refactor(docs): объединить setup/ и usage/ в прикладные разделы
- Директории setup/ и usage/ объединены в applied/ с подпапками для парных разделов - Раздел «Работа с данными» вынесен на верхний уровень в data/ - Шаблоны генерации разделены на 4 файла: введение, настройка, создание, использование - Обновлён сайдбар, CONTRIBUTING.md, MAP.md и все внутренние ссылки - Обновлены требования и содержимое разделов (стили, шаблоны, SVG-спрайты)
This commit is contained in:
@@ -38,63 +38,79 @@ const sidebar = [
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'Настройка',
|
||||
text: 'Работа с данными',
|
||||
// collapsed: true,
|
||||
items: [
|
||||
{ text: 'Алиасы импортов', link: '/docs/setup/aliases' },
|
||||
{ text: 'Biome', link: '/docs/setup/biome' },
|
||||
{ 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' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'Использование',
|
||||
items: [
|
||||
{ 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: 'Данные',
|
||||
items: [
|
||||
{ text: 'Введение', link: '/docs/usage/data/' },
|
||||
{ text: 'Введение', link: '/docs/data/' },
|
||||
{
|
||||
text: 'REST',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{
|
||||
text: 'Клиенты',
|
||||
text: 'Настройка',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: 'Автоматическая генерация', link: '/docs/usage/data/rest/clients/auto' },
|
||||
{ text: 'Ручное создание', link: '/docs/usage/data/rest/clients/manual' },
|
||||
{ text: 'Автоматическая генерация', link: '/docs/data/rest/clients/auto' },
|
||||
{ text: 'Ручное создание', link: '/docs/data/rest/clients/manual' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'Получение данных',
|
||||
text: 'Использование',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: 'Серверные компоненты', link: '/docs/usage/data/rest/fetching/server' },
|
||||
{ text: 'Клиентские компоненты', link: '/docs/usage/data/rest/fetching/client' },
|
||||
{ text: 'Серверные компоненты', link: '/docs/data/rest/fetching/server' },
|
||||
{ text: 'Клиентские компоненты', link: '/docs/data/rest/fetching/client' },
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
{ text: 'Realtime', link: '/docs/usage/data/realtime' },
|
||||
{ text: 'Realtime', link: '/docs/data/realtime' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'Прикладные разделы',
|
||||
items: [
|
||||
{ text: 'Алиасы импортов', link: '/docs/applied/aliases' },
|
||||
{ text: 'Biome', link: '/docs/applied/biome' },
|
||||
{ text: 'PostCSS', link: '/docs/applied/postcss' },
|
||||
{ text: 'VS Code', link: '/docs/applied/vscode' },
|
||||
{
|
||||
text: 'Стили',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: 'Настройка', link: '/docs/applied/styles/styles-setup' },
|
||||
{ text: 'Использование', link: '/docs/applied/styles/styles-usage' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'SVG-спрайты',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: 'Настройка', link: '/docs/applied/svg-sprites/svg-sprites-setup' },
|
||||
{ text: 'Использование', link: '/docs/applied/svg-sprites/svg-sprites-usage' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'Шаблоны генерации',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: 'Введение', link: '/docs/applied/templates/templates-intro' },
|
||||
{ text: 'Настройка', link: '/docs/applied/templates/templates-setup' },
|
||||
{ text: 'Создание шаблонов', link: '/docs/applied/templates/templates-create' },
|
||||
{ text: 'Использование', link: '/docs/applied/templates/templates-usage' },
|
||||
],
|
||||
},
|
||||
{ text: 'Структура проекта', link: '/docs/applied/project-structure' },
|
||||
{ text: 'Компоненты', link: '/docs/applied/components' },
|
||||
{ text: 'Страницы (App Router)', link: '/docs/applied/page-level' },
|
||||
// Неактивные разделы: страницы существуют, но пока пустые.
|
||||
// Оставляем в sidebar без `link`, чтобы видеть план, но без перехода.
|
||||
{ text: 'Изображения · в разработке' },
|
||||
{ text: 'Видео · в разработке' },
|
||||
{ text: 'Stores · в разработке' },
|
||||
{ text: 'Хуки · в разработке' },
|
||||
{ text: 'Шрифты · в разработке' },
|
||||
{ text: 'Локализация · в разработке' }
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
@@ -37,22 +37,24 @@ docs/
|
||||
│ ├── from-template.md
|
||||
│ ├── manual.md
|
||||
│ └── nextjs.md
|
||||
├── setup/ # Настройка: разовая настройка инструментов
|
||||
│ ├── aliases.md
|
||||
│ ├── biome.md
|
||||
│ ├── postcss.md
|
||||
│ ├── styles.md
|
||||
│ ├── svg-sprites.md
|
||||
│ ├── templates.md
|
||||
│ └── vscode.md
|
||||
└── usage/ # Использование: повседневная работа
|
||||
└── applied/ # Прикладные разделы: настройка и использование
|
||||
├── aliases.md
|
||||
├── biome.md
|
||||
├── postcss.md
|
||||
├── vscode.md
|
||||
├── styles/ # Стили: настройка + использование
|
||||
│ ├── styles-setup.md
|
||||
│ └── styles-usage.md
|
||||
├── svg-sprites/ # SVG-спрайты: настройка + использование
|
||||
│ ├── svg-sprites-setup.md
|
||||
│ └── svg-sprites-usage.md
|
||||
├── templates/ # Шаблоны генерации: настройка + использование
|
||||
│ ├── templates-setup.md
|
||||
│ └── templates-usage.md
|
||||
├── project-structure.md
|
||||
├── components.md
|
||||
├── page-level.md
|
||||
├── templates-generation.md
|
||||
├── styles.md
|
||||
├── images-sprites.md
|
||||
├── svg-sprites.md
|
||||
├── video.md
|
||||
├── data/
|
||||
├── stores.md
|
||||
@@ -70,7 +72,7 @@ generate-llms.ts # Скрипт генерации llms.txt и R
|
||||
### Добавление нового раздела
|
||||
|
||||
1. Создать `.md`-файл в нужной папке: `basics/`, `creating-project/`,
|
||||
`setup/` или `usage/`.
|
||||
или `applied/`.
|
||||
2. Добавить пункт в сайдбар — `.vitepress/config.ts`.
|
||||
Сайдбар — единственный источник порядка и группировки для `llms.txt`.
|
||||
3. Запустить `npm run llms` для обновления `llms.txt` и README.
|
||||
@@ -100,36 +102,27 @@ generate-llms.ts # Скрипт генерации llms.txt и R
|
||||
|
||||
Сценарии запуска нового проекта целиком: из шаблона, вручную, чистая
|
||||
установка фреймворка. Раздел описывает порядок шагов на уровне всего
|
||||
проекта; детали отдельных инструментов лежат в `setup/`.
|
||||
проекта; детали отдельных инструментов лежат в `applied/`.
|
||||
|
||||
**Граница:** не дублирует разделы `setup/`. Ссылается на них как на
|
||||
**Граница:** не дублирует разделы `applied/`. Ссылается на них как на
|
||||
шаги в общем сценарии.
|
||||
|
||||
### Настройка (`setup/`)
|
||||
### Прикладные разделы (`applied/`)
|
||||
|
||||
**Отвечает на вопрос:** «Как поставить и сконфигурировать инструмент
|
||||
в новом проекте?»
|
||||
**Отвечает на вопрос:** «Как поставить инструмент и как им пользоваться?»
|
||||
|
||||
Разовая установка отдельного инструмента или подсистемы (линтер,
|
||||
CSS-процессор, генератор спрайтов, шаблоны). Каждый раздел —
|
||||
самостоятельная подсистема. Выполняется один раз при заведении
|
||||
проекта или при смене мажорной версии инструмента.
|
||||
Прикладные разделы объединяют настройку и использование инструментов
|
||||
и подсистем. Каждый раздел — самостоятельная предметная область.
|
||||
|
||||
Типичная структура `setup/`-страницы: требования → установка (шаги) →
|
||||
конфиг → проверка.
|
||||
Разделы делятся на два типа:
|
||||
|
||||
**Граница:** `setup/` — про настройку, `usage/` — про написание кода
|
||||
с использованием уже настроенного инструмента.
|
||||
1. **Только настройка** — разовая установка инструмента (линтер,
|
||||
CSS-процессор, алиасы). Файл без суффикса: `biome.md`, `postcss.md`.
|
||||
|
||||
### Использование (`usage/`)
|
||||
|
||||
**Отвечает на вопрос:** «Как этим пользоваться в коде?»
|
||||
|
||||
Повседневная работа: как писать компоненты, стили, как получать данные,
|
||||
как работать со сторами, локализацией, ассетами. Полное описание
|
||||
конкретной области: структура файлов, правила, именование, типизация, примеры.
|
||||
|
||||
Шаблон страницы описан ниже в секции «Структура прикладного раздела».
|
||||
2. **Настройка + использование** — область, требующая и установки,
|
||||
и повседневных правил. Два файла с суффиксами: `styles-setup.md`
|
||||
(настройка) и `styles-usage.md` (использование). В сайдбаре
|
||||
оборачиваются в collapsed-группу.
|
||||
|
||||
**Граница:** прикладной раздел не дублирует базовые правила. Если правило
|
||||
уже описано в `basics/` — прикладной раздел ссылается на него, но не
|
||||
@@ -137,9 +130,9 @@ CSS-процессор, генератор спрайтов, шаблоны). К
|
||||
|
||||
## Структура прикладного раздела
|
||||
|
||||
Шаблон ниже относится к разделам `usage/` (повседневная работа).
|
||||
Разделы `setup/` и `creating-project/` имеют другую структуру —
|
||||
ориентированную на пошаговую установку (требования → установка →
|
||||
Шаблон ниже относится к usage-страницам прикладных разделов (`applied/*-usage.md`).
|
||||
Setup-страницы (`applied/*-setup.md`) и `creating-project/` имеют другую
|
||||
структуру — ориентированную на пошаговую установку (требования → установка →
|
||||
проверка).
|
||||
|
||||
Шаблон описывает все допустимые секции. Раздел включает только те,
|
||||
|
||||
@@ -25,30 +25,29 @@
|
||||
- [По гайду вручную](./creating-project/manual.md) — Поэтапное создание нового проекта без использования шаблона.
|
||||
- [Чистый Next.js](./creating-project/nextjs.md) — Установка Next.js без лишнего шаблона — голый каркас под дальнейшую сборку.
|
||||
|
||||
## Настройка
|
||||
## Работа с данными
|
||||
|
||||
- [Алиасы импортов](./setup/aliases.md) — Какие алиасы импортов есть в проекте и как ими пользоваться.
|
||||
- [Biome](./setup/biome.md) — Установка и настройка линтера-форматтера в новом проекте.
|
||||
- [PostCSS](./setup/postcss.md) — Установка и настройка CSS-процессора в новом проекте.
|
||||
- [Стили](./setup/styles.md) — Подготовка стилевой основы проекта: токены, медиа-запросы, глобальные стили.
|
||||
- [SVG-спрайты](./setup/svg-sprites.md) — Подключение SVG-спрайтов в новом проекте.
|
||||
- [Шаблоны генерации](./setup/templates.md) — Подключение шаблонов кодогенерации в новом проекте.
|
||||
- [VS Code](./setup/vscode.md) — Единые настройки редактора и расширений для команды.
|
||||
- [Введение](./data/index.md) — Какие источники данных используются в проекте и как с ними работать.
|
||||
- [REST: Настройка: Автоматическая генерация](./data/rest/clients/auto.md) — Генерация REST-клиента из OpenAPI-спецификации.
|
||||
- [REST: Настройка: Ручное создание](./data/rest/clients/manual.md) — Создание REST-клиента вручную, когда нет OpenAPI-спецификации.
|
||||
- [REST: Использование: Серверные компоненты](./data/rest/fetching/server.md) — Получение REST-данных в серверных компонентах.
|
||||
- [REST: Использование: Клиентские компоненты](./data/rest/fetching/client.md) — Получение REST-данных в клиентских компонентах.
|
||||
- [Realtime](./data/realtime.md) — Работа с push-данными от сервера: подписки и события.
|
||||
|
||||
## Использование
|
||||
## Прикладные разделы
|
||||
|
||||
- [Структура проекта](./usage/project-structure.md) — Из чего состоит проект и где что лежит.
|
||||
- [Компоненты](./usage/components.md) — Как устроен и пишется React-компонент в проекте.
|
||||
- [Страницы (App Router)](./usage/page-level.md) — Что должно лежать в файлах роутинга, а что — в экранах.
|
||||
- [Шаблоны и генерация кода](./usage/templates-generation.md) — Как устроены шаблоны кодогенерации и как ими пользоваться.
|
||||
- [Стили](./usage/styles.md) — Как пишутся стили в проекте.
|
||||
- [SVG-спрайты](./usage/svg-sprites.md) — Как добавлять и использовать SVG-иконки в коде.
|
||||
|
||||
## Данные
|
||||
|
||||
- [Введение](./usage/data/index.md) — Какие источники данных используются в проекте и как с ними работать.
|
||||
- [REST: Клиенты: Автоматическая генерация](./usage/data/rest/clients/auto.md) — Генерация REST-клиента из OpenAPI-спецификации.
|
||||
- [REST: Клиенты: Ручное создание](./usage/data/rest/clients/manual.md) — Создание REST-клиента вручную, когда нет OpenAPI-спецификации.
|
||||
- [REST: Получение данных: Серверные компоненты](./usage/data/rest/fetching/server.md) — Получение REST-данных в серверных компонентах.
|
||||
- [REST: Получение данных: Клиентские компоненты](./usage/data/rest/fetching/client.md) — Получение REST-данных в клиентских компонентах.
|
||||
- [Realtime](./usage/data/realtime.md) — Работа с push-данными от сервера: подписки и события.
|
||||
- [Алиасы импортов](./applied/aliases.md) — Какие алиасы импортов есть в проекте и как ими пользоваться.
|
||||
- [Biome](./applied/biome.md) — Установка и настройка линтера-форматтера в новом проекте.
|
||||
- [PostCSS](./applied/postcss.md) — Установка и настройка CSS-процессора в новом проекте.
|
||||
- [VS Code](./applied/vscode.md) — Единые настройки редактора и расширений для команды.
|
||||
- [Стили: Настройка](./applied/styles/styles-setup.md) — Подготовка стилевой основы проекта: токены, медиа-запросы, глобальные стили.
|
||||
- [Стили: Использование](./applied/styles/styles-usage.md) — Как пишутся стили в проекте.
|
||||
- [SVG-спрайты: Настройка](./applied/svg-sprites/svg-sprites-setup.md) — Подключение SVG-спрайтов в новом проекте.
|
||||
- [SVG-спрайты: Использование](./applied/svg-sprites/svg-sprites-usage.md) — Как добавлять и использовать SVG-иконки в коде.
|
||||
- [Шаблоны генерации](./applied/templates/templates-intro.md) — Что такое шаблоны кодогенерации и какие проблемы они решают.
|
||||
- [Шаблоны генерации: Настройка](./applied/templates/templates-setup.md) — Первичная установка шаблонов кодогенерации в проект.
|
||||
- [Шаблоны генерации: Создание шаблонов](./applied/templates/templates-create.md) — Структура шаблонов, синтаксис переменных и примеры.
|
||||
- [Шаблоны генерации: Использование](./applied/templates/templates-usage.md) — Генерация файлов из шаблонов через VS Code плагин и CLI.
|
||||
- [Структура проекта](./applied/project-structure.md) — Из чего состоит проект и где что лежит.
|
||||
- [Компоненты](./applied/components.md) — Как устроен и пишется React-компонент в проекте.
|
||||
- [Страницы (App Router)](./applied/page-level.md) — Что должно лежать в файлах роутинга, а что — в экранах.
|
||||
|
||||
@@ -78,4 +78,4 @@ keywords: [biome, линтер, форматтер, lint, format, biome.json, "@
|
||||
|
||||
## Интеграция с VS Code
|
||||
|
||||
Расширение `biomejs.biome` и автоформатирование при сохранении настраиваются в [Настройка VS Code](/docs/setup/vscode).
|
||||
Расширение `biomejs.biome` и автоформатирование при сохранении настраиваются в [VS Code](/docs/applied/vscode).
|
||||
@@ -67,4 +67,4 @@ export default {
|
||||
|
||||
Опция `importFrom` у `postcss-custom-media` удалена в v10+; её роль теперь выполняет `@csstools/postcss-global-data`.
|
||||
|
||||
Импортировать `media.css` в файлы компонентов **не нужно** и запрещено правилами (см. [Использование](/docs/usage/styles), раздел «Импорт стилей»).
|
||||
Импортировать `media.css` в файлы компонентов **не нужно** и запрещено правилами (см. [Использование стилей](/docs/applied/styles/styles-usage), раздел «Импорт стилей»).
|
||||
@@ -79,7 +79,7 @@ src/app/
|
||||
└── store/ # Шаблон стора
|
||||
```
|
||||
|
||||
Подробнее о генерации описано в разделе [Шаблоны и генерация кода](./templates-generation).
|
||||
Подробнее о генерации описано в разделе [Шаблоны генерации](/docs/applied/templates/templates-intro).
|
||||
|
||||
## Конфигурационные файлы
|
||||
|
||||
@@ -1,17 +1,16 @@
|
||||
---
|
||||
title: Стили
|
||||
title: Настройка стилей
|
||||
description: "Подготовка стилевой основы проекта: токены, медиа-запросы, глобальные стили."
|
||||
keywords: [variables.css, media.css, global.css, shared/styles, токены, переменные, custom-media, breakpoints, подключение стилей, базовые стили, инициализация]
|
||||
---
|
||||
|
||||
# Стили
|
||||
# Настройка стилей
|
||||
|
||||
Подготовка стилевой основы проекта: токены, медиа-запросы, глобальные стили.
|
||||
|
||||
## Требования
|
||||
|
||||
- Структура `src/` соответствует SLM ([Структура проекта](/docs/usage/project-structure)). Глобальные стили живут в `src/shared/styles/`, не в `src/app/`.
|
||||
- В проекте нет `globals.css` с кастомным содержимым и не установлен `tailwindcss`.
|
||||
- Установлен PostCSS или любой другой pre/post-процессор с поддержкой `@custom-media`.
|
||||
|
||||
## Файлы
|
||||
|
||||
@@ -27,7 +26,7 @@ keywords: [variables.css, media.css, global.css, shared/styles, токены, п
|
||||
|
||||
- В приложение импортируется **только** `global.css`.
|
||||
- `variables.css` и будущие глобальные файлы (резеты, темы, типографика) подключаются в `global.css` через `@import`.
|
||||
- `media.css` **не импортируется** — ни в `global.css`, ни в компоненты, ни в точку инициализации. Его читает CSS-процессор на этапе сборки (см. [PostCSS](/docs/setup/postcss)).
|
||||
- `media.css` **не импортируется** — ни в `global.css`, ни в компоненты, ни в точку инициализации. Его читает CSS-процессор на этапе сборки (см. [PostCSS](/docs/applied/postcss)).
|
||||
|
||||
## Корневой `font-size`
|
||||
|
||||
@@ -172,6 +171,6 @@ export default function RootLayout({ children }: { children: React.ReactNode })
|
||||
|
||||
## Дальше
|
||||
|
||||
- [PostCSS](/docs/setup/postcss) — подключить процессор, чтобы заработали `@media (--md)` и вложенность.
|
||||
- [Стили: использование](/docs/usage/styles) — правила написания CSS в компонентах.
|
||||
- [SVG-спрайты](/docs/setup/svg-sprites) — стили иконок отдельно от глобальных.
|
||||
- [PostCSS](/docs/applied/postcss) — подключить процессор, чтобы заработали `@media (--md)` и вложенность.
|
||||
- [Использование стилей](/docs/applied/styles/styles-usage) — правила написания CSS в компонентах.
|
||||
- [SVG-спрайты](/docs/applied/svg-sprites/svg-sprites-setup) — стили иконок отдельно от глобальных.
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
title: Стили
|
||||
title: Использование стилей
|
||||
description: Как пишутся стили в проекте.
|
||||
---
|
||||
|
||||
# Стили
|
||||
# Использование стилей
|
||||
|
||||
Как пишутся стили в проекте.
|
||||
|
||||
@@ -1,18 +1,12 @@
|
||||
---
|
||||
title: SVG-спрайты
|
||||
title: Настройка SVG-спрайтов
|
||||
description: Подключение SVG-спрайтов в новом проекте.
|
||||
keywords: [svg-sprites, установка, настройка, config, пакет, "@gromlab/svg-sprites", svg-sprites.config.ts]
|
||||
---
|
||||
|
||||
# SVG-спрайты
|
||||
|
||||
# Настройка SVG-спрайтов
|
||||
Подключение SVG-спрайтов в новом проекте.
|
||||
|
||||
## Требования
|
||||
|
||||
- Node.js 18+
|
||||
- React 18+
|
||||
|
||||
## Установка
|
||||
|
||||
1. Установить пакет:
|
||||
@@ -29,7 +23,7 @@ keywords: [svg-sprites, установка, настройка, config, паке
|
||||
mkdir -p src/shared/sprites/icons
|
||||
```
|
||||
|
||||
Источники спрайтов живут в `src/shared/sprites/<group>/` — это слой `shared` SLM-архитектуры (см. [Структура проекта](/docs/usage/project-structure), [Архитектура](/docs/basics/architecture/)). В `src/` посторонних каталогов вне слоёв не заводим.
|
||||
Источники спрайтов живут в `src/shared/sprites/<group>/` — это слой `shared` SLM-архитектуры (см. [Структура проекта](/docs/applied/project-structure), [Архитектура](/docs/basics/architecture/)). В `src/` посторонних каталогов вне слоёв не заводим.
|
||||
|
||||
4. Добавить скрипты в `package.json`:
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
---
|
||||
title: SVG-спрайты
|
||||
title: Использование SVG-спрайтов
|
||||
description: Как добавлять и использовать SVG-иконки в коде.
|
||||
keywords: [svg, спрайт, sprite, иконка, icon, SvgSprite, превью, preview, цвет, color]
|
||||
---
|
||||
|
||||
# SVG-спрайты
|
||||
# Использование SVG-спрайтов
|
||||
|
||||
Как добавлять и использовать SVG-иконки в коде.
|
||||
|
||||
91
docs/docs/applied/templates/templates-create.md
Normal file
91
docs/docs/applied/templates/templates-create.md
Normal file
@@ -0,0 +1,91 @@
|
||||
---
|
||||
title: Создание шаблонов генерации
|
||||
description: "Структура шаблонов, синтаксис переменных и примеры."
|
||||
keywords: [шаблоны, templates, .templates, syntax, переменные, kebabCase, pascalCase, scaffold]
|
||||
---
|
||||
|
||||
<!-- @formatter:off -->
|
||||
::: v-pre
|
||||
|
||||
# Создание шаблонов генерации
|
||||
|
||||
Структура шаблонов, синтаксис переменных и примеры.
|
||||
|
||||
## Структура шаблонов
|
||||
|
||||
Все шаблоны лежат в `.templates/` в корне проекта. Каждая папка — отдельный шаблон.
|
||||
|
||||
```text
|
||||
.templates/
|
||||
├── component/ # шаблон компонента
|
||||
│ └── {{name.kebabCase}}/
|
||||
│ ├── styles/
|
||||
│ │ └── {{name.kebabCase}}.module.css
|
||||
│ ├── types/
|
||||
│ │ └── {{name.kebabCase}}.type.ts
|
||||
│ ├── {{name.kebabCase}}.tsx
|
||||
│ └── index.ts
|
||||
└── store/ # шаблон Zustand стора
|
||||
└── {{name.kebabCase}}/
|
||||
├── {{name.kebabCase}}.store.ts
|
||||
├── {{name.kebabCase}}.type.ts
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
## Синтаксис шаблонов
|
||||
|
||||
### Переменные
|
||||
|
||||
Переменные работают в именах файлов/папок и внутри файлов:
|
||||
|
||||
```text
|
||||
{{variable}}
|
||||
```
|
||||
|
||||
Переменные могут быть любыми. `name` — дефолтная, подставляется генератором автоматически. Если реализация требует дополнительных параметров — можно использовать произвольные наборы переменных.
|
||||
|
||||
### Модификаторы
|
||||
|
||||
Модификаторы меняют регистр и формат записи переменной:
|
||||
|
||||
```text
|
||||
{{name.pascalCase}} → MyButton
|
||||
{{name.camelCase}} → myButton
|
||||
{{name.kebabCase}} → my-button
|
||||
{{name.snakeCase}} → my_button
|
||||
{{name.screamingSnakeCase}} → MY_BUTTON
|
||||
```
|
||||
|
||||
## Как создать новый шаблон
|
||||
|
||||
1. Создать папку в `.templates/` с именем шаблона (например `hook`).
|
||||
2. Внутри разместить файлы и папки, используя `{{name}}` и модификаторы в именах и содержимом.
|
||||
3. Шаблон сразу доступен и в расширении VS Code, и в CLI.
|
||||
|
||||
Пример — создание шаблона для хука:
|
||||
|
||||
```text
|
||||
.templates/
|
||||
└── hook/
|
||||
└── {{name.kebabCase}}/
|
||||
├── {{name.kebabCase}}.hook.ts
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
```ts
|
||||
// .templates/hook/{{name.kebabCase}}.hook.ts
|
||||
export const {{name.camelCase}} = () => {
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
// .templates/hook/index.ts
|
||||
export { {{name.camelCase}} } from './{{name.kebabCase}}.hook'
|
||||
```
|
||||
|
||||
## Дальше
|
||||
|
||||
- [Использование](/docs/applied/templates/templates-usage) — генерация через VS Code плагин и CLI.
|
||||
|
||||
:::
|
||||
32
docs/docs/applied/templates/templates-intro.md
Normal file
32
docs/docs/applied/templates/templates-intro.md
Normal file
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: Шаблоны генерации
|
||||
description: "Что такое шаблоны кодогенерации и какие проблемы они решают."
|
||||
---
|
||||
|
||||
# Шаблоны генерации
|
||||
|
||||
Что такое шаблоны кодогенерации и какие проблемы они решают.
|
||||
|
||||
## Проблема
|
||||
|
||||
Каждый новый модуль в проекте — компонент, стор, бизнес-модуль — требует однотипной структуры файлов и boilerplate-кода. Ручное создание приводит к трём проблемам:
|
||||
|
||||
- **Расхождения.** Разные разработчики создают модули по-разному: забывают `index.ts`, называют типы не по канону, пропускают стили.
|
||||
- **Время.** Создание одного компонента с типами, стилями и экспортом — 5–10 минут рутины. За спринт набегают часы.
|
||||
- **Ошибки копипасты.** Копирование существующего модуля и переименование — источник опечаток и забытых ссылок.
|
||||
|
||||
## Решение
|
||||
|
||||
Шаблоны кодогенерации — это папки с файлами-заготовками в `.templates/`. Вместо ручного создания файлов разработчик вызывает генератор, указывает имя — и получает готовый модуль со всей структурой, именами и boilerplate, подставленными автоматически.
|
||||
|
||||
Что дают шаблоны:
|
||||
|
||||
- **Единообразие.** Все модули одного типа идентичны по структуре. Канон живёт в шаблоне, а не в памяти разработчика.
|
||||
- **Скорость.** Генерация модуля — одна команда. Остальное время — на бизнес-логику.
|
||||
- **Согласованность с архитектурой.** Шаблоны учитывают SLM: правильные слои, сегменты, экспорты. Отклонение от стайлгайда требует осознанного усилия, а не случайного упущения.
|
||||
|
||||
## Состав раздела
|
||||
|
||||
- [Настройка](/docs/applied/templates/templates-setup) — первичная установка: скачивание стандартного набора шаблонов в проект.
|
||||
- [Создание шаблонов](/docs/applied/templates/templates-create) — структура файлов, синтаксис переменных, примеры.
|
||||
- [Использование](/docs/applied/templates/templates-usage) — генерация через VS Code плагин и CLI.
|
||||
44
docs/docs/applied/templates/templates-setup.md
Normal file
44
docs/docs/applied/templates/templates-setup.md
Normal file
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: Настройка шаблонов генерации
|
||||
description: Первичная установка шаблонов кодогенерации в проект.
|
||||
keywords: [шаблоны, templates, .templates, tiged, generator, генератор шаблонов, скачать шаблоны, scaffold]
|
||||
---
|
||||
|
||||
# Настройка шаблонов генерации
|
||||
|
||||
Первичная установка шаблонов кодогенерации в проект.
|
||||
|
||||
## Установка
|
||||
|
||||
1. Проверить, что `.templates/` отсутствует (или согласовать перезапись, если папка уже есть).
|
||||
|
||||
2. Скачать папку из эталонного репозитория:
|
||||
|
||||
```bash
|
||||
npx tiged git@gromlab.ru:templates/nextjs-template.git/.templates .templates
|
||||
```
|
||||
|
||||
3. Если `tiged` падает в default-режиме (HTTP-tarball у Gitea) — повторить с явным git-режимом:
|
||||
|
||||
```bash
|
||||
npx tiged --mode=git git@gromlab.ru:templates/nextjs-template.git/.templates .templates
|
||||
```
|
||||
|
||||
4. Проверить генерацию:
|
||||
|
||||
```bash
|
||||
npx @gromlab/create component test src/ui
|
||||
```
|
||||
|
||||
После проверки — удалить тестовый модуль.
|
||||
|
||||
## Проверка установки
|
||||
|
||||
- В корне проекта есть папка `.templates/`.
|
||||
- Внутри `.templates/` присутствуют стандартные шаблоны (или согласованный кастомный набор).
|
||||
- Пробная генерация через `npx @gromlab/create ...` отрабатывает без ошибок.
|
||||
|
||||
## Дальше
|
||||
|
||||
- [Создание шаблонов](/docs/applied/templates/templates-create) — структура файлов, синтаксис переменных, примеры.
|
||||
- [Использование](/docs/applied/templates/templates-usage) — генерация через VS Code плагин и CLI.
|
||||
39
docs/docs/applied/templates/templates-usage.md
Normal file
39
docs/docs/applied/templates/templates-usage.md
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: Использование шаблонов генерации
|
||||
description: Генерация файлов из шаблонов через VS Code плагин и CLI.
|
||||
keywords: [шаблоны, templates, generate, VS Code, CLI, gromlab/create, npx, scaffold]
|
||||
---
|
||||
|
||||
# Использование шаблонов генерации
|
||||
|
||||
Генерация файлов из шаблонов через VS Code плагин и CLI.
|
||||
|
||||
## Через VS Code
|
||||
|
||||
Template File Generator | gromlab ([Marketplace](https://marketplace.visualstudio.com/items?itemName=gromlab.vscode-templateFileGenerator), [Open VSX](https://open-vsx.org/extension/gromlab/vscode-templateFileGenerator)) — расширение для генерации файлов и папок из шаблонов через интерфейс редактора.
|
||||
|
||||
1. ПКМ на целевой папке в проводнике VS Code.
|
||||
2. **Generate from template** → выбрать шаблон.
|
||||
3. Ввести имя (например `button`) — расширение подставит его во все переменные `{{name}}`.
|
||||
|
||||
Расширение устанавливается разово на машину разработчика, не через проект.
|
||||
|
||||
## Через CLI
|
||||
|
||||
[@gromlab/create](https://www.npmjs.com/package/@gromlab/create) — CLI для генерации из тех же шаблонов. Используется через npx, глобальная установка не требуется.
|
||||
|
||||
```bash
|
||||
npx @gromlab/create <шаблон> <имя> [путь]
|
||||
```
|
||||
|
||||
Путь не обязателен — по умолчанию генерация происходит в текущую директорию.
|
||||
|
||||
| Команда | Что создаёт |
|
||||
|---|---|
|
||||
| `npx @gromlab/create component button` | Компонент в текущей папке |
|
||||
| `npx @gromlab/create module auth src/business` | Бизнес-модуль |
|
||||
| `npx @gromlab/create widget header src/widgets` | Виджет |
|
||||
| `npx @gromlab/create layout admin src/layouts` | Layout |
|
||||
| `npx @gromlab/create store auth src/business/auth/stores` | Стор |
|
||||
|
||||
CLI вызывается через `npx`, в `package.json` отдельно не добавляется.
|
||||
@@ -13,19 +13,19 @@ keywords: [создать проект, новый проект, с нуля, in
|
||||
| Компонент | Роль | Раздел |
|
||||
|-----------|------|--------|
|
||||
| Next.js | Фреймворк (роутинг, сборка, SSR) | [Next.js](/docs/creating-project/nextjs) |
|
||||
| Алиасы | Импорты по слоям SLM | [Алиасы](/docs/setup/aliases) |
|
||||
| Biome | Линтер и форматтер (замена ESLint + Prettier) | [Biome](/docs/setup/biome) |
|
||||
| Стили | Глобальные токены и breakpoints | [Стили](/docs/setup/styles) |
|
||||
| PostCSS | CSS-процессор для custom-media и вложенности | [PostCSS](/docs/setup/postcss) |
|
||||
| SVG-спрайты | Иконки через `<SvgSprite/>`, управление цветом | [SVG-спрайты](/docs/setup/svg-sprites) |
|
||||
| VS Code | Настройки редактора и расширения | [VS Code](/docs/setup/vscode) |
|
||||
| Шаблоны генерации | `.templates/` для `@gromlab/create` | [Шаблоны генерации](/docs/setup/templates) |
|
||||
| Алиасы | Импорты по слоям SLM | [Алиасы](/docs/applied/aliases) |
|
||||
| Biome | Линтер и форматтер (замена ESLint + Prettier) | [Biome](/docs/applied/biome) |
|
||||
| Стили | Глобальные токены и breakpoints | [Стили](/docs/applied/styles/styles-setup) |
|
||||
| PostCSS | CSS-процессор для custom-media и вложенности | [PostCSS](/docs/applied/postcss) |
|
||||
| SVG-спрайты | Иконки через `<SvgSprite/>`, управление цветом | [SVG-спрайты](/docs/applied/svg-sprites/svg-sprites-setup) |
|
||||
| VS Code | Настройки редактора и расширения | [VS Code](/docs/applied/vscode) |
|
||||
| Шаблоны генерации | `.templates/` для `@gromlab/create` | [Шаблоны генерации](/docs/applied/templates/templates-setup) |
|
||||
|
||||
Убрать компонент из состава — значит согласованно отказаться от части стайлгайда. Частичные проекты возможны (только Next.js, Next.js + стили и т.п.), но не являются эталоном.
|
||||
|
||||
## Канон раскладки
|
||||
|
||||
В `src/` допустимы только слои SLM: `app/`, `layouts/`, `screens/`, `widgets/`, `business/`, `infrastructure/`, `ui/`, `shared/`. Любая другая папка в `src/` — нарушение канона ([Структура проекта](/docs/usage/project-structure), [Архитектура](/docs/basics/architecture/)).
|
||||
В `src/` допустимы только слои SLM: `app/`, `layouts/`, `screens/`, `widgets/`, `business/`, `infrastructure/`, `ui/`, `shared/`. Любая другая папка в `src/` — нарушение канона ([Структура проекта](/docs/applied/project-structure), [Архитектура](/docs/basics/architecture/)).
|
||||
|
||||
В частности: `src/app/` содержит только файлы роутинга Next.js и инициализации, без каталогов `styles/`, `assets/`, `components/`.
|
||||
|
||||
@@ -43,43 +43,43 @@ keywords: [создать проект, новый проект, с нуля, in
|
||||
|
||||
Заменить дефолтный `"@/*"` в `tsconfig.json` на канонический список из восьми слой-префиксов.
|
||||
|
||||
См. [Алиасы](/docs/setup/aliases).
|
||||
См. [Алиасы](/docs/applied/aliases).
|
||||
|
||||
### 3. Biome
|
||||
|
||||
Линтер и форматтер. Подключается **до** написания кода, иначе в проекте копятся несогласованные правки.
|
||||
|
||||
См. [Biome](/docs/setup/biome).
|
||||
См. [Biome](/docs/applied/biome).
|
||||
|
||||
### 4. Стили (базовая инфраструктура)
|
||||
|
||||
Файлы `variables.css`, `media.css`, `global.css` в `src/shared/styles/` и подключение `global.css` в `src/app/layout.tsx`. CSS-процессор на этом шаге не ставится.
|
||||
|
||||
См. [Стили](/docs/setup/styles).
|
||||
См. [Стили](/docs/applied/styles/styles-setup).
|
||||
|
||||
### 5. PostCSS
|
||||
|
||||
CSS-процессор поверх базовых стилей: `@custom-media`, вложенность, autoprefixer. Ставится **только после шага 4** — опирается на `src/shared/styles/media.css`.
|
||||
|
||||
См. [PostCSS](/docs/setup/postcss).
|
||||
См. [PostCSS](/docs/applied/postcss).
|
||||
|
||||
### 6. SVG-спрайты
|
||||
|
||||
Пакет `@gromlab/svg-sprites`, генерация спрайт-файла и React-компонента `<SvgSprite/>`.
|
||||
|
||||
См. [SVG-спрайты](/docs/setup/svg-sprites).
|
||||
См. [SVG-спрайты](/docs/applied/svg-sprites/svg-sprites-setup).
|
||||
|
||||
### 7. VS Code
|
||||
|
||||
Расширения и настройки редактора. Опирается на установленный Biome (форматирование при сохранении) и PostCSS (ассоциация `*.css`).
|
||||
|
||||
См. [VS Code](/docs/setup/vscode).
|
||||
См. [VS Code](/docs/applied/vscode).
|
||||
|
||||
### 8. Шаблоны генерации
|
||||
|
||||
Папка `.templates/` для генератора модулей `@gromlab/create`.
|
||||
|
||||
См. [Шаблоны генерации](/docs/setup/templates).
|
||||
См. [Шаблоны генерации](/docs/applied/templates/templates-setup).
|
||||
|
||||
## Правила
|
||||
|
||||
|
||||
@@ -35,10 +35,10 @@ npx create-next-app@latest my-app \
|
||||
|------|----------|------------|
|
||||
| `--typescript` | TS включён | Стайлгайд требует TypeScript ([Типизация](/docs/basics/typing)) |
|
||||
| `--app` | App Router | Pages Router не используется |
|
||||
| `--src-dir` | Код в `src/` | Архитектура SLM требует `src/` ([Структура проекта](/docs/usage/project-structure)) |
|
||||
| `--import-alias "@/*"` | Placeholder | Требуется флагом; после установки `paths` полностью переписывается на слой-префиксы (см. [Алиасы](/docs/setup/aliases)) |
|
||||
| `--no-eslint` | ESLint не ставится | Линтер и форматтер — Biome ([Biome](/docs/setup/biome)) |
|
||||
| `--no-tailwind` | Tailwind не ставится | Стилизация — PostCSS Modules ([Стили](/docs/usage/styles)) |
|
||||
| `--src-dir` | Код в `src/` | Архитектура SLM требует `src/` ([Структура проекта](/docs/applied/project-structure)) |
|
||||
| `--import-alias "@/*"` | Placeholder | Требуется флагом; после установки `paths` полностью переписывается на слой-префиксы (см. [Алиасы](/docs/applied/aliases)) |
|
||||
| `--no-eslint` | ESLint не ставится | Линтер и форматтер — Biome ([Biome](/docs/applied/biome)) |
|
||||
| `--no-tailwind` | Tailwind не ставится | Стилизация — PostCSS Modules ([Стили](/docs/applied/styles/styles-usage)) |
|
||||
| `--use-npm` | Пакетный менеджер — npm | Единый инструмент в проектах |
|
||||
|
||||
### 2. Очистить дефолтный шаблон
|
||||
@@ -83,7 +83,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
|
||||
|
||||
### 3. Создать папку `src/shared/styles/`
|
||||
|
||||
Глобальные стили в SLM-архитектуре живут в слое `shared`, а не в `src/app/` ([Структура проекта](/docs/usage/project-structure)).
|
||||
Глобальные стили в SLM-архитектуре живут в слое `shared`, а не в `src/app/` ([Структура проекта](/docs/applied/project-structure)).
|
||||
|
||||
```bash
|
||||
mkdir -p src/shared/styles
|
||||
@@ -95,7 +95,7 @@ mkdir -p src/shared/styles
|
||||
|
||||
- **Конфликт с непустой директорией** — не удалять файлы пользователя автоматически. Ставить в подпапку или временно перенести посторонние файлы.
|
||||
- **Отклонение от канонических флагов** (pnpm, Tailwind, ESLint и т.п.) — только осознанное, с пониманием, что стайлгайд этого не предусматривает.
|
||||
- **Слои `src/`** не создавать авансом — появляются при первом модуле. Алиасы прописываются сразу на все восемь слоёв (см. [Алиасы](/docs/setup/aliases)).
|
||||
- **Слои `src/`** не создавать авансом — появляются при первом модуле. Алиасы прописываются сразу на все восемь слоёв (см. [Алиасы](/docs/applied/aliases)).
|
||||
- **`AGENTS.md` от Next.js** удаляется в шаге 2. Повторно не создаётся.
|
||||
- **Biome, стили, PostCSS, SVG-спрайты, VS Code** — отдельные шаги установки, не в этом разделе.
|
||||
|
||||
|
||||
@@ -22,17 +22,17 @@ keywords: [данные, api, rest, realtime, клиент, swr, infrastructure,
|
||||
Канал «запрос-ответ» по HTTP. Покрывает большинство API.
|
||||
|
||||
- **Клиенты** — как создаётся клиент REST API:
|
||||
- [Автоматическая генерация](/docs/usage/data/rest/clients/auto) — для API с OpenAPI-спецификацией, через `@gromlab/api-codegen`.
|
||||
- [Ручное создание](/docs/usage/data/rest/clients/manual) — для API без схемы, клиент пишется и поддерживается руками.
|
||||
- [Автоматическая генерация](/docs/data/rest/clients/auto) — для API с OpenAPI-спецификацией, через `@gromlab/api-codegen`.
|
||||
- [Ручное создание](/docs/data/rest/clients/manual) — для API без схемы, клиент пишется и поддерживается руками.
|
||||
- **Получение данных** — как клиент используется в приложении:
|
||||
- [Серверные компоненты](/docs/usage/data/rest/fetching/server) — прямой `await` метода клиента в Server Components.
|
||||
- [Клиентские компоненты](/docs/usage/data/rest/fetching/client) — через готовые хуки модуля API; SWR с кешем, дедупликацией и ревалидацией скрыт внутри хука.
|
||||
- [Серверные компоненты](/docs/data/rest/fetching/server) — прямой `await` метода клиента в Server Components.
|
||||
- [Клиентские компоненты](/docs/data/rest/fetching/client) — через готовые хуки модуля API; SWR с кешем, дедупликацией и ревалидацией скрыт внутри хука.
|
||||
|
||||
### Realtime
|
||||
|
||||
Канал push-данных: WebSocket, SSE, событийные шины. Транспорт не зашит в правила — важна абстракция «подписка».
|
||||
|
||||
- [Realtime](/docs/usage/data/realtime) — клиент realtime в `infrastructure/`, потребление через `useSWRSubscription` или прямые подписки.
|
||||
- [Realtime](/docs/data/realtime) — клиент realtime в `infrastructure/`, потребление через `useSWRSubscription` или прямые подписки.
|
||||
|
||||
## Что даёт раздел
|
||||
|
||||
@@ -46,6 +46,6 @@ keywords: [данные, api, rest, realtime, клиент, swr, infrastructure,
|
||||
|
||||
## Что не входит в раздел
|
||||
|
||||
- **Глобальное состояние UI** — Stores, формы, фичефлаги. Это [Stores](/docs/usage/stores).
|
||||
- **Глобальное состояние UI** — Stores, формы, фичефлаги. Это [Stores](/docs/applied/stores).
|
||||
- **Доменная логика** — как данные превращаются в сценарии бизнеса. Это слой `business/` в [Архитектуре](/docs/basics/architecture/).
|
||||
- **Хуки общего назначения** — переиспользуемые хуки UI, не привязанные к конкретному API. Это [Хуки](/docs/usage/hooks).
|
||||
- **Хуки общего назначения** — переиспользуемые хуки UI, не привязанные к конкретному API. Это [Хуки](/docs/applied/hooks).
|
||||
@@ -114,7 +114,7 @@ export function PostView({ slug, initialPost }: Props) {
|
||||
|
||||
## Начальное состояние с сервера
|
||||
|
||||
Если данные пришли из серверного компонента (см. [Серверные компоненты](/docs/usage/data/rest/fetching/server)) — передаются в `fallbackData` через `config` хука:
|
||||
Если данные пришли из серверного компонента (см. [Серверные компоненты](/docs/data/rest/fetching/server)) — передаются в `fallbackData` через `config` хука:
|
||||
|
||||
```tsx
|
||||
// page.tsx (server)
|
||||
@@ -48,7 +48,7 @@ export default async function DashboardPage() {
|
||||
|
||||
## Передача данных в клиентский компонент
|
||||
|
||||
Серверный компонент получает данные и передаёт их пропсами в клиентский. На клиенте данные становятся начальным состоянием — при необходимости перезапрашиваются через SWR (см. [Клиентские компоненты](/docs/usage/data/rest/fetching/client)).
|
||||
Серверный компонент получает данные и передаёт их пропсами в клиентский. На клиенте данные становятся начальным состоянием — при необходимости перезапрашиваются через SWR (см. [Клиентские компоненты](/docs/data/rest/fetching/client)).
|
||||
|
||||
```tsx
|
||||
// page.tsx (server)
|
||||
@@ -1,105 +0,0 @@
|
||||
---
|
||||
title: Шаблоны генерации
|
||||
description: Подключение шаблонов кодогенерации в новом проекте.
|
||||
keywords: [шаблоны, templates, .templates, tiged, generator, генератор шаблонов, добавить шаблон, скачать шаблоны, scaffold]
|
||||
---
|
||||
|
||||
# Шаблоны генерации
|
||||
|
||||
Подключение шаблонов кодогенерации в новом проекте.
|
||||
|
||||
## Требования
|
||||
|
||||
- Доступен `npx` (ставится вместе с npm).
|
||||
- Доступ к `gromlab.ru` (SSH-ключ добавлен) — для скачивания эталонного набора.
|
||||
|
||||
## Развилка
|
||||
|
||||
Сценарий зависит от состояния проекта:
|
||||
|
||||
| Состояние | Что делать |
|
||||
|-----------|------------|
|
||||
| В корне проекта **нет** `.templates/` | [Скачать стандартный набор](#скачать-стандартный-набор) |
|
||||
| `.templates/` **есть**, нужен новый специфический шаблон | [Создать шаблон вручную](#создать-шаблон-вручную) |
|
||||
| `.templates/` **есть**, нужно обновить до эталона | Скачать заново с подтверждением перезаписи |
|
||||
|
||||
## Скачать стандартный набор
|
||||
|
||||
### Установка
|
||||
|
||||
1. Проверить, что `.templates/` отсутствует (или согласовать перезапись, если папка уже есть).
|
||||
|
||||
2. Скачать папку из эталонного репозитория:
|
||||
|
||||
```bash
|
||||
npx tiged git@gromlab.ru:templates/nextjs-template.git/.templates .templates
|
||||
```
|
||||
|
||||
3. Если `tiged` падает в default-режиме (HTTP-tarball у Gitea) — повторить с явным git-режимом:
|
||||
|
||||
```bash
|
||||
npx tiged --mode=git git@gromlab.ru:templates/nextjs-template.git/.templates .templates
|
||||
```
|
||||
|
||||
4. Проверить генерацию:
|
||||
|
||||
```bash
|
||||
npx @gromlab/create component test-widget src/ui
|
||||
```
|
||||
|
||||
После проверки — удалить тестовый модуль.
|
||||
|
||||
### Правила
|
||||
|
||||
- **Скачанные файлы не править.** Источник истины — репозиторий `templates/nextjs-template`. Изменения стандартных шаблонов делаются в нём, не в отдельных проектах.
|
||||
- **Расположение — только `.templates/` в корне проекта.** Это требование расширения VS Code и CLI ([Шаблоны и генерация кода](/docs/usage/templates-generation)).
|
||||
- **Если доступа к `gromlab.ru` нет** — не восстанавливать содержимое из памяти: разойдётся с каноном. Запросить шаблоны иным путём.
|
||||
|
||||
## Создать шаблон вручную
|
||||
|
||||
Если стандартного набора недостаточно и нужен специфический шаблон под проект.
|
||||
|
||||
### Установка
|
||||
|
||||
1. Прочитать [Шаблоны и генерация кода](/docs/usage/templates-generation) — секции «Структура шаблонов», «Синтаксис шаблонов», «Как создать новый шаблон».
|
||||
|
||||
2. Определить:
|
||||
- имя шаблона (папка внутри `.templates/`);
|
||||
- состав файлов;
|
||||
- слой SLM предполагаемых потребителей ([Архитектура: слои](/docs/basics/architecture/reference/layers));
|
||||
- минимальное содержимое каждого файла.
|
||||
|
||||
3. Проверить, что имя шаблона не конфликтует с существующей папкой в `.templates/`.
|
||||
|
||||
4. Создать структуру `.templates/{name}/` по канону из [Шаблоны и генерация кода](/docs/usage/templates-generation) — синтаксис переменных, правила именования файлов и содержимого.
|
||||
|
||||
5. Проверить генерацию:
|
||||
|
||||
```bash
|
||||
npx @gromlab/create {name} test-entity {целевой путь}
|
||||
```
|
||||
|
||||
После проверки — удалить тестовый артефакт.
|
||||
|
||||
### Правила
|
||||
|
||||
- **Если запрос покрыт стандартными шаблонами** (`component`, `widget`, `store`, `layout`, `screen`, `business`) — не создавать копию.
|
||||
- **Стандартные шаблоны не трогать.** Правка стандарта — задача репозитория `templates/nextjs-template`, не отдельного проекта.
|
||||
- **Синтаксис переменных, правила регистра, минимальный boilerplate** — в [Шаблоны и генерация кода](/docs/usage/templates-generation). Здесь не дублируется.
|
||||
|
||||
## Общие правила
|
||||
|
||||
- VS Code-расширение `gromlab.vscode-templateFileGenerator` устанавливается разово на машину разработчика, а не через этот раздел ([Шаблоны и генерация кода](/docs/usage/templates-generation)).
|
||||
- CLI `@gromlab/create` вызывается через `npx`, в `package.json` отдельно не добавляется.
|
||||
- Менеджер пакетов (npm/pnpm/yarn/bun) не влияет: `tiged` и `@gromlab/create` запускаются через `npx`.
|
||||
|
||||
## Проверка установки
|
||||
|
||||
- В корне проекта есть папка `.templates/`.
|
||||
- Внутри `.templates/` присутствуют стандартные шаблоны (или согласованный кастомный набор).
|
||||
- В корне проекта нет каталогов `.git/` и `.github/` из репозитория-шаблона.
|
||||
- Пробная генерация через `npx @gromlab/create ...` отрабатывает без ошибок.
|
||||
|
||||
## Дальше
|
||||
|
||||
- [Шаблоны и генерация кода](/docs/usage/templates-generation) — синтаксис, использование, создание новых шаблонов.
|
||||
@@ -1,156 +0,0 @@
|
||||
---
|
||||
title: Шаблоны и генерация кода
|
||||
description: Как устроены шаблоны кодогенерации и как ими пользоваться.
|
||||
---
|
||||
|
||||
<!-- @formatter:off -->
|
||||
::: v-pre
|
||||
|
||||
# Шаблоны и генерация кода
|
||||
|
||||
Как устроены шаблоны кодогенерации и как ими пользоваться.
|
||||
|
||||
## Структура шаблонов
|
||||
|
||||
Все шаблоны лежат в `.templates/` в корне проекта. Каждая папка — отдельный шаблон.
|
||||
|
||||
```text
|
||||
.templates/
|
||||
├── component/ # шаблон компонента
|
||||
│ └── {{name.kebabCase}}/
|
||||
│ ├── styles/
|
||||
│ │ └── {{name.kebabCase}}.module.css
|
||||
│ ├── types/
|
||||
│ │ └── {{name.kebabCase}}.type.ts
|
||||
│ ├── {{name.kebabCase}}.tsx
|
||||
│ └── index.ts
|
||||
└── store/ # шаблон Zustand стора
|
||||
└── {{name.kebabCase}}/
|
||||
├── {{name.kebabCase}}.store.ts
|
||||
├── {{name.kebabCase}}.type.ts
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
## Синтаксис шаблонов
|
||||
|
||||
Переменные работают в именах файлов/папок и внутри файлов. Базовая переменная — `name`.
|
||||
|
||||
```text
|
||||
{{variable}}
|
||||
```
|
||||
|
||||
Модификаторы меняют регистр и формат записи:
|
||||
|
||||
```text
|
||||
{{name.pascalCase}} → MyButton
|
||||
{{name.camelCase}} → myButton
|
||||
{{name.kebabCase}} → my-button
|
||||
{{name.snakeCase}} → my_button
|
||||
{{name.screamingSnakeCase}} → MY_BUTTON
|
||||
```
|
||||
|
||||
## Как создать новый шаблон
|
||||
|
||||
1. Создать папку в `.templates/` с именем шаблона (например `hook`).
|
||||
2. Внутри разместить файлы и папки, используя `{{name}}` и модификаторы в именах и содержимом.
|
||||
3. Шаблон сразу доступен и в расширении VS Code, и в CLI.
|
||||
|
||||
Пример — создание шаблона для хука:
|
||||
|
||||
```text
|
||||
.templates/
|
||||
└── hook/
|
||||
└── {{name.kebabCase}}/
|
||||
├── {{name.kebabCase}}.hook.ts
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
```ts
|
||||
// .templates/hook/{{name.kebabCase}}.hook.ts
|
||||
export const {{name.camelCase}} = () => {
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
// .templates/hook/index.ts
|
||||
export { {{name.camelCase}} } from './{{name.kebabCase}}.hook'
|
||||
```
|
||||
|
||||
## Примеры шаблонов
|
||||
|
||||
### Шаблон компонента
|
||||
|
||||
```ts
|
||||
// .templates/component/index.ts
|
||||
export { {{name.pascalCase}} } from './{{name.kebabCase}}'
|
||||
```
|
||||
|
||||
```ts
|
||||
// .templates/component/types/{{name.kebabCase}}.type.ts
|
||||
import type { HTMLAttributes } from 'react'
|
||||
|
||||
/**
|
||||
* Параметры {{name.pascalCase}}.
|
||||
*/
|
||||
export type {{name.pascalCase}}Params = {}
|
||||
|
||||
/** HTML-атрибуты корневого элемента. */
|
||||
type RootAttrs = HTMLAttributes<HTMLDivElement>
|
||||
|
||||
export type {{name.pascalCase}}Props = RootAttrs & {{name.pascalCase}}Params
|
||||
```
|
||||
|
||||
```tsx
|
||||
// .templates/component/{{name.kebabCase}}.tsx
|
||||
import cl from 'clsx'
|
||||
import type { {{name.pascalCase}}Props } from './types/{{name.kebabCase}}.type'
|
||||
import styles from './styles/{{name.kebabCase}}.module.css'
|
||||
|
||||
/**
|
||||
* {{name.pascalCase}}.
|
||||
*/
|
||||
export const {{name.pascalCase}} = (props: {{name.pascalCase}}Props) => {
|
||||
const { children, className, ...htmlAttr } = props
|
||||
|
||||
return (
|
||||
<div {...htmlAttr} className={cl(styles.root, className)}>
|
||||
{children}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```css
|
||||
/* .templates/component/styles/{{name.kebabCase}}.module.css */
|
||||
.root {
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
## Генерация через VS Code
|
||||
|
||||
Template File Generator | gromlab ([Marketplace](https://marketplace.visualstudio.com/items?itemName=gromlab.vscode-templateFileGenerator), [Open VSX](https://open-vsx.org/extension/gromlab/vscode-templateFileGenerator)) — расширение для генерации файлов и папок из шаблонов через интерфейс редактора.
|
||||
|
||||
1. ПКМ на целевой папке в проводнике VS Code.
|
||||
2. **Generate from template** → выбрать шаблон.
|
||||
3. Ввести имя (например `button`) — расширение подставит его во все переменные `{{name}}`.
|
||||
|
||||
## Генерация через CLI
|
||||
|
||||
[@gromlab/create](https://www.npmjs.com/package/@gromlab/create) — CLI для генерации из тех же шаблонов. Используется через npx, глобальная установка не требуется.
|
||||
|
||||
```bash
|
||||
npx @gromlab/create <шаблон> <имя> <путь>
|
||||
```
|
||||
|
||||
| Команда | Что создаёт |
|
||||
|---|---|
|
||||
| `npx @gromlab/create component button src/shared/ui` | Компонент |
|
||||
| `npx @gromlab/create module auth src/business` | Бизнес-модуль |
|
||||
| `npx @gromlab/create widget header src/widgets` | Виджет |
|
||||
| `npx @gromlab/create layout admin src/layouts` | Layout |
|
||||
| `npx @gromlab/create store auth src/business/auth/stores` | Стор |
|
||||
|
||||
:::
|
||||
|
||||
Reference in New Issue
Block a user