From 781efc52f139a74d37b8ee731e68d29716c7505b Mon Sep 17 00:00:00 2001 From: "S.Gromov" Date: Mon, 27 Apr 2026 01:27:43 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20=D1=80=D0=B0=D0=B7=D0=B4=D0=B5=D0=BB=D1=8B=20?= =?UTF-8?q?=D1=83=D1=81=D1=82=D0=B0=D0=BD=D0=BE=D0=B2=D0=BA=D0=B8=20=D0=BF?= =?UTF-8?q?=D1=80=D0=BE=D0=B5=D0=BA=D1=82=D0=B0,=20Next.js,=20=D1=81=D1=82?= =?UTF-8?q?=D0=B8=D0=BB=D0=B5=D0=B9=20=D0=B8=20=D1=88=D0=B0=D0=B1=D0=BB?= =?UTF-8?q?=D0=BE=D0=BD=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Создание проекта: «Из шаблона» (clone через tiged) и «Вручную» (пошаговая сборка) — оформлены подгруппой - Next.js: `create-next-app` с каноническими флагами, очистка демо-шаблона, минимальный layout - Стили: базовая инфраструктура `variables.css` / `media.css` / `global.css` в `src/shared/styles/` без PostCSS - Шаблоны генерации: установка `.templates/` через tiged + создание шаблона вручную - Сайдбар «Установка и настройка» расширен новыми пунктами в порядке зависимости установки --- .vitepress/config.ts | 11 ++ docs/docs/setup/nextjs.md | 111 ++++++++++++++ docs/docs/setup/project-from-template.md | 47 ++++++ docs/docs/setup/project-manual.md | 91 ++++++++++++ docs/docs/setup/styles.md | 178 +++++++++++++++++++++++ docs/docs/setup/templates.md | 106 ++++++++++++++ 6 files changed, 544 insertions(+) create mode 100644 docs/docs/setup/nextjs.md create mode 100644 docs/docs/setup/project-from-template.md create mode 100644 docs/docs/setup/project-manual.md create mode 100644 docs/docs/setup/styles.md create mode 100644 docs/docs/setup/templates.md diff --git a/.vitepress/config.ts b/.vitepress/config.ts index f1d7496..61b899f 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -32,10 +32,21 @@ const sidebar = [ { text: 'Установка и настройка', items: [ + { + text: 'Создание проекта', + collapsed: true, + items: [ + { text: 'Из шаблона', link: '/docs/setup/project-from-template' }, + { text: 'Вручную', link: '/docs/setup/project-manual' }, + ], + }, + { text: 'Next.js', link: '/docs/setup/nextjs' }, { text: 'Алиасы', link: '/docs/setup/aliases' }, { text: 'Biome', link: '/docs/setup/biome' }, + { text: 'Стили', link: '/docs/setup/styles' }, { text: 'PostCSS', link: '/docs/setup/postcss' }, { text: 'SVG-спрайты', link: '/docs/setup/svg-sprites' }, + { text: 'Шаблоны генерации', link: '/docs/setup/templates' }, { text: 'VS Code', link: '/docs/setup/vscode' }, ], }, diff --git a/docs/docs/setup/nextjs.md b/docs/docs/setup/nextjs.md new file mode 100644 index 0000000..3f079a3 --- /dev/null +++ b/docs/docs/setup/nextjs.md @@ -0,0 +1,111 @@ +--- +title: Next.js +keywords: [next.js, create-next-app, npx, установка, инициализация, фреймворк, скаффолдинг, app router, typescript] +--- + +# Next.js + +Установка фреймворка через `create-next-app` и очистка дефолтного шаблона. На выходе — чистый скелет с App Router и TypeScript. + +## Требования + +- Node.js 18.18+ (рекомендуется LTS 20+). +- npm 10+. +- Рабочая папка пуста, либо для установки выбрана подпапка (`create-next-app@16+` отказывается ставиться в непустую директорию). + +## Установка + +### 1. Инициализация через `create-next-app` + +Флаги зафиксированы и не согласовываются — это канон стайлгайда: + +```bash +npx create-next-app@latest my-app \ + --typescript \ + --app \ + --src-dir \ + --import-alias "@/*" \ + --no-eslint \ + --no-tailwind \ + --use-npm +``` + +| Флаг | Значение | Почему так | +|------|----------|------------| +| `--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)) | +| `--use-npm` | Пакетный менеджер — npm | Единый инструмент в проектах | + +### 2. Очистить дефолтный шаблон + +`create-next-app` генерирует демо-страницу со стилями и ассетами, а Next.js 16+ дополнительно кладёт в корень собственные `AGENTS.md` и `CLAUDE.md` — всё это удаляется. + +```bash +rm src/app/page.module.css +rm src/app/globals.css +rm public/next.svg public/vercel.svg public/file.svg public/globe.svg public/window.svg +rm -f AGENTS.md CLAUDE.md +``` + +Заменить `src/app/page.tsx` на минимальный: + +```tsx +// src/app/page.tsx +export default function HomePage() { + return

Home

+} +``` + +Очистить `src/app/layout.tsx` от импорта шрифтов и `globals.css`: + +```tsx +// src/app/layout.tsx +import type { Metadata } from 'next' + +export const metadata: Metadata = { + title: 'App', + description: '', +} + +export default function RootLayout({ children }: { children: React.ReactNode }) { + return ( + + {children} + + ) +} +``` + +### 3. Создать папку `src/shared/styles/` + +Глобальные стили в SLM-архитектуре живут в слое `shared`, а не в `src/app/` ([Структура проекта](/docs/usage/project-structure)). + +```bash +mkdir -p src/shared/styles +``` + +Остальные слои (`layouts/`, `screens/`, `widgets/`, `business/`, `infrastructure/`, `ui/`) заводятся при появлении первого модуля в них. `src/shared/styles/` — единственный подкаталог `shared/`, который заводится сразу: без него не настроить стили на следующих шагах. + +## Правила + +- **Конфликт с непустой директорией** — не удалять файлы пользователя автоматически. Ставить в подпапку или временно перенести посторонние файлы. +- **Отклонение от канонических флагов** (pnpm, Tailwind, ESLint и т.п.) — только осознанное, с пониманием, что стайлгайд этого не предусматривает. +- **Слои `src/`** не создавать авансом — появляются при первом модуле. Алиасы прописываются сразу на все восемь слоёв (см. [Алиасы](/docs/setup/aliases)). +- **`AGENTS.md` от Next.js** удаляется в шаге 2. Повторно не создаётся. +- **Biome, стили, PostCSS, SVG-спрайты, VS Code** — отдельные шаги установки, не в этом разделе. + +## Проверка установки + +- В корне проекта: `next.config.ts`, `tsconfig.json`, `package.json`. +- В `package.json`: Next.js установлен, нет `eslint`, `tailwindcss`. +- В `src/app/` присутствуют минимальные `page.tsx` и `layout.tsx`. `globals.css`, `page.module.css` отсутствуют. Каталогов `styles/`, `assets/`, `providers/`, `components/` в `src/app/` нет. +- Папка `src/shared/styles/` создана (пустая). +- В `src/` из слоёв SLM присутствуют только `app/` и `shared/` (с `styles/`). Посторонних каталогов нет. +- В `public/` удалены `next.svg`, `vercel.svg`, `file.svg`, `globe.svg`, `window.svg`. +- В корне проекта нет `AGENTS.md` и `CLAUDE.md` от Next.js. +- `npm run build` завершается успешно. +- Пакетный менеджер — npm (нет `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`). diff --git a/docs/docs/setup/project-from-template.md b/docs/docs/setup/project-from-template.md new file mode 100644 index 0000000..7fe7180 --- /dev/null +++ b/docs/docs/setup/project-from-template.md @@ -0,0 +1,47 @@ +--- +title: Из шаблона +keywords: [создать проект из шаблона, шаблон, template, tiged, degit, клонировать шаблон, эталонный шаблон, быстрый старт, scaffold, новый проект] +--- + +# Создание проекта из шаблона + +Клонирование эталонного шаблона стайлгайда одной командой. Дефолтный сценарий создания проекта. + +В шаблоне уже настроены Next.js, Biome, стили, PostCSS, SVG-спрайты, VS Code и шаблоны генерации. Если нужен контроль над каждым шагом или шаблон недоступен — [Создание проекта вручную](/docs/setup/project-manual). + +## Требования + +- Node.js 18.18+ (рекомендуется LTS 20+). +- npm 10+. +- Доступ к `gromlab.ru` (SSH-ключ добавлен). + +## Установка + +1. Склонировать шаблон в родительском каталоге будущего проекта: + + ```bash + npx tiged git@gromlab.ru:templates/nextjs.git my-app + ``` + + `tiged` копирует снимок репозитория без истории git. Имя каталога (`my-app`) заменяется на нужное. + +2. Установить зависимости: + + ```bash + cd my-app + npm install + ``` + +3. Проверить сборку: + + ```bash + npm run build + ``` + + Сборка должна завершиться без ошибок. + +## Правила + +- **Шаблон — источник истины.** Не добавлять, не удалять и не переименовывать файлы шаблона «для приведения к канону»: шаблон уже канонический. Любое несоответствие — баг шаблона, а не проекта. +- **Менеджер пакетов — npm.** Отклонение (pnpm, yarn, bun) — только по явному решению с пониманием, что стайлгайд этого не предусматривает. +- **Не инициализировать git заново** автоматически. `tiged` намеренно не создаёт `.git/` — решение о репозитории принимает разработчик. diff --git a/docs/docs/setup/project-manual.md b/docs/docs/setup/project-manual.md new file mode 100644 index 0000000..8633100 --- /dev/null +++ b/docs/docs/setup/project-manual.md @@ -0,0 +1,91 @@ +--- +title: Вручную +keywords: [создать проект, новый проект, с нуля, init, initialize, scaffold, create-next-app, начать проект, поднять проект, эталонный проект, ручная установка] +--- + +# Создание проекта вручную + +Сборка эталонного Next.js-проекта шаг за шагом — для случаев, когда нужен контроль над каждым шагом или шаблон недоступен. + +Если шаблон доступен — быстрее использовать [Создание проекта из шаблона](/docs/setup/project-from-template). + +## Состав эталонного проекта + +| Компонент | Роль | Раздел | +|-----------|------|--------| +| Next.js | Фреймворк (роутинг, сборка, SSR) | [Next.js](/docs/setup/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-спрайты | Иконки через ``, управление цветом | [SVG-спрайты](/docs/setup/svg-sprites) | +| VS Code | Настройки редактора и расширения | [VS Code](/docs/setup/vscode) | +| Шаблоны генерации | `.templates/` для `@gromlab/create` | [Шаблоны генерации](/docs/setup/templates) | + +Убрать компонент из состава — значит согласованно отказаться от части стайлгайда. Частичные проекты возможны (только Next.js, Next.js + стили и т.п.), но не являются эталоном. + +## Канон раскладки + +В `src/` допустимы только слои SLM: `app/`, `layouts/`, `screens/`, `widgets/`, `business/`, `infrastructure/`, `ui/`, `shared/`. Любая другая папка в `src/` — нарушение канона ([Структура проекта](/docs/usage/project-structure), [Архитектура](/docs/basics/architecture/)). + +В частности: `src/app/` содержит только файлы роутинга Next.js и инициализации, без каталогов `styles/`, `assets/`, `components/`. + +## Порядок установки + +Подсистемы ставятся в фиксированном порядке — он отражает зависимости между шагами. + +### 1. Next.js + +Скелет фреймворка — обязательный первый шаг, остальное опирается на него. + +См. [Next.js](/docs/setup/nextjs). После выполнения проверки этого раздела `npm run build` должен проходить. + +### 2. Алиасы + +Заменить дефолтный `"@/*"` в `tsconfig.json` на канонический список из восьми слой-префиксов. + +См. [Алиасы](/docs/setup/aliases). + +### 3. Biome + +Линтер и форматтер. Подключается **до** написания кода, иначе в проекте копятся несогласованные правки. + +См. [Biome](/docs/setup/biome). + +### 4. Стили (базовая инфраструктура) + +Файлы `variables.css`, `media.css`, `global.css` в `src/shared/styles/` и подключение `global.css` в `src/app/layout.tsx`. CSS-процессор на этом шаге не ставится. + +См. [Стили](/docs/setup/styles). + +### 5. PostCSS + +CSS-процессор поверх базовых стилей: `@custom-media`, вложенность, autoprefixer. Ставится **только после шага 4** — опирается на `src/shared/styles/media.css`. + +См. [PostCSS](/docs/setup/postcss). + +### 6. SVG-спрайты + +Пакет `@gromlab/svg-sprites`, генерация спрайт-файла и React-компонента ``. + +См. [SVG-спрайты](/docs/setup/svg-sprites). + +### 7. VS Code + +Расширения и настройки редактора. Опирается на установленный Biome (форматирование при сохранении) и PostCSS (ассоциация `*.css`). + +См. [VS Code](/docs/setup/vscode). + +### 8. Шаблоны генерации + +Папка `.templates/` для генератора модулей `@gromlab/create`. + +См. [Шаблоны генерации](/docs/setup/templates). + +## Правила + +- **Порядок шагов фиксирован.** Перестановка ломает зависимости (PostCSS требует базовых стилей, VS Code — установленного Biome). +- **Между шагами обязательна проверка** из соответствующего раздела. Не переходить дальше, пока чеклист текущего шага не пройден. +- **Слои `src/`** (`layouts/`, `screens/`, `widgets/`, `business/`, `infrastructure/`, `ui/`) не создавать авансом. Появляются по мере первого модуля. Исключения — `src/app/` (создаётся `create-next-app`), `src/shared/styles/` (шаг 1) и `src/shared/sprites/icons/` (шаг 6). +- **Посторонние каталоги в `src/`** (`assets/`, `utils/`, `lib/`, `components/` и т.п.) — запрещены. +- **Подмножество шагов допустимо.** Можно ставить только Next.js и часть инструментов; полный набор — это эталон, а не обязательство. diff --git a/docs/docs/setup/styles.md b/docs/docs/setup/styles.md new file mode 100644 index 0000000..b70dce6 --- /dev/null +++ b/docs/docs/setup/styles.md @@ -0,0 +1,178 @@ +--- +title: Стили +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). + +## Требования + +- Структура `src/` соответствует SLM ([Структура проекта](/docs/usage/project-structure)). Глобальные стили живут в `src/shared/styles/`, не в `src/app/`. +- В проекте нет `globals.css` с кастомным содержимым и не установлен `tailwindcss`. + +## Файлы + +Состав глобальных стилей — три файла: + +| Файл | Роль | +|------|------| +| `variables.css` | Токены проекта (цвета, отступы, радиусы) | +| `media.css` | Custom media queries (брейкпоинты по ширине и высоте) | +| `global.css` | Точка сборки глобальных стилей: через `@import` тянет все остальные глобалы, импортируется в приложение один раз | + +Правила подключения: + +- В приложение импортируется **только** `global.css`. +- `variables.css` и будущие глобальные файлы (резеты, темы, типографика) подключаются в `global.css` через `@import`. +- `media.css` **не импортируется** — ни в `global.css`, ни в компоненты, ни в точку инициализации. Его читает CSS-процессор на этапе сборки (см. [PostCSS](/docs/setup/postcss)). + +## Корневой `font-size` + +Базовая единица `rem` в проекте привязана к **16px**: корневой `font-size` не переопределяется. `html { font-size: ... }` писать запрещено — пользовательская настройка размера шрифта в браузере должна работать (a11y). Все `rem`-значения в `media.css` и других стилях трактуются как `1rem = 16px по умолчанию`. + +Reset браузерных дефолтов (`box-sizing`, сброс `margin`, типографика) каноном не задаётся — каждый проект решает сам. Если заводится — подключается через `global.css`. + +## Установка + +### 1. Создать файлы + +```bash +mkdir -p src/shared/styles +touch src/shared/styles/variables.css src/shared/styles/media.css src/shared/styles/global.css +``` + +### 2. Заполнить `media.css` + +Файл `src/shared/styles/media.css`. Стандартный набор брейкпоинтов проекта; редактировать только при согласованном изменении шкалы. + +Единица — `rem` (реагирует на корневой `font-size`). Перевод исходит из дефолтного `html { font-size: 16px }`, т.е. `1rem = 16px`. + +```css +/* src/shared/styles/media.css */ + +/* Ширина — Mobile First (min-width), кроме --xs (max-width) */ +@custom-media --xs (max-width: 35.9375rem); /* 575px — до sm */ +@custom-media --sm (min-width: 36rem); /* 576px — телефон альбом / малый планшет */ +@custom-media --md (min-width: 48rem); /* 768px — планшет */ +@custom-media --lg (min-width: 62rem); /* 992px — малый десктоп */ +@custom-media --xl (min-width: 75rem); /* 1200px — десктоп */ +@custom-media --2xl (min-width: 88rem); /* 1408px — широкий десктоп */ +@custom-media --3xl (min-width: 120rem); /* 1920px — full HD+ */ + +/* Высота — min-height */ +@custom-media --h-xs (min-height: 41.6875rem); /* 667px — iPhone SE портрет */ +@custom-media --h-sm (min-height: 43.875rem); /* 702px */ +@custom-media --h-md (min-height: 50.625rem); /* 810px — iPad портрет */ +@custom-media --h-lg (min-height: 56.25rem); /* 900px */ +@custom-media --h-xl (min-height: 62.5rem); /* 1000px */ +@custom-media --h-2xl (min-height: 68.75rem); /* 1100px */ +@custom-media --h-3xl (min-height: 75rem); /* 1200px */ +``` + +Правила: + +- только `@custom-media` на верхнем уровне; +- имена короткие, по шкале (`--xs` … `--3xl`); высотные — с префиксом `--h-`; +- единица — `rem`, не `em`/`px`; пиксельное значение указывается комментарием; +- значения ширины — `min-width` (Mobile First), исключение `--xs` — `max-width` (блок «строго меньше `--sm`»); +- значения высоты — `min-height`. + +### 3. Заполнить `variables.css` + +Файл `src/shared/styles/variables.css`. Набор токенов под проект расширяется по мере роста дизайн-системы. + +```css +/* src/shared/styles/variables.css */ +:root { + /* Цвета */ + --color-primary: #3b82f6; + --color-bg: #ffffff; + --color-bg-hover: #f5f5f5; + --color-text: #1a1a1a; + + /* Отступы */ + --space-1: 4px; + --space-2: 8px; + --space-3: 12px; + --space-4: 16px; + + /* Скругления */ + --radius-1: 4px; + --radius-2: 8px; +} +``` + +Правила: + +- все токены определяются в `:root` — без вложенных селекторов; +- именование — `kebab-case` по ролям: `--color-*`, `--space-*`, `--radius-*`; +- `px` — основная единица для пространственных токенов; +- темы накладываются поверх через `[data-theme="..."] { ... }` — в отдельном файле темы или здесь же. + +`variables.css` напрямую в приложение не импортируется — только через `global.css`. + +### 4. Заполнить `global.css` + +Файл `src/shared/styles/global.css`. Единственный глобальный файл, импортируемый в точку инициализации приложения. Внутри — `@import` остальных глобалов относительным путём. + +```css +/* src/shared/styles/global.css */ +@import './variables.css'; + +/* Сюда же подключаются будущие глобалы через @import: + * @import './reset.css'; + * @import './typography.css'; + * @import './themes.css'; + * media.css НЕ импортируется — он работает через PostCSS. + */ +``` + +Правила: + +- пути в `@import` — относительные (`./variables.css`), не через алиасы; нативный CSS `@import` не понимает tsconfig-paths; +- `media.css` в `global.css` **не импортируется**; +- собственные глобальные правила (`html { ... }`, `body { ... }`) писать **не здесь**, а в отдельных файлах рядом (`reset.css`, `typography.css`) и подключать через `@import`. `global.css` — только точка сборки; +- порядок `@import` определяет порядок каскада: токены первыми, дальше резеты / темы / типографика. + +### 5. Подключить `global.css` в layout + +Импорт делается **один раз** — в корневом layout приложения: + +```tsx +// src/app/layout.tsx +import 'shared/styles/global.css' + +import type { Metadata } from 'next' + +export const metadata: Metadata = { + title: 'App', + description: '', +} + +export default function RootLayout({ children }: { children: React.ReactNode }) { + return ( + + {children} + + ) +} +``` + +`variables.css` и `media.css` в layout **не импортируются напрямую** — только через `global.css` (variables) или через PostCSS на сборке (media). + +## Проверка установки + +- В `src/shared/styles/` присутствуют три файла: `variables.css`, `media.css`, `global.css`. В `src/app/` папки `styles/` нет. +- В `src/app/layout.tsx` есть `import 'shared/styles/global.css'`. Импортов `variables.css` и `media.css` там нет. +- В проекте **не появились** PostCSS-пакеты и `postcss.config.*` — этот раздел их не ставит. +- `npm run build` завершается успешно. + +## Дальше + +- [PostCSS](/docs/setup/postcss) — подключить процессор, чтобы заработали `@media (--md)` и вложенность. +- [Стили: использование](/docs/usage/styles) — правила написания CSS в компонентах. +- [SVG-спрайты](/docs/setup/svg-sprites) — стили иконок отдельно от глобальных. diff --git a/docs/docs/setup/templates.md b/docs/docs/setup/templates.md new file mode 100644 index 0000000..7e75a1d --- /dev/null +++ b/docs/docs/setup/templates.md @@ -0,0 +1,106 @@ +--- +title: Шаблоны генерации +keywords: [шаблоны, templates, .templates, tiged, generator, генератор шаблонов, добавить шаблон, скачать шаблоны, scaffold] +--- + +# Шаблоны генерации + +Папка `.templates/` в корне проекта для генератора модулей `@gromlab/create`. + +Синтаксис шаблонов и работа генератора — [Шаблоны и генерация кода](/docs/usage/templates-generation). + +## Требования + +- Доступен `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) — синтаксис, использование, создание новых шаблонов.