Compare commits
2 Commits
3d93efd90a
...
781efc52f1
| Author | SHA1 | Date | |
|---|---|---|---|
| 781efc52f1 | |||
| ec01ae2e1c |
@@ -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' },
|
||||
],
|
||||
},
|
||||
|
||||
111
docs/docs/setup/nextjs.md
Normal file
111
docs/docs/setup/nextjs.md
Normal file
@@ -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 <h1>Home</h1>
|
||||
}
|
||||
```
|
||||
|
||||
Очистить `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 (
|
||||
<html lang="ru">
|
||||
<body>{children}</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### 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`).
|
||||
47
docs/docs/setup/project-from-template.md
Normal file
47
docs/docs/setup/project-from-template.md
Normal file
@@ -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/` — решение о репозитории принимает разработчик.
|
||||
91
docs/docs/setup/project-manual.md
Normal file
91
docs/docs/setup/project-manual.md
Normal file
@@ -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-спрайты | Иконки через `<SvgSprite/>`, управление цветом | [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-компонента `<SvgSprite/>`.
|
||||
|
||||
См. [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 и часть инструментов; полный набор — это эталон, а не обязательство.
|
||||
178
docs/docs/setup/styles.md
Normal file
178
docs/docs/setup/styles.md
Normal file
@@ -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 (
|
||||
<html lang="ru">
|
||||
<body>{children}</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
`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) — стили иконок отдельно от глобальных.
|
||||
106
docs/docs/setup/templates.md
Normal file
106
docs/docs/setup/templates.md
Normal file
@@ -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) — синтаксис, использование, создание новых шаблонов.
|
||||
@@ -101,40 +101,41 @@ const linkToSiteUrl = (link: string): string =>
|
||||
|
||||
/**
|
||||
* Развернуть sidebar в плоский список с сохранением группы и
|
||||
* опционального префикса вложенной группы.
|
||||
* накопленного префикса вложенных групп. Поддерживает произвольную
|
||||
* глубину вложенности — префиксы подгрупп склеиваются через `: `.
|
||||
*/
|
||||
const flattenSidebar = (sidebar: SidebarItem[]): Entry[] => {
|
||||
const entries: Entry[] = [];
|
||||
|
||||
for (const top of sidebar) {
|
||||
const section = top.text;
|
||||
const walk = (
|
||||
items: SidebarItem[],
|
||||
section: string,
|
||||
prefix: string | null,
|
||||
): void => {
|
||||
for (const item of items) {
|
||||
const hasChildren = !!item.items && item.items.length > 0;
|
||||
|
||||
if (top.link && !top.items) {
|
||||
entries.push({ section, prefix: null, text: top.text, link: top.link });
|
||||
if (item.link) {
|
||||
entries.push({ section, prefix, text: item.text, link: item.link });
|
||||
}
|
||||
|
||||
if (hasChildren) {
|
||||
const nextPrefix = prefix ? `${prefix}: ${item.text}` : item.text;
|
||||
walk(item.items!, section, nextPrefix);
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
for (const top of sidebar) {
|
||||
const hasChildren = !!top.items && top.items.length > 0;
|
||||
|
||||
if (top.link && !hasChildren) {
|
||||
entries.push({ section: top.text, prefix: null, text: top.text, link: top.link });
|
||||
continue;
|
||||
}
|
||||
|
||||
if (!top.items) continue;
|
||||
|
||||
for (const item of top.items) {
|
||||
if (item.items) {
|
||||
for (const sub of item.items) {
|
||||
if (!sub.link) continue;
|
||||
entries.push({
|
||||
section,
|
||||
prefix: item.text,
|
||||
text: sub.text,
|
||||
link: sub.link,
|
||||
});
|
||||
}
|
||||
} else if (item.link) {
|
||||
entries.push({
|
||||
section,
|
||||
prefix: null,
|
||||
text: item.text,
|
||||
link: item.link,
|
||||
});
|
||||
}
|
||||
if (hasChildren) {
|
||||
walk(top.items!, top.text, null);
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user