Compare commits
2 Commits
f645b2ad40
...
e5e4ace91a
| Author | SHA1 | Date | |
|---|---|---|---|
| e5e4ace91a | |||
| 5a773a5b4f |
@@ -33,18 +33,34 @@ const sidebar = [
|
||||
text: 'Прикладные разделы',
|
||||
items: [
|
||||
{ text: 'Структура проекта', link: '/docs/applied/project-structure' },
|
||||
{ text: 'Алиасы', link: '/docs/applied/aliases' },
|
||||
{ text: 'Компоненты', link: '/docs/applied/components' },
|
||||
{ text: 'Страницы (App Router)', link: '/docs/applied/page-level' },
|
||||
{ text: 'Шаблоны и генерация кода', link: '/docs/applied/templates-generation' },
|
||||
{ text: 'Стили', link: '/docs/applied/styles' },
|
||||
{
|
||||
text: 'Стили',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: 'PostCSS', link: '/docs/applied/styles/postcss' },
|
||||
{ text: 'Использование', link: '/docs/applied/styles/usage' },
|
||||
],
|
||||
},
|
||||
{ text: 'Изображения', link: '/docs/applied/images-sprites' },
|
||||
{ text: 'SVG-спрайты', link: '/docs/applied/svg-sprites' },
|
||||
{
|
||||
text: 'SVG-спрайты',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: 'Установка и настройка', link: '/docs/applied/svg-sprites/setup' },
|
||||
{ text: 'Использование', link: '/docs/applied/svg-sprites/usage' },
|
||||
],
|
||||
},
|
||||
{ text: 'Видео', link: '/docs/applied/video' },
|
||||
{ text: 'API', link: '/docs/applied/api' },
|
||||
{ text: 'Stores', link: '/docs/applied/stores' },
|
||||
{ text: 'Хуки', link: '/docs/applied/hooks' },
|
||||
{ text: 'Шрифты', link: '/docs/applied/fonts' },
|
||||
{ text: 'Локализация', link: '/docs/applied/localization' },
|
||||
{ text: 'Biome', link: '/docs/applied/biome' },
|
||||
{ text: 'Настройка VS Code', link: '/docs/applied/vscode' },
|
||||
],
|
||||
},
|
||||
|
||||
@@ -6,12 +6,12 @@
|
||||
|
||||
**Для AI-агентов:**
|
||||
|
||||
- [Карта разделов](https://nextjs-style-guide.gromlab.ru/llms.txt) — `llms.txt`, оглавление со ссылками на разделы.
|
||||
- [Полный текст](https://nextjs-style-guide.gromlab.ru/llms-full.txt) — `llms-full.txt`, вся документация одним файлом.
|
||||
- [llms.txt](/llms.txt) — Карта разделов, оглавление со ссылками на разделы.
|
||||
- [llms-full.txt](/llms-full.txt) — Вся документация одним файлом.
|
||||
|
||||
**Для проекта:**
|
||||
|
||||
- [Архив с правилами](https://nextjs-style-guide.gromlab.ru/nextjs-style-guide.zip) — `nextjs-style-guide.zip`, набор Markdown-файлов для распаковки в `./ai/nextjs-style-guide/` или другую папку проекта.
|
||||
- [nextjs-style-guide.zip](/nextjs-style-guide.zip) — Набор Markdown-файлов для распаковки в `./ai/nextjs-style-guide/` или другую папку проекта.
|
||||
|
||||
## Структура документации
|
||||
|
||||
|
||||
78
docs/docs/applied/aliases.md
Normal file
78
docs/docs/applied/aliases.md
Normal file
@@ -0,0 +1,78 @@
|
||||
---
|
||||
title: Алиасы
|
||||
keywords: [алиасы, aliases, paths, tsconfig, импорты, baseUrl, app, layouts, screens, widgets, business, infrastructure, ui, shared]
|
||||
---
|
||||
|
||||
# Алиасы
|
||||
|
||||
Импорты в проекте идут через алиасы слоёв SLM-архитектуры — по одному на каждый слой `src/`. Префикс `@/` **не используется**: имя слоя само по себе однозначно адресует код.
|
||||
|
||||
Слои и направление зависимостей — [Архитектура: слои](/docs/basics/architecture/reference/layers).
|
||||
|
||||
## Конфиг
|
||||
|
||||
`tsconfig.json` в корне проекта:
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"paths": {
|
||||
"app/*": ["./src/app/*"],
|
||||
"layouts/*": ["./src/layouts/*"],
|
||||
"screens/*": ["./src/screens/*"],
|
||||
"widgets/*": ["./src/widgets/*"],
|
||||
"business/*": ["./src/business/*"],
|
||||
"infrastructure/*": ["./src/infrastructure/*"],
|
||||
"ui/*": ["./src/ui/*"],
|
||||
"shared/*": ["./src/shared/*"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Восемь алиасов — ровно по числу слоёв. Других алиасов в проекте нет.
|
||||
|
||||
## Правила
|
||||
|
||||
- **Каждый импорт между модулями — через алиас слоя.** Относительные пути (`../../`) запрещены за пределами своего модуля.
|
||||
- **Внутри одного модуля** допустимы относительные импорты (`./model`, `./ui/button`) — это часть инкапсуляции модуля.
|
||||
- **Префикс `@/` не используется.** Имя слоя — само по себе адрес.
|
||||
- **Направление импортов** определяется архитектурой, не алиасами. Алиас разрешает импорт технически, но не отменяет правила слоёв (→ [Слои](/docs/basics/architecture/reference/layers)).
|
||||
|
||||
**Хорошо**
|
||||
|
||||
```ts
|
||||
import { Button } from 'ui/button'
|
||||
import { useUser } from 'business/user'
|
||||
import { formatDate } from 'shared/utils/date'
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
|
||||
```ts
|
||||
// Относительный путь между модулями
|
||||
import { Button } from '../../../ui/button'
|
||||
|
||||
// Префикс @/, которого нет в paths
|
||||
import { Button } from '@/ui/button'
|
||||
|
||||
// Алиас на src — не предусмотрен
|
||||
import { Button } from 'src/ui/button'
|
||||
```
|
||||
|
||||
## Внутри модуля
|
||||
|
||||
Внутри своего модуля — относительные пути:
|
||||
|
||||
```ts
|
||||
// src/ui/button/button.tsx
|
||||
import styles from './button.module.css'
|
||||
import { Icon } from './icon'
|
||||
```
|
||||
|
||||
Не использовать алиас на самого себя:
|
||||
|
||||
```ts
|
||||
// Плохо — алиас вместо относительного пути внутри модуля
|
||||
import { Icon } from 'ui/button/icon'
|
||||
```
|
||||
80
docs/docs/applied/biome.md
Normal file
80
docs/docs/applied/biome.md
Normal file
@@ -0,0 +1,80 @@
|
||||
---
|
||||
title: Biome
|
||||
keywords: [biome, линтер, форматтер, lint, format, biome.json, "@biomejs/biome", замена eslint, замена prettier]
|
||||
---
|
||||
|
||||
# Biome
|
||||
|
||||
Единый линтер и форматтер для JS/TS/JSON в проекте. Заменяет связку ESLint + Prettier одним инструментом.
|
||||
|
||||
## Требования
|
||||
|
||||
- Node.js 18+.
|
||||
- Проект без установленного ESLint и Prettier (они конфликтуют с Biome).
|
||||
|
||||
## Установка
|
||||
|
||||
1. Установить пакет:
|
||||
|
||||
```bash
|
||||
npm install --save-dev --save-exact @biomejs/biome
|
||||
```
|
||||
|
||||
2. Инициализировать конфиг:
|
||||
|
||||
```bash
|
||||
npx @biomejs/biome init
|
||||
```
|
||||
|
||||
В корне появится `biome.json` с дефолтными настройками.
|
||||
|
||||
3. Привести `biome.json` к стандартному виду — добавить override для `*.css` (см. «Стандартный `biome.json`»). Делается сразу после `init`, до первого запуска `lint`/`check`.
|
||||
|
||||
4. Добавить скрипты в `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"lint": "biome lint .",
|
||||
"format": "biome format --write .",
|
||||
"check": "biome check --write ."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Скрипт | Что делает |
|
||||
|--------|-----------|
|
||||
| `lint` | Проверка правил без правок |
|
||||
| `format` | Автоформатирование всех файлов |
|
||||
| `check` | Lint + format + organize imports в один проход (основная команда) |
|
||||
|
||||
## Стандартный `biome.json`
|
||||
|
||||
Дефолтный `biome.json`, созданный `biome init`, кастомизируется ровно одним блоком — `overrides` для `*.css` с отключённым правилом `suspicious/noUnknownAtRules`. Этот override **обязателен по умолчанию во всех проектах**, независимо от того, подключены ли уже стили: проектный CSS-стек использует `@custom-media` и другие нестандартные at-правила, которые Biome не распознаёт; без override `npm run lint` падает.
|
||||
|
||||
Фрагмент, который добавляется в `biome.json`:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"overrides": [
|
||||
{
|
||||
"includes": ["**/*.css"],
|
||||
"linter": {
|
||||
"rules": {
|
||||
"suspicious": {
|
||||
"noUnknownAtRules": "off"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Если в `biome.json` уже есть массив `overrides` — добавить элемент в него; не дублировать массив.
|
||||
|
||||
Прочая настройка правил Biome — отдельная задача, не входит в стандартный канон.
|
||||
|
||||
## Интеграция с VS Code
|
||||
|
||||
Расширение `biomejs.biome` и автоформатирование при сохранении настраиваются в [Настройка VS Code](/docs/applied/vscode).
|
||||
71
docs/docs/applied/styles/postcss.md
Normal file
71
docs/docs/applied/styles/postcss.md
Normal file
@@ -0,0 +1,71 @@
|
||||
---
|
||||
title: PostCSS
|
||||
keywords: [postcss, postcss.config.mjs, postcss-custom-media, postcss-nesting, autoprefixer, postcss-global-data, csstools, "@custom-media", "@nest", css-процессор]
|
||||
---
|
||||
|
||||
# PostCSS
|
||||
|
||||
Установка и настройка CSS-процессора PostCSS в проекте: набор плагинов, конфиг `postcss.config.mjs`. Выполняется один раз при заведении проекта.
|
||||
|
||||
Правила написания CSS в компонентах — [Использование](/docs/applied/styles/usage).
|
||||
|
||||
## Зачем PostCSS
|
||||
|
||||
Подключаем ради двух вещей:
|
||||
|
||||
- **Вложенность** — `&:hover`, `&::before`, `&._active` и `@media` внутри селектора. Без процессора нативный CSS не покрывает всех нужных кейсов вложенности.
|
||||
- **`@custom-media`** — единые breakpoints проекта (`@media (--md)`) вместо магических `min-width`. Определяются в одном месте, переиспользуются везде.
|
||||
|
||||
Autoprefixer и `@csstools/postcss-global-data` идут довеском под эти две задачи.
|
||||
|
||||
## Требования
|
||||
|
||||
- Next.js 14+ (App Router).
|
||||
- Node.js 18+.
|
||||
|
||||
CSS Modules поддерживаются Next.js из коробки — отдельной установки не требуют.
|
||||
|
||||
## Установка
|
||||
|
||||
1. Установить PostCSS-плагины как devDependencies:
|
||||
|
||||
```bash
|
||||
npm install -D postcss-custom-media postcss-nesting autoprefixer @csstools/postcss-global-data
|
||||
```
|
||||
|
||||
2. Создать `postcss.config.mjs` в корне проекта (см. «Конфиг»).
|
||||
|
||||
## Конфиг
|
||||
|
||||
Файл `postcss.config.mjs` в корне проекта.
|
||||
|
||||
```js
|
||||
// postcss.config.mjs
|
||||
export default {
|
||||
plugins: {
|
||||
'@csstools/postcss-global-data': {
|
||||
files: ['src/shared/styles/media.css'],
|
||||
},
|
||||
'postcss-custom-media': {},
|
||||
'postcss-nesting': {},
|
||||
autoprefixer: {},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Разбор плагинов
|
||||
|
||||
| Плагин | Назначение |
|
||||
|--------|------------|
|
||||
| `@csstools/postcss-global-data` | Подгружает определения `@custom-media` из `src/shared/styles/media.css` перед обработкой каждого CSS-модуля. Семантика — «глобальный файл определений, который не импортируется в исходники» |
|
||||
| `postcss-custom-media` | Поддержка `@custom-media --md (...)` и использования `@media (--md) {}`. Определения берутся из файла, который подгрузил `postcss-global-data` |
|
||||
| `postcss-nesting` | Нативная CSS-вложенность: `&:hover`, `&::before`, `&._active` |
|
||||
| `autoprefixer` | Добавление вендорных префиксов по browserslist |
|
||||
|
||||
### Почему внешний файл с `@custom-media`, а не `@import`
|
||||
|
||||
`@custom-media` — глобальные определения, одинаковые для всего проекта. Держим их в `src/shared/styles/media.css`. `@csstools/postcss-global-data` подгружает этот файл перед каждым модулем, а `postcss-custom-media` заменяет `@media (--md)` на конкретные `@media (min-width: ...)` на этапе сборки. Сами определения в бандл не попадают.
|
||||
|
||||
Опция `importFrom` у `postcss-custom-media` удалена в v10+; её роль теперь выполняет `@csstools/postcss-global-data`.
|
||||
|
||||
Импортировать `media.css` в файлы компонентов **не нужно** и запрещено правилами (см. [Использование](/docs/applied/styles/usage), раздел «Импорт стилей»).
|
||||
@@ -1,10 +1,10 @@
|
||||
---
|
||||
title: Стили
|
||||
title: Использование
|
||||
---
|
||||
|
||||
# Стили
|
||||
# Использование
|
||||
|
||||
Правила написания CSS: PostCSS Modules, форматирование, переменные.
|
||||
Правила написания CSS: PostCSS Modules, форматирование, переменные. Установка и настройка процессора — [PostCSS](/docs/applied/styles/postcss).
|
||||
|
||||
## Общие правила
|
||||
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
title: SVG-спрайты
|
||||
---
|
||||
|
||||
# SVG-спрайты
|
||||
108
docs/docs/applied/svg-sprites/setup.md
Normal file
108
docs/docs/applied/svg-sprites/setup.md
Normal file
@@ -0,0 +1,108 @@
|
||||
---
|
||||
title: Установка и настройка
|
||||
keywords: [svg-sprites, установка, настройка, config, пакет, "@gromlab/svg-sprites", svg-sprites.config.ts]
|
||||
---
|
||||
|
||||
# Установка и настройка
|
||||
|
||||
Первичная настройка пакета `@gromlab/svg-sprites` в проекте. Выполняется один раз при заведении проекта и при смене мажорной версии пакета.
|
||||
|
||||
Что такое спрайты, как с ними работать и как управлять цветом — [Использование](/docs/applied/svg-sprites/usage).
|
||||
|
||||
## Требования
|
||||
|
||||
- Node.js 18+
|
||||
- React 18+
|
||||
|
||||
## Установка
|
||||
|
||||
1. Установить пакет:
|
||||
|
||||
```bash
|
||||
npm install @gromlab/svg-sprites
|
||||
```
|
||||
|
||||
2. Создать `svg-sprites.config.ts` в корне проекта (см. «Стандартный конфиг»).
|
||||
|
||||
3. Создать папку входа для SVG-файлов в слое `shared`:
|
||||
|
||||
```bash
|
||||
mkdir -p src/shared/sprites/icons
|
||||
```
|
||||
|
||||
Источники спрайтов живут в `src/shared/sprites/<group>/` — это слой `shared` SLM-архитектуры (см. [Структура проекта](/docs/applied/project-structure), [Архитектура](/docs/basics/architecture/)). В `src/` посторонних каталогов вне слоёв не заводим.
|
||||
|
||||
4. Добавить скрипты в `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"sprite": "svg-sprites",
|
||||
"predev": "svg-sprites",
|
||||
"prebuild": "svg-sprites"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Хуки `predev` и `prebuild` гарантируют, что спрайты и типы всегда актуальны перед запуском и сборкой.
|
||||
|
||||
5. Добавить сгенерированные артефакты в `.gitignore`:
|
||||
|
||||
```text
|
||||
# Сгенерированные спрайты и React-компонент
|
||||
/public/sprites/
|
||||
/src/ui/svg-sprite/
|
||||
```
|
||||
|
||||
6. Выполнить первую генерацию:
|
||||
|
||||
```bash
|
||||
npm run sprite
|
||||
```
|
||||
|
||||
## Стандартный конфиг
|
||||
|
||||
Файл `svg-sprites.config.ts` в корне проекта. Это канон — отклонения только по явной причине.
|
||||
|
||||
```ts
|
||||
// svg-sprites.config.ts
|
||||
import { defineConfig } from '@gromlab/svg-sprites'
|
||||
|
||||
export default defineConfig({
|
||||
output: 'public/sprites',
|
||||
publicPath: '/sprites',
|
||||
react: 'src/ui/svg-sprite',
|
||||
sprites: [
|
||||
{ name: 'icons', input: 'src/shared/sprites/icons' },
|
||||
],
|
||||
})
|
||||
```
|
||||
|
||||
### Фиксированные значения
|
||||
|
||||
| Опция | Значение | Почему так |
|
||||
|-------|----------|------------|
|
||||
| `output` | `public/sprites` | Единая папка статики Next.js |
|
||||
| `publicPath` | `/sprites` | URL-путь без `public/` (Next.js раздаёт `public/` как `/`) |
|
||||
| `react` | `src/ui/svg-sprite` | Слой `ui/` из архитектуры проекта (→ [Архитектура](/docs/basics/architecture/)) |
|
||||
| `sprites[0].name` | `icons` | Основной спрайт всегда называется `icons` |
|
||||
|
||||
### Трансформации
|
||||
|
||||
Все значения по умолчанию оставлять включёнными:
|
||||
|
||||
```ts
|
||||
transform: {
|
||||
removeSize: true,
|
||||
replaceColors: true,
|
||||
addTransition: true,
|
||||
}
|
||||
```
|
||||
|
||||
Явно прописывать блок `transform` не нужно — пакет применяет эти значения по умолчанию.
|
||||
|
||||
Отключать `replaceColors` — только для отдельного спрайта с фиксированной палитрой (например, брендовые логотипы). Делать это на уровне спрайта, не глобально.
|
||||
|
||||
### Режим
|
||||
|
||||
По умолчанию `mode: 'stack'` — не указывать явно. Переход на `symbol` требует обоснования: превью и примеры в пакете оптимизированы под `stack`.
|
||||
55
docs/docs/applied/svg-sprites/usage.md
Normal file
55
docs/docs/applied/svg-sprites/usage.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Использование
|
||||
keywords: [svg, спрайт, sprite, иконка, icon, SvgSprite, превью, preview, цвет, color]
|
||||
---
|
||||
|
||||
# Использование
|
||||
|
||||
Работа с SVG-иконками через сгенерированный компонент `<SvgSprite/>`. Установка пакета — [Установка и настройка](/docs/applied/svg-sprites/setup).
|
||||
|
||||
## Шаги
|
||||
|
||||
1. **Положить SVG в папку спрайта:**
|
||||
|
||||
```text
|
||||
src/shared/sprites/icons/new-icon.svg
|
||||
```
|
||||
|
||||
2. **Импортировать компонент.** Компонент `<SvgSprite/>` генерируется пакетом вместе с типами имён иконок — автодополнение работает без ручных описаний:
|
||||
|
||||
```tsx
|
||||
import { SvgSprite } from 'ui/svg-sprite'
|
||||
|
||||
<SvgSprite icon="new-icon" />
|
||||
```
|
||||
|
||||
3. **Посмотреть и пощупать иконку — в превью.** Пакет генерирует HTML-превью рядом со спрайтом (`public/sprites/icons.preview.html`). Там виден набор иконок, имена и поведение цвета.
|
||||
|
||||
## Управление цветом
|
||||
|
||||
При сборке цвета в SVG заменяются на CSS-переменные `--icon-color-N`. Управление — через обычный CSS родителя.
|
||||
|
||||
**Моно-иконка** наследует `color` родителя (`--icon-color-1` по умолчанию `currentColor`):
|
||||
|
||||
```css
|
||||
.button {
|
||||
color: var(--color-primary);
|
||||
}
|
||||
```
|
||||
|
||||
**Точечное переопределение** — через переменную:
|
||||
|
||||
```css
|
||||
.icon-danger {
|
||||
--icon-color-1: var(--color-danger);
|
||||
}
|
||||
```
|
||||
|
||||
**Мульти-иконка** — переменные задаются явно, порядок виден в превью:
|
||||
|
||||
```css
|
||||
.folder {
|
||||
--icon-color-1: var(--color-folder-bg);
|
||||
--icon-color-2: var(--color-folder-accent);
|
||||
}
|
||||
```
|
||||
@@ -20,4 +20,4 @@ title: Стилизация
|
||||
- **Магические значения** — произвольные цвета, отступы и скругления запрещены, использовать токены.
|
||||
- **Глобальные стили** вне `app/styles/` запрещены.
|
||||
|
||||
Правила написания CSS, вложенность, медиа-запросы и токены — [Стили](/docs/applied/styles).
|
||||
Правила написания CSS, вложенность, медиа-запросы и токены — [Стили: использование](/docs/applied/styles/usage).
|
||||
|
||||
Reference in New Issue
Block a user