Compare commits
2 Commits
e5e4ace91a
...
v2
| Author | SHA1 | Date | |
|---|---|---|---|
| 47658cdbb9 | |||
| 4aeb1dd6b2 |
@@ -20,9 +20,6 @@ jobs:
|
||||
echo "DOCKER_REGISTRY=$DOCKER_REGISTRY" >> $GITHUB_ENV
|
||||
REGISTRY_IMAGE="$DOCKER_REGISTRY/$(echo "${{ github.repository }}" | tr '[:upper:]' '[:lower:]')"
|
||||
echo "REGISTRY_IMAGE=$REGISTRY_IMAGE" >> $GITHUB_ENV
|
||||
# Версия сборки: тег если есть, иначе короткий SHA
|
||||
BUILD_VERSION=$(git describe --tags --exact-match 2>/dev/null || git rev-parse --short HEAD)
|
||||
echo "BUILD_VERSION=$BUILD_VERSION" >> $GITHUB_ENV
|
||||
|
||||
- name: Login to Container Registry
|
||||
uses: docker/login-action@v3
|
||||
@@ -50,8 +47,6 @@ jobs:
|
||||
push: true
|
||||
tags: ${{ steps.meta.outputs.tags }}
|
||||
labels: ${{ steps.meta.outputs.labels }}
|
||||
build-args: |
|
||||
BUILD_VERSION=${{ env.BUILD_VERSION }}
|
||||
provenance: false
|
||||
sbom: false
|
||||
|
||||
@@ -78,7 +73,7 @@ jobs:
|
||||
ssh -i ~/.ssh/deploy_key root@188.225.47.78 bash -s <<'SCRIPT'
|
||||
set -e
|
||||
IMAGE="${{ env.REGISTRY_IMAGE }}:latest"
|
||||
CONTAINER="nextjs-style-guide"
|
||||
CONTAINER="frontend-style-guide"
|
||||
|
||||
# Логин в реестр
|
||||
echo '${{ secrets.CR_TOKEN }}' | docker login ${{ env.DOCKER_REGISTRY }} -u '${{ secrets.CR_USER }}' --password-stdin
|
||||
|
||||
6
.gitignore
vendored
6
.gitignore
vendored
@@ -134,8 +134,4 @@ dist
|
||||
# VitePress
|
||||
.vitepress/cache
|
||||
.vitepress/dist
|
||||
docs/.vitepress
|
||||
|
||||
# Генерируется через `npm run llms`
|
||||
docs/public/
|
||||
generated/
|
||||
docs/.vitepress
|
||||
@@ -1,117 +1,112 @@
|
||||
import { defineConfig } from 'vitepress';
|
||||
|
||||
const sidebar = [
|
||||
{
|
||||
text: 'Главная',
|
||||
link: '/docs/',
|
||||
},
|
||||
const ruSidebar = [
|
||||
{
|
||||
text: 'Workflow',
|
||||
link: '/docs/workflow',
|
||||
link: '/workflow',
|
||||
},
|
||||
{
|
||||
text: 'Базовые правила',
|
||||
items: [
|
||||
{ text: 'Технологии и библиотеки', link: '/docs/basics/tech-stack' },
|
||||
{ text: 'Именование', link: '/docs/basics/naming' },
|
||||
{
|
||||
text: 'Архитектура',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: 'Обзор', link: '/docs/basics/architecture/' },
|
||||
{ text: 'Слои', link: '/docs/basics/architecture/reference/layers' },
|
||||
{ text: 'Модули', link: '/docs/basics/architecture/reference/modules' },
|
||||
{ text: 'Сегменты', link: '/docs/basics/architecture/reference/segments' },
|
||||
],
|
||||
},
|
||||
{ text: 'Стиль кода', link: '/docs/basics/code-style' },
|
||||
{ text: 'Документирование', link: '/docs/basics/documentation' },
|
||||
{ text: 'Типизация', link: '/docs/basics/typing' },
|
||||
{ text: 'Технологии и библиотеки', link: '/basics/tech-stack' },
|
||||
{ text: 'Именование', link: '/basics/naming' },
|
||||
{ text: 'Архитектура', link: '/basics/architecture' },
|
||||
{ text: 'Стиль кода', link: '/basics/code-style' },
|
||||
{ text: 'Документирование', link: '/basics/documentation' },
|
||||
{ text: 'Типизация', link: '/basics/typing' },
|
||||
],
|
||||
},
|
||||
{
|
||||
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: 'Стили',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: 'PostCSS', link: '/docs/applied/styles/postcss' },
|
||||
{ text: 'Использование', link: '/docs/applied/styles/usage' },
|
||||
],
|
||||
},
|
||||
{ text: 'Изображения', link: '/docs/applied/images-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' },
|
||||
{ text: 'Структура проекта', link: '/applied/project-structure' },
|
||||
{ text: 'Компоненты', link: '/applied/components' },
|
||||
{ text: 'Страницы (App Router)', link: '/applied/page-level' },
|
||||
{ text: 'Шаблоны и генерация кода', link: '/applied/templates-generation' },
|
||||
{ text: 'Стили', link: '/applied/styles' },
|
||||
{ text: 'Изображения', link: '/applied/images-sprites' },
|
||||
{ text: 'SVG-спрайты', link: '/applied/svg-sprites' },
|
||||
{ text: 'Видео', link: '/applied/video' },
|
||||
{ text: 'API', link: '/applied/api' },
|
||||
{ text: 'Stores', link: '/applied/stores' },
|
||||
{ text: 'Хуки', link: '/applied/hooks' },
|
||||
{ text: 'Шрифты', link: '/applied/fonts' },
|
||||
{ text: 'Локализация', link: '/applied/localization' },
|
||||
{ text: 'Настройка VS Code', link: '/applied/vscode' },
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
/**
|
||||
* Vite-плагин: отдаёт `.txt` и `.md` с явной кодировкой UTF-8.
|
||||
* Без этого браузер декодирует как ISO-8859-1 и кириллица ломается.
|
||||
*/
|
||||
const utf8TextPlugin = {
|
||||
name: 'utf8-text-files',
|
||||
configureServer(server: any) {
|
||||
server.middlewares.use((req: any, res: any, next: any) => {
|
||||
const url: string = req.url || '';
|
||||
if (url.endsWith('.txt') || url.endsWith('.md')) {
|
||||
res.setHeader('Content-Type', 'text/plain; charset=utf-8');
|
||||
}
|
||||
next();
|
||||
});
|
||||
const enSidebar = [
|
||||
{
|
||||
text: 'Processes',
|
||||
items: [
|
||||
{ text: 'Getting Started', link: '/en/workflow/getting-started' },
|
||||
{ text: 'Creating an App', link: '/en/workflow/creating-app' },
|
||||
{ text: 'Creating Pages', link: '/en/workflow/creating-pages' },
|
||||
{ text: 'Creating Components', link: '/en/workflow/creating-components' },
|
||||
{ text: 'Styling', link: '/en/workflow/styling' },
|
||||
{ text: 'Data Fetching', link: '/en/workflow/data-fetching' },
|
||||
{ text: 'State Management', link: '/en/workflow/state-management' },
|
||||
{ text: 'Localization', link: '/en/workflow/localization' },
|
||||
],
|
||||
},
|
||||
};
|
||||
{
|
||||
text: 'Basic Rules',
|
||||
items: [
|
||||
{ text: 'Tech Stack', link: '/en/basics/tech-stack' },
|
||||
{ text: 'Architecture', link: '/en/basics/architecture' },
|
||||
{ text: 'Code Style', link: '/en/basics/code-style' },
|
||||
{ text: 'Naming', link: '/en/basics/naming' },
|
||||
{ text: 'Documentation', link: '/en/basics/documentation' },
|
||||
{ text: 'Typing', link: '/en/basics/typing' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'Applied Sections',
|
||||
items: [
|
||||
{ text: 'VS Code Setup', link: '/en/applied/vscode' },
|
||||
{ text: 'Project Structure', link: '/en/applied/project-structure' },
|
||||
{ text: 'Components', link: '/en/applied/components' },
|
||||
{ text: 'Page-level Components', link: '/en/applied/page-level' },
|
||||
{ text: 'Templates & Code Generation', link: '/en/applied/templates-generation' },
|
||||
{ text: 'Styles', link: '/en/applied/styles' },
|
||||
{ text: 'Images', link: '/en/applied/images-sprites' },
|
||||
{ text: 'SVG Sprites', link: '/en/applied/svg-sprites' },
|
||||
{ text: 'Video', link: '/en/applied/video' },
|
||||
{ text: 'API', link: '/en/applied/api' },
|
||||
{ text: 'Stores', link: '/en/applied/stores' },
|
||||
{ text: 'Hooks', link: '/en/applied/hooks' },
|
||||
{ text: 'Fonts', link: '/en/applied/fonts' },
|
||||
{ text: 'Localization', link: '/en/applied/localization' },
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
export default defineConfig({
|
||||
srcDir: 'docs',
|
||||
// `docs/public/` содержит сгенерированные `.md`-копии и `llms.txt` для LLM
|
||||
// (попадают в корень `dist/` как статика). Исключаем из сканирования
|
||||
// страниц, иначе VitePress рендерит их как HTML-страницы.
|
||||
srcExclude: ['public/**'],
|
||||
lang: 'ru-RU',
|
||||
title: 'NextJS Style Guide',
|
||||
description: 'Стандарты разработки на Next.js + TypeScript с архитектурой SLM',
|
||||
description: 'Правила и стандарты разработки на NextJS и TypeScript',
|
||||
|
||||
vite: {
|
||||
plugins: [utf8TextPlugin],
|
||||
define: {
|
||||
__BUILD_VERSION__: JSON.stringify(process.env.BUILD_VERSION || 'dev'),
|
||||
rewrites: {
|
||||
'ru/:rest*': ':rest*',
|
||||
},
|
||||
|
||||
locales: {
|
||||
root: {
|
||||
label: 'Русский',
|
||||
lang: 'ru-RU',
|
||||
themeConfig: {
|
||||
sidebar: ruSidebar,
|
||||
},
|
||||
},
|
||||
en: {
|
||||
label: 'English',
|
||||
lang: 'en-US',
|
||||
link: '/en/',
|
||||
themeConfig: {
|
||||
sidebar: enSidebar,
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
themeConfig: {
|
||||
sidebar,
|
||||
socialLinks: [
|
||||
{ icon: 'github', link: 'https://gromlab.ru/docs/nextjs-style-guide' },
|
||||
],
|
||||
},
|
||||
|
||||
// Расширенный блок описания для llms.txt — даёт LLM полный
|
||||
// технический контекст: стек, методология, охват тем.
|
||||
// Используется в generate-llms.ts.
|
||||
llmsBlockquote:
|
||||
'Стандарты разработки frontend-приложений на Next.js (App Router) + TypeScript + React с архитектурой SLM (Scoped Layered Module Design — модульная архитектура со слоями ответственности, где каждый модуль содержит всё необходимое: компоненты, хуки, сторы, типы, стили).',
|
||||
llmsContext:
|
||||
'Стек: React, TypeScript, Next.js App Router, Mantine UI, SWR, Zustand, i18next, PostCSS Modules, Vitest, clsx.\n\nДокументация покрывает архитектуру SLM (слои, модули, сегменты, направление зависимостей, публичный API), правила оформления кода (именование, форматирование, импорты, типизация, JSDoc), реализацию компонентов и хуков, работу с App Router, кодогенерацию из шаблонов, стилизацию (Mobile First, токены), работу с API и сокетами, управление состоянием через Zustand, локализацию, ассеты (шрифты, изображения, SVG-спрайты) и настройку VS Code.',
|
||||
} as any);
|
||||
});
|
||||
|
||||
@@ -15,5 +15,3 @@
|
||||
max-width: 100%;
|
||||
overflow-wrap: anywhere;
|
||||
}
|
||||
|
||||
|
||||
|
||||
11
AGENTS.md
11
AGENTS.md
@@ -3,6 +3,11 @@
|
||||
При работе с документацией следовать правилам из CONTRIBUTING.md.
|
||||
|
||||
- Язык документации и коммитов — русский.
|
||||
- После изменений в `.md`-файлах — запустить `npm run llms` для обновления `llms.txt` и README.
|
||||
- При добавлении нового раздела — обновить сайдбар (`.vitepress/config.ts`):
|
||||
он же является источником порядка и группировки для `llms.txt`.
|
||||
- Исходники документации — в `src/`, только `.md` файлы.
|
||||
- Скрипты и манифесты сборки — в `scripts/`.
|
||||
- Общие правила — в `src/base/`.
|
||||
- Фреймворк-специфичные — в `src/{framework}/`.
|
||||
- Точки входа (`DEVELOP.md`, `REVIEW.md`) — в `src/{framework}/`.
|
||||
- После изменений в `.md`-файлах — запустить `npm run build:ai` для пересборки `dist/ai/`.
|
||||
- При добавлении нового раздела — добавить файл в `src/` и путь в манифест `scripts/{fw}.build.js`.
|
||||
- Frontmatter каждого `.md`-файла содержит поля `title`, `scope`, `keywords`, `when`.
|
||||
|
||||
296
CONTRIBUTING.md
296
CONTRIBUTING.md
@@ -1,247 +1,129 @@
|
||||
# Правила работы над документацией
|
||||
# Правила написания документации
|
||||
|
||||
Мета-документ: как устроен проект, как писать и редактировать разделы.
|
||||
Как писать и редактировать разделы стайлгайда.
|
||||
|
||||
## О проекте
|
||||
## Типы разделов
|
||||
|
||||
Документационный сайт с правилами и стандартами фронтенд-разработки на Next.js + TypeScript.
|
||||
|
||||
- Движок: VitePress
|
||||
- Язык: русский
|
||||
- Контент: `docs/docs/`
|
||||
|
||||
## Команды
|
||||
|
||||
| Команда | Что делает |
|
||||
|---------|-----------|
|
||||
| `npm run dev` | Локальный сервер разработки |
|
||||
| `npm run build` | Сборка статического сайта |
|
||||
| `npm run llms` | Генерация `llms.txt` (карта документации для LLM) и README |
|
||||
|
||||
## Структура файлов
|
||||
|
||||
```
|
||||
docs/
|
||||
├── index.md # Лендинг (URL `/`)
|
||||
└── docs/ # Контент документации (URL `/docs/...`)
|
||||
├── index.md # Главная страница
|
||||
├── workflow.md
|
||||
├── workflow/ # Процессы разработки
|
||||
├── basics/ # Базовые правила
|
||||
│ ├── tech-stack.md
|
||||
│ ├── architecture/
|
||||
│ ├── code-style.md
|
||||
│ ├── naming.md
|
||||
│ ├── documentation.md
|
||||
│ └── typing.md
|
||||
└── applied/ # Прикладные разделы
|
||||
├── vscode.md
|
||||
├── project-structure.md
|
||||
├── components.md
|
||||
├── page-level.md
|
||||
├── templates-generation.md
|
||||
├── styles.md
|
||||
├── images-sprites.md
|
||||
├── svg-sprites.md
|
||||
├── video.md
|
||||
├── api.md
|
||||
├── stores.md
|
||||
├── hooks.md
|
||||
├── fonts.md
|
||||
└── localization.md
|
||||
.vitepress/
|
||||
└── config.ts # Конфигурация VitePress, сайдбар
|
||||
generate-llms.ts # Скрипт генерации llms.txt и README
|
||||
```
|
||||
|
||||
Сгенерированные артефакты (`docs/public/`): `llms.txt`, `llms-full.txt`,
|
||||
`nextjs-style-guide.zip`, `manifest.json`, копии `.md` в `docs/public/docs/`.
|
||||
|
||||
### Добавление нового раздела
|
||||
|
||||
1. Создать `.md`-файл в нужной папке (`docs/docs/basics/` или `docs/docs/applied/`).
|
||||
2. Добавить пункт в сайдбар — `.vitepress/config.ts`.
|
||||
Сайдбар — единственный источник порядка и группировки для `llms.txt`.
|
||||
3. Запустить `npm run llms` для обновления `llms.txt` и README.
|
||||
|
||||
## Два типа документации
|
||||
|
||||
### Базовые правила
|
||||
### Базовые правила (`basics/`)
|
||||
|
||||
**Отвечает на вопрос:** «Каким должен быть любой код?»
|
||||
|
||||
Универсальные стандарты, **не привязанные к конкретной области**.
|
||||
Правило базовое, если оно применимо ко всему коду одинаково: именование переменных, оформление импортов, когда использовать `type` vs `interface`.
|
||||
Универсальные стандарты, не привязанные к конкретной области.
|
||||
Правило базовое, если оно применимо ко всему коду одинаково.
|
||||
|
||||
Примеры в базовых правилах допускаются, но служат иллюстрацией принципа, а не инструкцией по конкретной области.
|
||||
**Граница:** если правило касается только одной области — оно прикладное.
|
||||
|
||||
**Граница:** если правило касается только одной области (только стили, только компоненты, только API) — оно живёт в прикладном разделе, не в базовых.
|
||||
|
||||
### Прикладные разделы
|
||||
### Прикладные разделы (`applied/`)
|
||||
|
||||
**Отвечает на вопрос:** «Как работать с X?»
|
||||
|
||||
Полное описание конкретной области: структура файлов, правила, именование, типизация, примеры.
|
||||
|
||||
**Граница:** прикладной раздел не дублирует базовые правила.
|
||||
Если правило уже описано в базовых — прикладной раздел ссылается на него, но не повторяет.
|
||||
**Граница:** не дублирует базовые правила. Если правило уже описано в базовых — ссылается, но не повторяет.
|
||||
|
||||
## Структура прикладного раздела
|
||||
### Триггеры (`triggers/`)
|
||||
|
||||
Шаблон ниже описывает все допустимые секции. Раздел включает только те секции, которые для него релевантны — пустые секции не создаются.
|
||||
**Отвечает на вопрос:** «Как выполнить задачу X?»
|
||||
|
||||
```markdown
|
||||
# {Название}
|
||||
Конкретная инструкция: какие разделы прочитать, какие шаги выполнить. Триггер ссылается на basics/ и applied/, но не дублирует их. Группируются по роли: `triggers/develop/`, `triggers/review/`, `triggers/architect/`.
|
||||
|
||||
Краткое описание: о чём раздел и какие аспекты работы с областью он охватывает.
|
||||
Структура триггера:
|
||||
|
||||
## Что нужно знать
|
||||
- **Заголовок** — глагол + объект ("Создать компонент", "Добавить иконку")
|
||||
- **Описание** — одно предложение: что делает триггер
|
||||
- **Прочитай перед началом** — ссылки на basics/ и applied/
|
||||
- **Шаги** — нумерованный список действий со ссылками
|
||||
- **Смежные триггеры** — ссылки на связанные задачи
|
||||
- **Проверь себя** — чеклист из 2-5 пунктов для самопроверки
|
||||
|
||||
Неочевидная информация, которую читатель должен знать перед чтением раздела.
|
||||
Если для раздела нет такой вводной — секция не создаётся.
|
||||
### Фреймворк-специфичные (`{framework}/`)
|
||||
|
||||
## Структура
|
||||
Разделы и триггеры, которые применимы только к конкретному фреймворку. Те же категории — `applied/` и `triggers/`.
|
||||
|
||||
Файловая организация: какие файлы создавать и куда класть.
|
||||
Обязательно — дерево файлов через code-block.
|
||||
**Граница:** если правило одинаково для всех фреймворков — оно в `base/`.
|
||||
|
||||
## Правила
|
||||
|
||||
Конкретные требования, специфичные для области. Делятся на две подсекции:
|
||||
|
||||
### Реализация
|
||||
|
||||
Как написан код внутри файла: синтаксис, паттерны, API.
|
||||
Отвечает на вопрос: «Как писать код?»
|
||||
|
||||
Примеры: объявление через `const`, деструктуризация пропсов, формат вызова `cl()`, способ подключения стилей, структура хука.
|
||||
|
||||
### Организация
|
||||
|
||||
Как компонент/модуль встроен в проект: файловые границы, зоны ответственности, экспорт.
|
||||
Отвечает на вопрос: «Где что лежит и за что отвечает?»
|
||||
|
||||
Примеры: один компонент — один файл, вложенные компоненты в `ui/`, логика выносится в `model/`.
|
||||
|
||||
Формат обеих подсекций — маркированный список.
|
||||
Для неочевидных случаев — блоки «Хорошо / Плохо».
|
||||
Если в области нет правил одной из категорий — подсекция не создаётся.
|
||||
|
||||
## Именование
|
||||
|
||||
Соглашения по именам, специфичные для этой области.
|
||||
Только то, что НЕ покрыто в базовом разделе «Именование».
|
||||
|
||||
## Типизация
|
||||
|
||||
Правила типизации, специфичные для этой области.
|
||||
Только то, что НЕ покрыто в базовом разделе «Типизация».
|
||||
|
||||
## Документирование
|
||||
|
||||
Что и как документировать в этой области.
|
||||
Только то, что НЕ покрыто в базовом разделе «Документирование».
|
||||
|
||||
## Примеры
|
||||
|
||||
Полноценные примеры кода.
|
||||
Каждый пример с путём к файлу и пояснениями.
|
||||
|
||||
```
|
||||
|
||||
### Порядок секций
|
||||
|
||||
Порядок фиксированный: контекст → структура → правила → специализации базовых правил → примеры.
|
||||
|
||||
Логика: читатель сначала понимает «что это», потом «где это лежит», потом «как это делать», и в конце видит полный пример.
|
||||
|
||||
### Секции-расширения базовых правил
|
||||
|
||||
«Именование», «Типизация», «Документирование» в прикладном разделе — это **точки расширения** базовых правил.
|
||||
|
||||
- В базовых описано общее: `camelCase` для переменных, `type` vs `interface`, формат JSDoc.
|
||||
- В прикладном разделе описано специфичное: как именовать CSS-классы (стили), как типизировать пропсы компонентов (компоненты), как документировать хуки (хуки).
|
||||
|
||||
Если для области нет специфики по именованию, типизации или документированию — секция не создаётся.
|
||||
|
||||
## Конвенции оформления
|
||||
|
||||
### Frontmatter
|
||||
## Frontmatter
|
||||
|
||||
Каждый `.md`-файл начинается с YAML frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Название раздела
|
||||
scope: basics | applied | triggers
|
||||
keywords: [ключевое слово 1, ключевое слово 2]
|
||||
when: "Когда агенту читать этот раздел"
|
||||
---
|
||||
```
|
||||
|
||||
Значение `title` совпадает с текстом `h1`-заголовка в файле.
|
||||
| Поле | Описание |
|
||||
|------|----------|
|
||||
| `title` | Название раздела. Совпадает с `h1` в файле |
|
||||
| `scope` | Тип: `basics`, `applied` или `triggers` |
|
||||
| `keywords` | Ключевые слова для поиска агентом |
|
||||
| `when` | Описание ситуации, когда раздел релевантен |
|
||||
|
||||
## Структура прикладного раздела
|
||||
|
||||
Раздел включает только релевантные секции — пустые не создаются.
|
||||
|
||||
```markdown
|
||||
# {Название}
|
||||
|
||||
Краткое описание: о чём раздел.
|
||||
|
||||
## Что нужно знать
|
||||
|
||||
Неочевидная вводная информация (если есть).
|
||||
|
||||
## Структура
|
||||
|
||||
Файловая организация. Обязательно — дерево файлов.
|
||||
|
||||
## Правила
|
||||
|
||||
### Реализация
|
||||
|
||||
Как писать код: синтаксис, паттерны, API.
|
||||
|
||||
### Организация
|
||||
|
||||
Где что лежит: файловые границы, зоны ответственности, экспорт.
|
||||
|
||||
## Именование
|
||||
|
||||
Специфичные для области соглашения (не покрытые в basics/naming).
|
||||
|
||||
## Типизация
|
||||
|
||||
Специфичные для области правила (не покрытые в basics/typing).
|
||||
|
||||
## Документирование
|
||||
|
||||
Специфичные для области правила (не покрытые в basics/documentation).
|
||||
|
||||
## Примеры
|
||||
|
||||
Полноценные примеры кода с путями к файлам.
|
||||
```
|
||||
|
||||
Порядок фиксированный: контекст -> структура -> правила -> специализации базовых -> примеры.
|
||||
|
||||
## Конвенции оформления
|
||||
|
||||
### Заголовки
|
||||
|
||||
- Один `h1` на файл — совпадает с `title` из frontmatter.
|
||||
- Сразу после `h1` — вводный абзац (одно-два предложения).
|
||||
- Основные секции — `h2`.
|
||||
- Подсекции внутри `h2` — `h3`.
|
||||
- `h4` не используется.
|
||||
|
||||
### Вводный абзац
|
||||
|
||||
Абзац сразу после `h1` отвечает на вопрос «о чём этот раздел?».
|
||||
Он попадает в `llms.txt` и `README.md` архива как краткое описание,
|
||||
поэтому должен быть плотным и без воды.
|
||||
|
||||
**Правила:**
|
||||
|
||||
- Не начинать с «Раздел описывает», «Этот раздел», «В этом разделе»,
|
||||
«Здесь рассмотрено», «В этом документе».
|
||||
- Начинать с подлежащего — самой темы (`Слои SLM:`, `Соглашения об именовании:`).
|
||||
- Двоеточие или тире для перечисления **категорий и областей**, а не
|
||||
конкретных значений из содержимого.
|
||||
- Не дублировать содержимое: если внутри раздела 12 правил —
|
||||
не перечислять их во вводном абзаце.
|
||||
- Не аргументировать («единые правила делают код предсказуемым»).
|
||||
- 1–2 предложения.
|
||||
|
||||
**Проверка:** если при добавлении нового правила/инструмента/раздела
|
||||
вводный абзац придётся править — он слишком конкретный.
|
||||
|
||||
**Хорошо:**
|
||||
|
||||
```markdown
|
||||
Слои SLM: назначение, классификация, направление зависимостей, правила.
|
||||
```
|
||||
|
||||
```markdown
|
||||
Базовый стек проекта по областям: UI, архитектура, данные, состояние,
|
||||
локализация, тестирование, стили, генерация кода.
|
||||
```
|
||||
|
||||
**Плохо:**
|
||||
|
||||
```markdown
|
||||
Раздел описывает слои SLM: что такое слой, какие бывают, как между
|
||||
ними направлены зависимости и какие правила действуют на каждом.
|
||||
```
|
||||
|
||||
```markdown
|
||||
Этот раздел описывает базовый стек технологий и библиотек, принятый в
|
||||
проекте. React, TypeScript, Next.js, SWR, Zustand, i18next.
|
||||
```
|
||||
- Сразу после `h1` — вводный абзац.
|
||||
- Основные секции — `h2`. Подсекции — `h3`. `h4` не используется.
|
||||
|
||||
### Примеры кода
|
||||
|
||||
- Блоки кода с указанием языка: ` ```tsx `, ` ```css `, ` ```bash `, ` ```text `.
|
||||
- Путь к файлу указывается перед блоком кода текстом или комментарием внутри блока.
|
||||
- Путь к файлу — перед блоком кода или комментарием внутри.
|
||||
- Дерево файлов — ` ```text ` с символами `├──`, `└──`, `│`.
|
||||
|
||||
### Блоки «Хорошо / Плохо»
|
||||
|
||||
Используются для контрастного сравнения правильного и неправильного подхода.
|
||||
|
||||
Формат:
|
||||
|
||||
```markdown
|
||||
**Хорошо:**
|
||||
|
||||
@@ -258,16 +140,16 @@ title: Название раздела
|
||||
|
||||
### Таблицы
|
||||
|
||||
Используются для структурированных перечислений: настройки, команды, соответствия.
|
||||
Формат — стандартный Markdown: `| Ключ | Описание |`.
|
||||
|
||||
### Ссылки между разделами
|
||||
|
||||
Прикладной раздел может ссылаться на другие разделы, но не дублирует их содержимое.
|
||||
Ссылаться можно, дублировать содержимое — нет.
|
||||
|
||||
## Принципы
|
||||
|
||||
1. **Не дублировать.** Одна мысль живёт в одном месте. Остальные ссылаются.
|
||||
2. **Базовое vs прикладное.** Если правило применимо ко всему коду — оно базовое. Если только к одной области — прикладное.
|
||||
3. **Пустые секции не создавать.** Если для раздела нет специфики по именованию — секции «Именование» в нём нет.
|
||||
4. **Примеры обязательны.** Прикладной раздел без примеров кода — незавершён.
|
||||
1. **Не дублировать.** Одна мысль — одно место. Остальные ссылаются.
|
||||
2. **Базовое vs прикладное.** Применимо ко всему коду — базовое. К одной области — прикладное.
|
||||
3. **Общее vs специфичное.** Одинаково для всех фреймворков — в `base/`. Для одного — в `{framework}/`.
|
||||
4. **Пустые секции не создавать.**
|
||||
5. **Примеры обязательны.** Прикладной раздел без примеров — незавершён.
|
||||
|
||||
@@ -1,10 +1,5 @@
|
||||
:8080 {
|
||||
root * /srv
|
||||
|
||||
# Кириллица в .txt и .md ломается без явного charset
|
||||
@text path *.txt *.md
|
||||
header @text Content-Type "text/plain; charset=utf-8"
|
||||
|
||||
file_server
|
||||
try_files {path} /index.html
|
||||
}
|
||||
|
||||
@@ -1,13 +1,9 @@
|
||||
FROM node:24-alpine AS build
|
||||
WORKDIR /app
|
||||
# zip нужен для упаковки nextjs-style-guide.zip
|
||||
RUN apk add --no-cache zip
|
||||
COPY package*.json ./
|
||||
RUN npm ci
|
||||
COPY . .
|
||||
ARG BUILD_VERSION=dev
|
||||
ENV BUILD_VERSION=${BUILD_VERSION}
|
||||
RUN npm run llms && npm run build
|
||||
RUN npm run build
|
||||
|
||||
FROM caddy:2-alpine
|
||||
COPY Caddyfile /etc/caddy/Caddyfile
|
||||
|
||||
@@ -1,19 +0,0 @@
|
||||
# Ассистент
|
||||
|
||||
## Для ассистента
|
||||
|
||||
- Всегда используй Русский язык для общения и генерации документации/комментариев/коммитов.
|
||||
- Всегда следуй этим правилам при генерации кода и ответах.
|
||||
- Всегда пиши план действий перед генерацией кода.
|
||||
- Всегда спрашивай разрешения у пользователя перед генерацией кода.
|
||||
- Всегда проверяй, что код соответствует линтингу и форматированию.
|
||||
- Всегда сверяйся с чек-листом при генерации кода.
|
||||
- Не предлагай решения, которые противоречат этим правилам этого файла.
|
||||
- Если не уверен — уточни у пользователя, не гадай, не придумывай.
|
||||
|
||||
## Обязательность чек-листов
|
||||
|
||||
- Все чек-листы, приведённые в правилах, обязательны к исполнению.
|
||||
- Ассистент обязан сверяться с чек-листом при выполнении любой задачи, связанной с кодом.
|
||||
- Нельзя сокращать, игнорировать или опускать пункты чек-листа — каждый пункт должен быть выполнен или явно отмечен как невыполнимый с объяснением причины.
|
||||
- В каждом ответе, связанном с генерацией или изменением кода, ассистент обязан ссылаться на соответствующий чек-лист и подтверждать его выполнение.
|
||||
@@ -1,84 +0,0 @@
|
||||
---
|
||||
title: Stores
|
||||
---
|
||||
|
||||
# Stores
|
||||
|
||||
## Сторы (Stores)
|
||||
|
||||
> В этом разделе собраны основные правила и рекомендации по созданию и оформлению сторов. Следуйте этим принципам, чтобы обеспечить чистую архитектуру, удобство поддержки и единый стиль работы с состоянием в проекте.
|
||||
> В проекте для организации состояния используется только библиотека Zustand.
|
||||
|
||||
### Структура
|
||||
- Store размещается в файле `<store-name>.store.ts` в папке `stores/` на своём уровне абстракции согласно архитектуре проекта.
|
||||
- Интерфейс состояния описывается в этом же файле с суффиксом `State` (PascalCase).
|
||||
- Для каждого store создаётся отдельный хук доступа (например, `useTodoStore`).
|
||||
- Для глобальных сторов используйте только `shared/store`.
|
||||
|
||||
### Именование
|
||||
- Соблюдайте [правила именования файлов и папок](#правила-именования-файлов-и-папок):
|
||||
- Файл store — `<store-name>.store.ts` (kebab-case).
|
||||
- Имя интерфейса состояния — PascalCase с суффиксом `State`.
|
||||
- Имя хука — camelCase с префиксом `use`.
|
||||
|
||||
### Требования
|
||||
- В store допускается только хранение состояния и методы управления им, без бизнес-логики, асинхронных операций и side-effects (см. раздел "Правила организации и использовалья Store").
|
||||
- Для методов, изменяющих состояние через set, если используется функция — тело функции в фигурных скобках, return с новой строки после стрелки.
|
||||
- Не дублируйте логику между сторами.
|
||||
|
||||
### Типизация
|
||||
- Всегда указывайте типы для всех полей состояния и методов.
|
||||
- Не используйте неявное приведение типов и не полагайтесь на автоматический вывод, если это может снизить читаемость или безопасность.
|
||||
|
||||
### Документирование
|
||||
- Документируйте только назначение store и смысл полей, строго по [правилам документирования кода](#правило-для-документирования-кода).
|
||||
|
||||
### Экспорт
|
||||
- Экспортируйте хук доступа к store и интерфейс состояния через `index.ts` слоя/компонента.
|
||||
|
||||
### Примеры
|
||||
|
||||
```ts
|
||||
import { create } from 'zustand';
|
||||
import { TodoItem } from './types/todo-item.interface';
|
||||
|
||||
/**
|
||||
* Состояние хранилища задач.
|
||||
*/
|
||||
export interface TodoStoreState {
|
||||
/** Массив задач. */
|
||||
items: TodoItem[];
|
||||
/** Добавить задачу. */
|
||||
addTodo: (item: TodoItem) => void;
|
||||
/** Удалить задачу. */
|
||||
removeTodo: (id: string) => void;
|
||||
}
|
||||
|
||||
/**
|
||||
* Хук для доступа к хранилищу задач.
|
||||
*/
|
||||
export const useTodoStore = create<TodoStoreState>((set) => ({
|
||||
items: [],
|
||||
addTodo: (item) => set((state) => {
|
||||
return {
|
||||
items: [...state.items, item],
|
||||
};
|
||||
}),
|
||||
removeTodo: (id) => set((state) => {
|
||||
return {
|
||||
items: state.items.filter((t) => t.id !== id),
|
||||
};
|
||||
}),
|
||||
}));
|
||||
```
|
||||
|
||||
### Чек-лист
|
||||
|
||||
- [ ] Store размещён в `stores/<store-name>.store.ts` на своём уровне абстракции согласно архитектуре проекта.
|
||||
- [ ] Именование файлов и сущностей соответствует [правилам именования файлов и папок](#правила-именования-файлов-и-папок).
|
||||
- [ ] Все поля и методы строго типизированы (см. [общие правила типизации](#общие-правила-типизации)).
|
||||
- [ ] В store только состояние и методы управления им, без бизнес-логики и side-effects.
|
||||
- [ ] Для методов, изменяющих состояние через set, используется функция с return с новой строки.
|
||||
- [ ] Документировано только назначение store и смысл полей (см. [правила документирования кода](#правило-для-документирования-кода)).
|
||||
- [ ] Нет неиспользуемого или невалидного кода.
|
||||
- [ ] Экспорт через индексный файл.
|
||||
@@ -1,227 +0,0 @@
|
||||
---
|
||||
title: CSS
|
||||
---
|
||||
|
||||
# CSS
|
||||
|
||||
## Правила оформления и стилизации CSS-кода
|
||||
|
||||
- **Препроцессоры**
|
||||
Используй PostCSS и модули для стилизации.
|
||||
|
||||
- **Архитектура написания стилей**
|
||||
Используй подход **Mobile First**
|
||||
Используй CSS переменные для стилизации.
|
||||
Используй Custom Media Queries для адаптивных стилей.
|
||||
Используй BEM для именования классов.
|
||||
Между каждым CSS-правилом (селектором) должен быть один пустой сброс строки, пример:
|
||||
```css
|
||||
.todo-list {
|
||||
max-width: 600px;
|
||||
padding: var(--space-3);
|
||||
|
||||
@media (--md) {
|
||||
max-width: 800px;
|
||||
}
|
||||
}
|
||||
|
||||
.todo-list__text {
|
||||
font-size: 18px;
|
||||
|
||||
@media (--md) {
|
||||
font-size: 22px;
|
||||
}
|
||||
}
|
||||
```
|
||||
Запрещено писать правила подряд без пустой строки:
|
||||
```css
|
||||
/* Так делать нельзя! */
|
||||
.todo-list { ... }
|
||||
.todo-list__text { ... }
|
||||
```
|
||||
|
||||
- **Методология именования классов**
|
||||
Использовать методологию **BEM** для именования классов.
|
||||
- Блок: kebab-case, пример `.user-bar { }`
|
||||
- Елемент: kebab-case, соеденный с блоком двойным нижним подчеркиванием, пример `.user-bar__slide { }`
|
||||
- Модификатор: kebab-case, отдельный самостоятельный класс, **не соединяется** с блоком/елементом, имя модификатора всегда начинается с нижнего подчеркивания, пример: `._red { }`
|
||||
|
||||
- **Единицы измерения**
|
||||
Используй `px` как основная единица измирения, так-же допускается использовать остальные единицы измерения если того требует реализуемый дизайн.
|
||||
|
||||
- **Импорт стилей**
|
||||
Стили компонента должны импортироваться только внутри соответствующего компонента.
|
||||
Запрещено импортировать стили одного компонента в другой.
|
||||
Запрещено импортировать `css переменные` в файлы стилей, они доступны глобально.
|
||||
Запрещено импортировать `custom media` в файлы стилей, они доступны глобально.
|
||||
|
||||
- **Переменные**
|
||||
Все значения переменных нужно писать в `/shared/styles` или в Mantine ThemeProvider.
|
||||
Все что не является цветами, брекпоинтами, отступами, скруглением допускаются использоваться в компонентах.
|
||||
Обязательное создавай CSS перменные для:
|
||||
- "Цветов", пример: `--color-danger: red;`.
|
||||
- "Брекпоинты", описываем в (Сustom media) пример: `@custom-media --md (min-width: 62em);`.
|
||||
- "Отспупы (--space)", , пример: `--space-1: 4px;`, `--space-2: 8px;`, `--space-3: 12px;` итд..
|
||||
- "Скругление углов (--radius)", пример: `--radius-1: 4px;`,`--radius-2: 8px;`,`--radius-3: 12px;` итд..
|
||||
|
||||
- **Вложенность селекторов**
|
||||
Запрещено использовать вложенность селекторов.
|
||||
Разрешено использовать вложенность только для:
|
||||
- Псевдо-классов `:hover`, `:active` итд..
|
||||
- Псевдо-елементов `::before`, `::after`
|
||||
- Медиа запросов `@media`
|
||||
- Классы **модификаторы** по методологии BEM
|
||||
Каждый вложенный селектор отделяется 1 пустой строкой.
|
||||
|
||||
- **Медиа запросы**
|
||||
Строго запрещено использовать `@media` без вложения в селектор.
|
||||
Строго запрещено использовать в теле `@media` любые селекторы.
|
||||
Разрешено использовать только Custom Media Queries (например, `@media (--md) {}`).
|
||||
Запрещено использовать любые произвольные значения breakpoints (например, max-width: 768px).
|
||||
**Пример как правильно писать @media**
|
||||
```css
|
||||
.todo-list {
|
||||
max-width: 600px;
|
||||
padding: 24px;
|
||||
|
||||
@media (--md) {
|
||||
max-width: 800px;
|
||||
}
|
||||
}
|
||||
|
||||
.todo-list__text {
|
||||
font-size: 18px;
|
||||
|
||||
@media (--md) {
|
||||
font-size: 22px;
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
**Пример как неправильно писать @media**
|
||||
```css
|
||||
// Медиа запрос не вложен в селектор
|
||||
@media (--md) {
|
||||
.todo-list {
|
||||
max-width: 600px;
|
||||
padding: 24px;
|
||||
}
|
||||
.todo-list__text {
|
||||
font-size: 18px;
|
||||
}
|
||||
}
|
||||
// Используется стандартный `min-width: 992px` вмето Custom Media Queries
|
||||
@media (min-width: 992px) {
|
||||
// Внутри @media запроса используются селекторы
|
||||
.todo-list {
|
||||
max-width: 600px;
|
||||
padding: 24px;
|
||||
}
|
||||
.todo-list__text {
|
||||
font-size: 18px;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- **Глобальные стили и сбросы**
|
||||
Все глобальные стили (например, сбросы) должны располагаться в отдельном файле, например, `src/app/styles/global.css`.
|
||||
|
||||
- **Использование Mantine и PostCSS**
|
||||
Для стандартных визуальных компонентов (кнопки, инпуты, layout, grid, notifications и т.д.) использовать только Mantine и его ThemeProvider.
|
||||
Запрещено использовать в Mantine компонентах его props/styling, вмето этого нужно добавлять кастомные стили PostCSS.
|
||||
Кастомные стили допускаются только в случае, если требуемый дизайн невозможно реализовать средствами Mantine.
|
||||
При написании кастомных стилей стараться использовать переменные и токены Mantine, если это возможно.
|
||||
|
||||
- **Порядок CSS-свойств**
|
||||
В стилях рекомендуется придерживаться логического порядка свойств:
|
||||
1. Позиционирование (position, top, left, z-index и т.д.)
|
||||
2. Блочная модель (display, width, height, margin, padding и т.д.)
|
||||
3. Оформление (background, border, box-shadow и т.д.)
|
||||
4. Текст (font, color, text-align и т.д.)
|
||||
5. Прочее (transition, animation и т.д.)
|
||||
|
||||
- **Комментарии**
|
||||
В стилях запрещено использовать комментарии.
|
||||
|
||||
- **Дублирования**
|
||||
Не дублировать стили между компонентами. Общие стили выносить в shared/styles или использовать переменные.
|
||||
|
||||
- **Примеры кода стилей**
|
||||
Пример как хорошо:
|
||||
```css
|
||||
/* Блок BEM */
|
||||
.user-bar {
|
||||
display: none;
|
||||
color: black;
|
||||
|
||||
/* Медиа запрос custom media и отделяется 1 пустой строкой */
|
||||
@media (--md) {
|
||||
display: flex;
|
||||
}
|
||||
}
|
||||
|
||||
/* Елемент BEM отделяется 1 пустой строкой*/
|
||||
.user-bar__button-next {
|
||||
background-color: #f0f0f0;
|
||||
|
||||
/* Псевдо-класс отделяется 1 пустой строкой*/
|
||||
&:hover {
|
||||
background-color: #e0e0e0;
|
||||
}
|
||||
|
||||
/* Модификатор BEM отделяется 1 пустой строкой*/
|
||||
&._blue {
|
||||
background-color: #2b2bbe;
|
||||
}
|
||||
|
||||
/* Модификатор BEM отделяется 1 пустой строкой*/
|
||||
&._green {
|
||||
background-color: #29c53d;
|
||||
}
|
||||
}
|
||||
```
|
||||
Пример как плохо писать:
|
||||
```css
|
||||
.user-bar {
|
||||
display: none;
|
||||
color: black;
|
||||
&__button {
|
||||
&_next {
|
||||
background-color: #f0f0f0;
|
||||
&:hover {
|
||||
background-color: #e0e0e0;
|
||||
}
|
||||
&._blue {
|
||||
background-color: #2b2bbe;
|
||||
}
|
||||
&._green {
|
||||
background-color: #29c53d;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@media (min-width: 992px) {
|
||||
.user-bar {
|
||||
display: flex;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Чек лист для проверки стилизации.**
|
||||
- [ ] Используется PostCSS и CSS-модули для стилизации.
|
||||
- [ ] Применён подход Mobile First.
|
||||
- [ ] Именование классов строго по BEM:
|
||||
- [ ] Модификатор — отдельный класс, начинается с нижнего подчёркивания (например, `._red`, `._active`)
|
||||
- [ ] Все CSS-переменные (цвета, брейкпоинты, отступы, скругления) определены только в `/shared/styles` или через Mantine ThemeProvider.
|
||||
- [ ] Для медиа-запросов используются только custom media переменные из `/shared/styles/media.css`.
|
||||
- [ ] Соблюдается правила вложености селекторов.
|
||||
- [ ] Соблюдается правила отступов селекторов.
|
||||
- [ ] Глобальные стили (reset) вынесены в отдельный файл, остальные стили — модульные.
|
||||
- [ ] Для стандартных UI-элементов используются только компоненты Mantine, кастомные стили — только при необходимости.
|
||||
- [ ] В Mantine-компонентах не используются props/styling для стилизации, только PostCSS.
|
||||
- [ ] Кастомные стили используют переменные и токены Mantine, если это возможно.
|
||||
- [ ] В стилях нет комментариев.
|
||||
- [ ] Стили компонента импортируются только внутри соответствующего компонента.
|
||||
- [ ] Нет импорта стилей одного компонента в другой.
|
||||
- [ ] Нет импорта файлов переменных и custom media — они доступны глобально.
|
||||
- [ ] Нет дублирования стилей между компонентами, общие стили вынесены в shared/styles или используются переменные.
|
||||
@@ -1,88 +0,0 @@
|
||||
---
|
||||
title: Компоненты
|
||||
---
|
||||
|
||||
# Компоненты
|
||||
|
||||
## Правила создания и работы с компонентами.
|
||||
|
||||
### 1. Структура компонента
|
||||
Ассистент при создании/рефакторинге компонента должен **строго** придерживаться следующей структуры файлов и папок:
|
||||
|
||||
```
|
||||
component-name/
|
||||
index.ts
|
||||
component-name.tsx
|
||||
styles/
|
||||
component-name.module.css
|
||||
locales/
|
||||
ru.json
|
||||
en.json
|
||||
types/
|
||||
component-name.interface.ts
|
||||
component-name.type.ts
|
||||
component-name.enum.ts
|
||||
schemas/
|
||||
schema-name.schema.ts
|
||||
utils/
|
||||
util-name.util.ts
|
||||
hooks/
|
||||
use-hook-name.hook.ts
|
||||
stores/
|
||||
store-name.store.ts
|
||||
ui/
|
||||
... # вложенные компоненты для component-name
|
||||
```
|
||||
|
||||
Пояснения к структуре компонента:
|
||||
**Обязательные файлы** обязательны для всех компонентов, даже если они пустые.
|
||||
- component-name/: Папка компонента корень для всего компонента.
|
||||
- index.ts: экспортирует главный компонент, интерфейс и всё, что может быть переиспользовано.
|
||||
- component-name.tsx: главный компонент.
|
||||
- styles/component-name.module.css: стили компонента.
|
||||
- locales/ru.json: локализация на русском языке.
|
||||
- locales/en.json: локализация на английском языке.
|
||||
- types/component-name.interface.ts: интерфейс пропсов компонента.
|
||||
**Не обязательные файлы** добавляются только при необходимости
|
||||
- types/component-name.type.ts: типы компонента.
|
||||
- types/component-name.enum.ts: enum компонента.
|
||||
- schemas/schema-name.schema.ts: схемы валидации.
|
||||
- utils/util-name.util.ts: утилиты компонента.
|
||||
- hooks/use-hook-name.hook.ts: хуки компонента.
|
||||
- stores/store-name.store.ts: хранилища состояния компонента.
|
||||
- ui/: Папка для вложенных компонентов.
|
||||
|
||||
### Требования к компоненту
|
||||
- Использовать `memo()` для всех компонентов, которые принимают пропсы.
|
||||
- Использовать `useMemo` для всех вычислений, которые передаются в пропсы других компонентов.
|
||||
- Использовать `useCallback` для всех функций/методов, которые передаются в пропсы других компонентов.
|
||||
|
||||
### Требования к вложенным компонентам
|
||||
- Вложенный компонент — это полноценный компонент, который обязан полностью соблюдать все правила, описанные для компонентов (структура, именование, документация, типизация, стилизация и т.д.).
|
||||
- Все вложенные компоненты размещаются только в папке ui/ основного компонента.
|
||||
|
||||
**Пояснение**
|
||||
Нет необходимости повторять структуру и требования — вложенный компонент подчиняется тем же правилам, что и любой другой компонент, только располагается в папке ui/ родительского компонента.
|
||||
|
||||
### Требования к локализации
|
||||
- Все добавленные локализации обязательно подключать в экземпляр `app/i18n` (чтобы новые namespace были доступны для i18next).
|
||||
|
||||
---
|
||||
|
||||
### Чек-лист для создания нового компонента
|
||||
- [ ] Главный компонент размещён в корне и назван по правилу PascalCase.
|
||||
- [ ] Создан файл стилей в папке `styles/`, имя в kebab-case, используется BEM.
|
||||
- [ ] Все классы применяются через `className={styles['component-name']}`.
|
||||
- [ ] Создана папка `locales/` с файлами `ru.json` и `en.json`.
|
||||
- [ ] Создан файл интерфейса пропсов в папке `types/`, даже если интерфейс пустой.
|
||||
- [ ] Создан файл `index.ts` с экспортом главного компонента и интерфейса.
|
||||
- [ ] Внутренние компоненты (если есть) размещены в папке `ui/`.
|
||||
- [ ] Все важные части кода документированы по TSDoc (см. раздел 16).
|
||||
- [ ] Остальные файлы (schemas, дополнительные типы, enum) добавлены только при необходимости.
|
||||
- [ ] Именование файлов и папок соответствует правилам (см. выше).
|
||||
- [ ] Нет неиспользуемого или невалидного кода.
|
||||
- [ ] Для компонентов с пропсами используется `React.memo`.
|
||||
- [ ] Для вычислений, передаваемых в пропсы, используется `useMemo`.
|
||||
- [ ] Для функций, передаваемых в пропсы, используется `useCallback`.
|
||||
- [ ] Все тексты вынесены в локализационные файлы и используются через i18n.
|
||||
- [ ] Новые namespace подключены в экземпляр i18n.
|
||||
@@ -1,68 +0,0 @@
|
||||
# Хуки (React Hooks)
|
||||
|
||||
> В проекте для создания пользовательских хуков используется только React (функциональные компоненты и хуки).
|
||||
> В этом разделе собраны основные правила и рекомендации по созданию и оформлению хуков. Следуйте этим принципам, чтобы обеспечить чистую архитектуру, переиспользуемость и единый стиль работы с хуками в проекте.
|
||||
|
||||
## Рекомендации по использованию сторонних хуков
|
||||
- Если есть возможность, используйте хуки Mantine в компонентах и кастомных хуках для работы с состоянием, темизацией, медиа-запросами и другими возможностями библиотеки.
|
||||
- Не дублируйте функциональность, уже реализованную в Mantine.
|
||||
|
||||
## Структура
|
||||
- Каждый хук размещается в отдельном файле с именем `use-<hook-name>.hook.ts` в папке `hooks/` на своём уровне абстракции согласно архитектуре проекта.
|
||||
- Имя хука — в стиле camelCase с префиксом `use` (например, `useTodoFilter`).
|
||||
- Для сложных возвращаемых структур использовать отдельные типы или интерфейсы, размещая их в папке `types/` на своём уровне абстракции.
|
||||
|
||||
## Именование
|
||||
- Соблюдайте [правила именования файлов и папок](#правила-именования-файлов-и-папок):
|
||||
- Файл хука — `use-<hook-name>.hook.ts` (kebab-case).
|
||||
- Имя хука — camelCase с префиксом `use`.
|
||||
|
||||
## Требования
|
||||
- Хук должен быть строго типизирован: все параметры, возвращаемые значения и внутренние переменные должны иметь явные типы.
|
||||
- Не хранить бизнес-логику, связанную с несколькими слоями — хук должен быть изолирован в рамках своего слоя/feature.
|
||||
- Не дублировать логику между хуками — общие части выносить в shared.
|
||||
- Не использовать side-effects вне useEffect/useLayoutEffect.
|
||||
- Для мемоизации возвращаемых значений и функций использовать useMemo и useCallback.
|
||||
- Не использовать устаревшие или неразрешённые паттерны React.
|
||||
|
||||
## Типизация
|
||||
- Всегда явно указывать типы для всех параметров, возвращаемых значений и состояния внутри хука.
|
||||
- Не используйте неявное приведение типов и не полагайтесь на автоматический вывод, если это может снизить читаемость или безопасность.
|
||||
|
||||
## Документирование
|
||||
- Документируйте только назначение хука (описание), строго по [правилам документирования кода](#правило-для-документирования-кода).
|
||||
|
||||
## Экспорт
|
||||
- Экспортируйте хук только именованным экспортом через `index.ts` слоя/компонента.
|
||||
|
||||
## Примеры
|
||||
|
||||
```ts
|
||||
import { useMemo } from 'react';
|
||||
import { TodoItem } from '../types/todo-item.interface';
|
||||
import { TodoStatus } from '../types/todo-status.enum';
|
||||
|
||||
/**
|
||||
* Хук фильтрации задач по статусу.
|
||||
*/
|
||||
export const useTodoFilter = (items: TodoItem[], filter: TodoStatus): TodoItem[] => {
|
||||
return useMemo(() => {
|
||||
if (filter === TodoStatus.ALL) return items;
|
||||
if (filter === TodoStatus.ACTIVE) return items.filter((t) => !t.completed);
|
||||
return items.filter((t) => t.completed);
|
||||
}, [items, filter]);
|
||||
};
|
||||
```
|
||||
|
||||
## Чек-лист
|
||||
|
||||
- [ ] Хук размещён в файле `use-<hook-name>.hook.ts` в папке `hooks/` на своём уровне абстракции согласно архитектуре проекта.
|
||||
- [ ] Именование файлов и сущностей соответствует [правилам именования файлов и папок](#правила-именования-файлов-и-папок).
|
||||
- [ ] Все параметры, возвращаемые значения и внутренние переменные строго типизированы.
|
||||
- [ ] Вся бизнес-логика изолирована в рамках слоя/feature.
|
||||
- [ ] Нет дублирования логики между хуками.
|
||||
- [ ] Для мемоизации используется useMemo/useCallback.
|
||||
- [ ] Не используются side-effects вне useEffect/useLayoutEffect.
|
||||
- [ ] Документировано только назначение хука (см. [правила документирования кода](#правило-для-документирования-кода)).
|
||||
- [ ] Нет неиспользуемого или невалидного кода.
|
||||
- [ ] Экспорт только именованный через индексный файл.
|
||||
@@ -1,124 +0,0 @@
|
||||
# Хуки API (React Hooks)
|
||||
|
||||
> В проекте для работы с API-хуками используется только React и библиотека SWR для получения данных (GET-запросы).
|
||||
> В этом разделе собраны основные правила и рекомендации по созданию и оформлению хуков для работы с API. Следуйте этим принципам, чтобы обеспечить чистую архитектуру, переиспользуемость и единый стиль работы с API-хуками в проекте.
|
||||
|
||||
## Описание и назначение API-хуков
|
||||
|
||||
API-хуки предназначены для получения данных с сервера (GET-запросы) и используются в компонентах или других хуках.
|
||||
В проекте для этого применяется библиотека SWR, которая обеспечивает кэширование, автоматическое обновление и удобную работу с асинхронными запросами.
|
||||
|
||||
**Fetcher** — это функция, которую использует SWR для выполнения запроса к API. В проекте fetcher обычно экспортируется из файла клиента (например, `backendFetcher` из `shared/api/backend/client.ts`) и инкапсулирует логику обращения к конкретному API-клиенту.
|
||||
|
||||
**API-клиент** — это отдельный модуль (папка), отвечающий за взаимодействие с конкретным внешним или внутренним API.
|
||||
API-клиент включает:
|
||||
- инициализацию экземпляра HTTP-клиента (например, Axios),
|
||||
- настройку базового URL, интерцепторов и общих обработчиков ошибок,
|
||||
- организацию всех сущностей и методов для работы с этим API (например, users, auth, orders и т.д.),
|
||||
- экспорт всех функций, типов и fetcher через индексные файлы.
|
||||
|
||||
Каждый API-клиент размещается в папке `src/shared/api/<client-name>/` и имеет собственную структуру согласно архитектуре проекта.
|
||||
|
||||
## Структура
|
||||
- Каждый API-хук размещается в отдельном файле с именем `use-<method-name>.hook-api.ts` в папке `hooks/api/<client-name>/` на своём уровне абстракции согласно архитектуре проекта.
|
||||
- Имя хука — в стиле camelCase с префиксом `use` (например, `useGetUser`).
|
||||
- Для сложных возвращаемых структур используйте отдельные типы или интерфейсы, размещая их в папке `types/` на своём уровне абстракции.
|
||||
|
||||
## Именование
|
||||
- Соблюдайте [правила именования файлов и папок](#правила-именования-файлов-и-папок):
|
||||
- Файл хука — `use-<method-name>.hook-api.ts` (kebab-case).
|
||||
- Имя хука — camelCase с префиксом `use`.
|
||||
|
||||
## Требования
|
||||
- Хук должен быть строго типизирован: все параметры, возвращаемые значения и внутренние переменные должны иметь явные типы.
|
||||
- Для получения данных используйте только SWR.
|
||||
- Не дублируйте логику между хуками — общие части выносите в shared.
|
||||
- Не используйте side-effects вне useEffect/useLayoutEffect.
|
||||
|
||||
## Типизация
|
||||
- Всегда явно указывайте типы для всех параметров, возвращаемых значений и состояния внутри хука.
|
||||
- Придерживайтесь [общих правил типизации проекта](#общие-правила-типизации).
|
||||
- Не используйте неявное приведение типов и не полагайтесь на автоматический вывод, если это может снизить читаемость или безопасность.
|
||||
|
||||
## Документирование
|
||||
- Документируйте только назначение хука (описание), строго по [правилам документирования кода](#правило-для-документирования-кода).
|
||||
|
||||
## Экспорт
|
||||
- Экспортируйте хук только именованным экспортом через `index.ts` слоя/компонента.
|
||||
|
||||
## Пример API хука
|
||||
|
||||
```ts
|
||||
// use-get-me.hook-api.ts
|
||||
import useSWR from 'swr';
|
||||
import { backendFetcher } from 'shared/api/backend/client';
|
||||
import { UserDto } from 'shared/api/backend/entities/users/get-me.api';
|
||||
|
||||
/**
|
||||
* Хук для получения информации о текущем пользователе.
|
||||
*/
|
||||
export const useGetMe = () => {
|
||||
const { data, error, isLoading } = useSWR<UserDto>('/users/me', backendFetcher);
|
||||
|
||||
return {
|
||||
data,
|
||||
error,
|
||||
isLoading,
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### Пример использования хука в компоненте
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import { useGetMe } from 'shared/hooks/api/backend/use-get-me.hook-api';
|
||||
|
||||
export const UserInfo: React.FC = () => {
|
||||
const { data, error, isLoading } = useGetMe();
|
||||
|
||||
if (isLoading) {
|
||||
return <div>Загрузка...</div>;
|
||||
}
|
||||
|
||||
if (error) {
|
||||
return <div>Ошибка загрузки данных</div>;
|
||||
}
|
||||
|
||||
if (!data) {
|
||||
return <div>Нет данных о пользователе</div>;
|
||||
}
|
||||
|
||||
return (
|
||||
<div>
|
||||
<div>Имя: {data.name}</div>
|
||||
<div>Email: {data.email}</div>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
## Чек-лист для создания API-хука
|
||||
|
||||
- [ ] Для каждого GET-запроса создан отдельный хук.
|
||||
- [ ] Хук размещён в `hooks/api/<client-name>/use-<method-name>.hook-api.ts` на своём уровне абстракции согласно архитектуре проекта.
|
||||
- [ ] Именование файлов и сущностей соответствует [правилам именования файлов и папок](#правила-именования-файлов-и-папок).
|
||||
- [ ] Используется SWR для получения данных.
|
||||
- [ ] Все параметры, возвращаемые значения и внутренние переменные строго типизированы.
|
||||
- [ ] Нет дублирования логики между хуками.
|
||||
- [ ] Не используются side-effects вне useEffect/useLayoutEffect.
|
||||
- [ ] Документировано только назначение хука (см. [правила документирования кода](#правило-для-документирования-кода)).
|
||||
- [ ] Нет неиспользуемого или невалидного кода.
|
||||
- [ ] Экспорт только именованный через индексный файл.
|
||||
|
||||
---
|
||||
|
||||
## Чек-лист для использования API-хука
|
||||
|
||||
- [ ] Импортируется только нужный хук через публичные экспорты (`index.ts`).
|
||||
- [ ] Использование хука строго по назначению (только для получения данных).
|
||||
- [ ] Если требуется получить данные через GET-запрос в компоненте — обязательно используется соответствующий API-хук.
|
||||
**Запрещено вызывать GET-методы API напрямую в компонентах, только через хуки.**
|
||||
- [ ] Обработка состояний загрузки, ошибки и данных реализована корректно.
|
||||
- [ ] Не происходит дублирования логики, связанной с получением данных.
|
||||
- [ ] Нет неиспользуемого или невалидного кода.
|
||||
@@ -1,242 +0,0 @@
|
||||
# API
|
||||
|
||||
> В этом разделе собраны основные правила и рекомендации по созданию, оформлению и использованию API-клиентов и функций для работы с сервером. Следуйте этим принципам, чтобы обеспечить единый стиль, безопасность и удобство поддержки API-слоя в проекте.
|
||||
|
||||
## Описание и назначение API-клиента
|
||||
|
||||
API-клиент — это модуль (папка), отвечающий за взаимодействие с конкретным внешним или внутренним API.
|
||||
В проекте для HTTP-запросов используется только Axios.
|
||||
API-клиент инкапсулирует:
|
||||
- инициализацию экземпляра Axios,
|
||||
- настройку базового URL, интерцепторов, обработчиков ошибок,
|
||||
- организацию всех сущностей и методов для работы с этим API (например, users, auth, orders и т.д.),
|
||||
- экспорт всех функций, типов и fetcher через индексные файлы.
|
||||
|
||||
Каждый API-клиент размещается в папке `src/shared/api/<client-name>/` и имеет собственную структуру согласно архитектуре проекта.
|
||||
|
||||
|
||||
## Использование методов API
|
||||
|
||||
- Все методы API должны использоваться строго внутри блока `try...catch`.
|
||||
- При вызове методов API всегда используйте полный путь, например:
|
||||
`await api.backend.createUser({ email, password });`
|
||||
- Запрещено вызывать методы API вне блока `try...catch` даже в тестах, утилитах и других вспомогательных функциях.
|
||||
|
||||
|
||||
## Структура клиента
|
||||
```text
|
||||
src/shared/api/backend/
|
||||
│
|
||||
├── client.ts
|
||||
├── index.ts
|
||||
└── entities/
|
||||
├── users/
|
||||
│ ├── get-me.api.ts
|
||||
│ ├── create-user.api.ts
|
||||
│ ├── update-user.api.ts
|
||||
│ └── index.ts
|
||||
├── auth/
|
||||
│ ├── login.api.ts
|
||||
│ ├── register.api.ts
|
||||
│ └── index.ts
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
## Описание ключевых элементов
|
||||
|
||||
- **client.ts**
|
||||
Экземпляр Axios с настройками, интерцепторами, экспортом fetcher для SWR.
|
||||
|
||||
- **index.ts**
|
||||
Главная точка экспорта: экспортирует client, fetcher, все сущности и их методы.
|
||||
|
||||
- **entities/**
|
||||
Папка для бизнес-сущностей (например, users, auth, orders и т.д.).
|
||||
|
||||
- **`<entity>/`**
|
||||
Папка для отдельной сущности. Имя — в kebab-case, отражает бизнес-область (например, users, auth).
|
||||
|
||||
- **`<operation>.api.ts`**
|
||||
Файл для каждой операции (CRUD, спец. действия).
|
||||
Внутри:
|
||||
- DTO (интерфейсы запроса/ответа)
|
||||
- Функция, реализующая запрос через client
|
||||
|
||||
- **index.ts (внутри `<entity>`/)**
|
||||
Экспортирует все методы и типы этой сущности.
|
||||
|
||||
- **index.ts (внутри entities/)**
|
||||
Экспортирует все сущности (users, auth и т.д.).
|
||||
|
||||
|
||||
## Именование
|
||||
|
||||
- Соблюдайте [правила именования файлов и папок](#правила-именования-файлов-и-папок):
|
||||
- Файл клиента — `client.ts`.
|
||||
- Файл функции — `<operation>-<entity>.api.ts` (например, `create-user.api.ts`).
|
||||
- DTO — в папке `dto/` (например, `create-user.dto.ts`).
|
||||
- Все функции и типы экспортируются через индексные файлы на каждом уровне (сущность, entities, клиент).
|
||||
|
||||
|
||||
## Требования
|
||||
|
||||
- Для каждого действия (CRUD, спец. действия) — отдельная функция и файл.
|
||||
- Все функции используют общий экземпляр Axios из `client.ts`.
|
||||
- Все функции строго типизированы (используются DTO).
|
||||
- DTO объявляется в отдельном файле в папке `dto/` перед функцией, которая его использует.
|
||||
- Для каждого GET метода обязательно должен быть создан API-хук.
|
||||
- Все API-хуки должны создаваться строго по [документации раздела "Хуки для API"](#хуки-для-api-api-hooks).
|
||||
|
||||
|
||||
## Типизация
|
||||
|
||||
- Все функции и DTO строго типизированы.
|
||||
- Все интерфейсы, типы и enum размещены в папке `types/` на своём уровне абстракции.
|
||||
- Все DTO размещены в папке `dto/` на своём уровне абстракции.
|
||||
- Придерживайтесь [общих правил типизации проекта](#общие-правила-типизации).
|
||||
|
||||
|
||||
## Документирование
|
||||
|
||||
- Документируйте только назначение функций и DTO.
|
||||
- В описании указывается только смысл функции/типа.
|
||||
|
||||
|
||||
## Экспорт
|
||||
|
||||
- Все функции и типы экспортируются через индексные файлы на каждом уровне (сущность, entities, клиент).
|
||||
|
||||
|
||||
## Примеры
|
||||
|
||||
### Пример клиента API
|
||||
|
||||
```ts
|
||||
// client.ts
|
||||
import axios, { AxiosInstance } from "axios";
|
||||
export { AxiosError, isAxiosError } from 'axios';
|
||||
export type { AxiosResponse } from 'axios';
|
||||
|
||||
/**
|
||||
* Экземпляр HTTP-клиента для работы с backend API.
|
||||
*/
|
||||
export const backendHttpClient: AxiosInstance = axios.create({
|
||||
baseURL: '/api',
|
||||
timeout: 10000,
|
||||
});
|
||||
|
||||
// Интерцептор запроса
|
||||
backendHttpClient.interceptors.request.use(
|
||||
(config) => {
|
||||
// Здесь можно добавить авторизационные заголовки или другую логику
|
||||
return config;
|
||||
},
|
||||
(error) => Promise.reject(error)
|
||||
);
|
||||
|
||||
// Интерцептор ответа
|
||||
backendHttpClient.interceptors.response.use(
|
||||
(response) => response,
|
||||
(error) => {
|
||||
// Здесь можно обработать ошибки (например, показать уведомление)
|
||||
return Promise.reject(error);
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
### Пример DTO
|
||||
|
||||
```ts
|
||||
// dto/create-user.dto.ts
|
||||
/**
|
||||
* DTO для создания пользователя.
|
||||
*/
|
||||
export interface CreateUserDto {
|
||||
/** Email пользователя. */
|
||||
email: string;
|
||||
/** Пароль пользователя. */
|
||||
password: string;
|
||||
}
|
||||
```
|
||||
|
||||
### Пример API-функции
|
||||
|
||||
```ts
|
||||
// create-user.api.ts
|
||||
import { backendHttpClient } from '../client';
|
||||
import { CreateUserDto } from './dto/create-user.dto';
|
||||
|
||||
/**
|
||||
* Создать пользователя.
|
||||
*/
|
||||
export const createUser = (data: CreateUserDto) => backendHttpClient.post('/users', data);
|
||||
```
|
||||
|
||||
### Пример index.ts (в папке сущности)
|
||||
|
||||
```ts
|
||||
export * from './create-user.api';
|
||||
export * from './get-user.api';
|
||||
```
|
||||
|
||||
### Пример использования API-функции в компоненте
|
||||
|
||||
```tsx
|
||||
import React, { useState } from 'react';
|
||||
import { api } from 'shared/api';
|
||||
|
||||
export const CreateUserForm: React.FC = () => {
|
||||
const [email, setEmail] = useState('');
|
||||
const [password, setPassword] = useState('');
|
||||
|
||||
const handleSubmit = async (e: React.FormEvent) => {
|
||||
e.preventDefault();
|
||||
try {
|
||||
await api.backend.createUser({ email, password });
|
||||
console.log('Пользователь создан!');
|
||||
} catch {
|
||||
console.log('Ошибка создания пользователя');
|
||||
}
|
||||
};
|
||||
|
||||
return (
|
||||
<form onSubmit={handleSubmit}>
|
||||
<input
|
||||
type="email"
|
||||
value={email}
|
||||
onChange={e => setEmail(e.target.value)}
|
||||
placeholder="Email"
|
||||
required
|
||||
/>
|
||||
<input
|
||||
type="password"
|
||||
value={password}
|
||||
onChange={e => setPassword(e.target.value)}
|
||||
placeholder="Пароль"
|
||||
required
|
||||
/>
|
||||
<button type="submit">Создать пользователя</button>
|
||||
</form>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
|
||||
## Чек-лист для создания клиента
|
||||
- [ ] Новый клиент размещён в `src/shared/api/<client-name>/`.
|
||||
- [ ] В корне клиента есть client.ts (экземпляр Axios) и index.ts (главный экспорт).
|
||||
- [ ] Все бизнес-сущности размещены в entities/, каждая — в отдельной папке.
|
||||
- [ ] Для каждой операции создан отдельный файл `<operation>`.api.ts с DTO и функцией.
|
||||
- [ ] DTO объявлен непосредственно перед функцией.
|
||||
- [ ] В каждой папке сущности есть свой index.ts для экспорта методов и типов.
|
||||
- [ ] В папке entities/ есть общий index.ts для экспорта всех сущностей.
|
||||
- [ ] Все экспорты организованы через индексные файлы.
|
||||
- [ ] Для каждого GET-метода создан отдельный SWR-хук (см. правила API-хуков).
|
||||
- [ ] Нет дублирования кода и неиспользуемых файлов.
|
||||
|
||||
## Чек-лист для использования API
|
||||
- [ ] Импортируется только нужный метод через публичные экспорты (index.ts).
|
||||
- [ ] Все вызовы API обёрнуты в try...catch.
|
||||
- [ ] Используются только строго типизированные методы.
|
||||
- [ ] Не происходит обращения к Axios напрямую — только через client.
|
||||
- [ ] Нет дублирования логики и неиспользуемого кода.
|
||||
@@ -1,21 +0,0 @@
|
||||
---
|
||||
title: Общие принципы
|
||||
---
|
||||
|
||||
# Общие принципы
|
||||
|
||||
## Стек технологий и библиотеки
|
||||
- Использовать **TypeScript** для всех файлов логики и компонентов.
|
||||
- Использовать **FSD (Feature-Sliced Design)**: разделять код на features, entities, processes, widgets, shared.
|
||||
- Использовать **React** (функциональные компоненты, хуки).
|
||||
- Использовать **Mantine UI** для UI-компонентов.
|
||||
- Использовать **Axios** в качестве клиента для работы с API.
|
||||
- Использовать **SWR** для data fetching (GET-запросы).
|
||||
- Использовать **Zustand** для глобального состояния.
|
||||
- Использовать **i18n** для локализации.
|
||||
- Использовать **Vitest** для тестирования.
|
||||
- Использовать **PostCSS модули** для стилизации.
|
||||
- Использовать **BEM** для именований классов в стилях
|
||||
- Использовать **Mobile First** подход для написания стилей.
|
||||
- Использовать **Context7** примеров использования библиотек.
|
||||
- Использовать **i18n** (i18next) для локализации всех пользовательских текстов.
|
||||
@@ -1,22 +0,0 @@
|
||||
---
|
||||
title: Архитектура
|
||||
---
|
||||
|
||||
# Архитектура
|
||||
|
||||
## Архитектура проекта
|
||||
В проекте используется FSD (Feature-Sliced Design) архитектура.
|
||||
|
||||
- **FSD-границы**
|
||||
- Не нарушать границы слоёв (например, feature не может импортировать из widgets).
|
||||
- Бизнес-логика должна быть вынесена в хуки или сервисы.
|
||||
- **Импорты**
|
||||
- Внутри слоя — относительные импорты.
|
||||
- Между слоями — абсолютные импорты.
|
||||
- **Требования**
|
||||
- Не смешивать логику разных слоёв.
|
||||
- Не хранить бизнес-логику в UI-компонентах.
|
||||
- **Именование**
|
||||
- Файлы и папки kebab-case.
|
||||
|
||||
---
|
||||
@@ -1,74 +0,0 @@
|
||||
---
|
||||
title: Стиль кода
|
||||
---
|
||||
|
||||
# Стиль кода
|
||||
|
||||
## Отступы
|
||||
|
||||
Используем 2 пробела для отступов во всём проекте. Не используем табы.
|
||||
|
||||
|
||||
## Кавычки
|
||||
|
||||
Используем **одинарные кавычки** для строк в JavaScript/TypeScript, и **двойные кавычки** для атрибутов в JSX/TSX.
|
||||
|
||||
**Пример:**
|
||||
|
||||
```ts
|
||||
// JavaScript/TypeScript
|
||||
const message = 'Привет, мир!';
|
||||
const name = 'ProjectName';
|
||||
```
|
||||
|
||||
```tsx
|
||||
// JSX/TSX
|
||||
<input type="text" placeholder="Введите имя" />
|
||||
<button title="Сохранить">Сохранить</button>
|
||||
```
|
||||
|
||||
## Строгая типизация
|
||||
|
||||
всегда указывать типы для пропсов, возвращаемых значений, параметров функций.
|
||||
|
||||
## Ранние возвраты
|
||||
|
||||
(early return) для повышения читаемости.
|
||||
|
||||
## Мемоизация
|
||||
|
||||
Старайся оптимизировать код если это возможно.
|
||||
|
||||
## Документирование
|
||||
|
||||
Документируем ТОЛЬКО ОПИСАНИЕ (функций, компонентов, типов и их полей).
|
||||
|
||||
## any, unknown
|
||||
|
||||
запрещено использовать без крайней необходимости.
|
||||
|
||||
## Классы в TSX
|
||||
|
||||
Для стилизации компонентов используем CSS-модули и методологию BEM. Классы подключаются через объект стилей, импортированный из соответствующего `.module.css` файла.
|
||||
|
||||
> Объект стилей всегда импортируется с именем `s` (сокращённо от style), а не `styles`.
|
||||
|
||||
**Пример:**
|
||||
|
||||
```tsx
|
||||
import s from './my-component.module.css';
|
||||
|
||||
export const MyComponent = () => (
|
||||
<div className={s['my-component']}>
|
||||
<button className={s['my-component__button']}>Кнопка</button>
|
||||
<span className={s['my-component__text']}>Текст</span>
|
||||
<button className={s['my-component__button'] + ' ' + s._active}>
|
||||
Активная кнопка
|
||||
</button>
|
||||
</div>
|
||||
);
|
||||
```
|
||||
|
||||
- Имя класса всегда берётся из объекта `s`.
|
||||
- Для модификаторов используется отдельный класс с нижним подчёркиванием (например, `s._active`).
|
||||
- Не используйте строковые литералы с классами напрямую — только через объект `s`.
|
||||
@@ -1,18 +0,0 @@
|
||||
---
|
||||
title: Именование
|
||||
---
|
||||
|
||||
# Именование
|
||||
|
||||
## Именование файлов и папок
|
||||
- Папка компонента: kebab-case, совпадает с названием компонента, пример: `component-name`.
|
||||
- React-компонент: kebab-case, совпадает с названием компонента, пример: `component-name.tsx`.
|
||||
- Стили: kebab-case, шаблон: `<style-name>.module.css`, пример: `style-name.module.css`.
|
||||
- Интерфейсы: kebab-case, шаблон: `<interface-name>.interface.ts`, пример: `interface-name.interface.ts`.
|
||||
- Типы: kebab-case, шаблон: `<type-name>.type.ts`, пример: `type-name.type.ts`.
|
||||
- Enum: kebab-case, шаблон: `<enum-name>.enum.ts`, пример: `enum-name.enum.ts`.
|
||||
- Схемы: kebab-case, шаблон: `<schema-name>.schema.ts`, пример: `schema-name.schema.ts`.
|
||||
- Локализация: kebab-case, пример: `ru.json`, `en.json`.
|
||||
- Утилиты: kebab-case, шаблон: `<util-name>.util.ts`, пример: `util-name.util.ts`
|
||||
- React Hooks: kebab-case, шаблон: `use-<hook-name>.hook.ts`, пример: `use-hook-name.hook.ts`
|
||||
- Хранилища состояния компонента: kebab-case, шаблон: `<store-name>.store.ts`, пример: `store-name.store.ts`
|
||||
@@ -1,69 +0,0 @@
|
||||
---
|
||||
title: Документирование
|
||||
---
|
||||
|
||||
# Документирование
|
||||
|
||||
## Правило для документирования кода
|
||||
|
||||
- Документировать разрешено только описание (назначение) функций, компонентов, типов, интерфейсов, enum и их полей.
|
||||
- Строго запрещено документировать параметры, возвращаемые значения, типы пропсов, аргументы, возвращаемые значения функций, компоненты, хуки и т.д.
|
||||
- В интерфейсах, типах и enum разрешено документировать только смысл (описание) каждого поля или значения.
|
||||
- В React-компонентах, функциях, хранилищах, схемах, утилитах разрешено документировать только назначение (описание), без детализации параметров и возвращаемых значений.
|
||||
- Описание должно быть кратким, информативным и реально помогать понять структуру и бизнес-логику.
|
||||
- Не допускается избыточная или дублирующая очевидное документация.
|
||||
- В конце описания всегда ставить точку.
|
||||
|
||||
**Примеры правильного документирования**
|
||||
```tsx
|
||||
/**
|
||||
* Список задач пользователя.
|
||||
*/
|
||||
export const TodoList = memo(() => { ... });
|
||||
|
||||
/**
|
||||
* Интерфейс задачи.
|
||||
*/
|
||||
export interface TodoItem {
|
||||
/** Уникальный идентификатор задачи. */
|
||||
id: string;
|
||||
/** Текст задачи. */
|
||||
text: string;
|
||||
/** Статус выполнения задачи. */
|
||||
completed: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Перечисление фильтров задач.
|
||||
*/
|
||||
export enum TodoFilter {
|
||||
/** Все задачи. */
|
||||
All = 'all',
|
||||
/** Только активные задачи. */
|
||||
Active = 'active',
|
||||
/** Только выполненные задачи. */
|
||||
Completed = 'completed',
|
||||
}
|
||||
```
|
||||
|
||||
**Примеры неправильного документирования**
|
||||
```ts
|
||||
// ❌ Не нужно:/
|
||||
/**
|
||||
* @param id - идентификатор задачи
|
||||
* @returns объект задачи
|
||||
*/
|
||||
|
||||
// ❌ Не нужно:/
|
||||
/**
|
||||
* @param props - пропсы компонента
|
||||
* @returns JSX.Element
|
||||
*/
|
||||
|
||||
// ❌ Не нужно:/
|
||||
/**
|
||||
* id — идентификатор задачи
|
||||
* text — текст задачи
|
||||
* completed — статус выполнения
|
||||
*/
|
||||
```
|
||||
@@ -1,187 +0,0 @@
|
||||
---
|
||||
title: Типизация
|
||||
---
|
||||
|
||||
# Типизация
|
||||
|
||||
## Общие правила типизации
|
||||
|
||||
> Данный раздел определяет единые требования к типизации для всего проекта. Соблюдение этих правил обеспечивает читаемость, предсказуемость и безопасность кода.
|
||||
|
||||
- Использовать только строгую типизацию TypeScript для всех файлов логики, компонентов, хуков, API, сторов и утилит.
|
||||
- Всегда явно указывать типы для:
|
||||
- Пропсов компонентов
|
||||
- Параметров функций и методов
|
||||
- Возвращаемых значений функций и методов
|
||||
- Всех переменных состояния (в том числе в store)
|
||||
- Всех значимых переменных и констант, если их тип не очевиден из присваивания
|
||||
- Не использовать `any` и `unknown` без крайней необходимости. Если использование неизбежно — обязательно добавить комментарий с обоснованием.
|
||||
- Все интерфейсы, типы и enum всегда размещать в папке `types/` на своём уровне абстракции (например, `features/todo/types/`).
|
||||
- Для DTO всегда использовать отдельную папку `dto/` на уровне сущности или слоя.
|
||||
- Для сложных структур использовать отдельные интерфейсы или типы, размещая их в соответствующих файлах в папке `types/`.
|
||||
- Для DTO, enum, схем и других сущностей — всегда создавать отдельные типы/интерфейсы с осмысленными именами.
|
||||
- Ключи enum всегда писать ЗАГЛАВНЫМИ_БУКВАМИ (SCREAMING_SNAKE_CASE).
|
||||
- Не использовать неявное приведение типов и не полагаться на автоматический вывод, если это может снизить читаемость или безопасность.
|
||||
- Для массивов и объектов всегда указывать тип элементов/ключей.
|
||||
- Для возвращаемых значений асинхронных функций всегда указывать тип Promise.
|
||||
- Типизацию коллбеков и функций, передаваемых в пропсы, указывать инлайн, не выносить в отдельные типы.
|
||||
- Для типизации внешних библиотек использовать официальные типы или создавать собственные декларации при необходимости.
|
||||
- Не использовать устаревшие или не рекомендуемые паттерны типизации (например, `Function`, `Object`, `{}`).
|
||||
---
|
||||
|
||||
### Примеры
|
||||
|
||||
#### Интерфейс и типы для сущностей (всегда в папке types/)
|
||||
|
||||
```ts
|
||||
// features/todo/types/todo-item.interface.ts
|
||||
|
||||
/**
|
||||
* Интерфейс задачи.
|
||||
*/
|
||||
export interface TodoItem {
|
||||
/** Уникальный идентификатор задачи. */
|
||||
id: string;
|
||||
/** Текст задачи. */
|
||||
text: string;
|
||||
/** Статус выполнения задачи. */
|
||||
completed: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
#### Типизация enum (всегда в папке types/)
|
||||
|
||||
```ts
|
||||
// features/todo/types/todo-status.enum.ts
|
||||
|
||||
/**
|
||||
* Перечисление статусов задачи.
|
||||
*/
|
||||
export enum TodoStatus {
|
||||
/** Активная задача. */
|
||||
ACTIVE = 'active',
|
||||
/** Выполненная задача. */
|
||||
COMPLETED = 'completed',
|
||||
}
|
||||
```
|
||||
|
||||
#### Типизация пропсов компонента
|
||||
|
||||
```ts
|
||||
import { FC, memo } from 'react';
|
||||
import { TodoItem } from './types/todo-item.interface';
|
||||
|
||||
/**
|
||||
* Список задач.
|
||||
*/
|
||||
export interface TodoListProps {
|
||||
/** Массив задач. */
|
||||
items: TodoItem[];
|
||||
}
|
||||
|
||||
export const TodoList: FC<TodoListProps> = memo(({ items }) => (
|
||||
<ul>
|
||||
{items.map((item) => (
|
||||
<li key={item.id}>{item.text}</li>
|
||||
))}
|
||||
</ul>
|
||||
));
|
||||
```
|
||||
|
||||
#### Типизация функций и коллбеков (инлайн)
|
||||
|
||||
```ts
|
||||
/**
|
||||
* Функция фильтрации задач.
|
||||
*/
|
||||
export const getCompletedTodos = (items: TodoItem[]): TodoItem[] => {
|
||||
return items.filter((t) => t.completed);
|
||||
};
|
||||
|
||||
/**
|
||||
* Колбэк для обработки клика (инлайн).
|
||||
*/
|
||||
const handleClick = (id: string): void => {
|
||||
console.log('Clicked:', id);
|
||||
};
|
||||
```
|
||||
|
||||
#### Типизация асинхронных функций
|
||||
|
||||
```ts
|
||||
/**
|
||||
* Получить задачи с сервера.
|
||||
*/
|
||||
export const fetchTodos = async (): Promise<TodoItem[]> => {
|
||||
const response = await fetch('/api/todos');
|
||||
return response.json();
|
||||
};
|
||||
```
|
||||
|
||||
#### Типизация состояния в store (интерфейс в types/)
|
||||
|
||||
```ts
|
||||
// features/todo/types/todo-store.interface.ts
|
||||
|
||||
/**
|
||||
* Состояние хранилища задач.
|
||||
*/
|
||||
export interface TodoStoreState {
|
||||
/** Массив задач. */
|
||||
items: TodoItem[];
|
||||
/** Добавить задачу. */
|
||||
addTodo: (item: TodoItem) => void;
|
||||
/** Удалить задачу. */
|
||||
removeTodo: (id: string) => void;
|
||||
}
|
||||
```
|
||||
|
||||
#### Типизация DTO (всегда в папке dto/)
|
||||
|
||||
```ts
|
||||
// features/todo/dto/create-todo.dto.ts
|
||||
|
||||
/**
|
||||
* DTO для создания задачи.
|
||||
*/
|
||||
export interface CreateTodoDto {
|
||||
/** Текст задачи. */
|
||||
text: string;
|
||||
}
|
||||
|
||||
// features/todo/dto/todo-response.dto.ts
|
||||
|
||||
/**
|
||||
* DTO ответа сервера.
|
||||
*/
|
||||
export interface TodoResponseDto {
|
||||
/** Созданная задача. */
|
||||
todo: TodoItem;
|
||||
}
|
||||
```
|
||||
|
||||
#### Типизация внешних библиотек
|
||||
|
||||
```ts
|
||||
import type { AxiosResponse } from 'axios';
|
||||
|
||||
export const getData = async (): Promise<AxiosResponse<TodoItem[]>> => {
|
||||
// ...
|
||||
};
|
||||
```
|
||||
### Чек-лист проверки типизации
|
||||
|
||||
- [ ] Все пропсы компонентов явно типизированы через интерфейс или тип в папке `types/`.
|
||||
- [ ] Все параметры и возвращаемые значения функций и методов явно типизированы.
|
||||
- [ ] Все переменные состояния (в том числе в store) имеют явные типы.
|
||||
- [ ] Все интерфейсы, типы и enum размещены в папке `types/` на своём уровне абстракции.
|
||||
- [ ] Ключи всех enum написаны ЗАГЛАВНЫМИ_БУКВАМИ (SCREAMING_SNAKE_CASE).
|
||||
- [ ] Все DTO размещены в папке `dto/` на своём уровне абстракции.
|
||||
- [ ] Не используется `any` и `unknown` без крайней необходимости и поясняющего комментария.
|
||||
- [ ] Для сложных структур используются отдельные интерфейсы или типы.
|
||||
- [ ] Для массивов и объектов указан тип элементов/ключей.
|
||||
- [ ] Для асинхронных функций указан тип Promise с конкретным типом результата.
|
||||
- [ ] Типы коллбеков и функций, передаваемых в пропсы, указаны инлайн.
|
||||
- [ ] Не используются устаревшие типы (`Function`, `Object`, `{}`).
|
||||
- [ ] Для внешних библиотек используются официальные типы или собственные декларации.
|
||||
- [ ] Нет неявного приведения типов, все типы читаемы и прозрачны.
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
title: Локализация
|
||||
---
|
||||
|
||||
# Локализация
|
||||
|
||||
## Правила использования локализации
|
||||
|
||||
- Все пользовательские тексты должны быть вынесены в локализационные файлы.
|
||||
- Для каждого компонента создавать папку `locales/` с файлами `ru.json`, `en.json` и т.д.
|
||||
- Новые namespace обязательно регистрировать в экземпляре i18n (см. `app/i18n.ts`).
|
||||
- В коде использовать только функцию перевода из i18n, не использовать "жёстко" прописанные строки.
|
||||
94
README.md
94
README.md
@@ -1,69 +1,53 @@
|
||||
# NextJS Style Guide
|
||||
# Style Guide
|
||||
|
||||
Соглашения по разработке Next.js проектов: архитектура и слои приложения, структура кода, организация модулей, стилизация, типизация и инфраструктура.
|
||||
Репозиторий с правилами и стандартами фронтенд-разработки. Исходники документации собираются в разные форматы под разные фреймворки.
|
||||
|
||||
## Использование
|
||||
## Структура
|
||||
|
||||
**Для AI-агентов:**
|
||||
```text
|
||||
src/ # Исходники — только .md файлы
|
||||
├── base/ # Общие правила (не поставляется отдельно)
|
||||
│ ├── basics/ # Базовые: стиль кода, именование, типизация
|
||||
│ ├── applied/ # Прикладные: компоненты, стили, хуки, API
|
||||
│ └── triggers/ # Триггеры: создание компонента, стилизация и т.д.
|
||||
│
|
||||
└── nextjs/ # Next.js — самостоятельная единица
|
||||
├── applied/ # Next.js-специфичные: page-level, project-structure
|
||||
├── triggers/ # Next.js-специфичные триггеры: create-page, create-layout
|
||||
├── DEVELOP.md # Точка входа для агента-разработчика
|
||||
└── REVIEW.md # Точка входа для агента-ревьювера
|
||||
|
||||
- [llms.txt](/llms.txt) — Карта разделов, оглавление со ссылками на разделы.
|
||||
- [llms-full.txt](/llms-full.txt) — Вся документация одним файлом.
|
||||
scripts/ # Скрипты и манифесты сборки
|
||||
├── build-ai.js # Скрипт сборки
|
||||
└── nextjs.build.js # Манифест: какие файлы, куда, как называются
|
||||
|
||||
**Для проекта:**
|
||||
dist/ # Собранные версии (gitignore)
|
||||
├── ai/{framework}/ # Для AI-агентов
|
||||
└── vitepress/{framework}/ # Для людей (планируется)
|
||||
```
|
||||
|
||||
- [nextjs-style-guide.zip](/nextjs-style-guide.zip) — Набор Markdown-файлов для распаковки в `./ai/nextjs-style-guide/` или другую папку проекта.
|
||||
## Сборка
|
||||
|
||||
## Структура документации
|
||||
```bash
|
||||
npm run build:ai # Собрать все фреймворки
|
||||
```
|
||||
|
||||
### Workflow
|
||||
## Манифест
|
||||
|
||||
**Что делать и в каком порядке** — пошаговые инструкции.
|
||||
Каждый фреймворк имеет манифест `scripts/{framework}.build.js`. Ключ — путь в выходной папке, значение — путь исходника в `src/`.
|
||||
|
||||
| Раздел | Отвечает на вопрос |
|
||||
|--------|-------------------|
|
||||
| Начало работы | Что нужно знать перед началом разработки? |
|
||||
| Создание проекта | Как начать новый проект? |
|
||||
| Генерация кода | Какие модули должны генерироваться из шаблонов? |
|
||||
| Добавление страницы | Как добавить новую страницу в проект? |
|
||||
| Добавление UI-модуля | Как создать компонент, бизнес-модуль, виджет или layout? |
|
||||
| Стилизация | Как стилизовать компоненты в проекте? |
|
||||
| Получение данных | Как получать данные с сервера? |
|
||||
| Управление состоянием | Как работать с состоянием? |
|
||||
| Локализация | Как добавлять переводы и подключать локализацию? |
|
||||
Скрипт только копирует файлы по манифесту. Никакой генерации.
|
||||
|
||||
### Базовые правила
|
||||
|
||||
**Каким должен быть код** — стандарты, не привязанные к конкретной технологии.
|
||||
|
||||
| Раздел | Отвечает на вопрос |
|
||||
|--------|-------------------|
|
||||
| Технологии и библиотеки | Какой стек используем? |
|
||||
| Архитектура | Как устроены слои SLM, зависимости, публичный API? |
|
||||
| Стиль кода | Как оформлять код: отступы, кавычки, импорты, early return? |
|
||||
| Именование | Как называть файлы, переменные, компоненты, хуки? |
|
||||
| Документирование | Как писать JSDoc: что документировать, а что нет? |
|
||||
| Типизация | Как типизировать: type vs interface, any/unknown? |
|
||||
|
||||
### Прикладные разделы
|
||||
|
||||
**Как это настроить и использовать** — конфигурация, структура и примеры кода для конкретных областей.
|
||||
|
||||
| Раздел | Отвечает на вопрос |
|
||||
|--------|-------------------|
|
||||
| Настройка VS Code | Как настроить редактор для проекта? |
|
||||
| Структура проекта | Как организованы папки и файлы по SLM? |
|
||||
| Компоненты | Как устроен компонент: файлы, пропсы, clsx? |
|
||||
| Page-level компоненты | Как описывать layout, page, loading, error, not-found? |
|
||||
| Шаблоны и генерация кода | Как работают шаблоны, синтаксис и инструменты генерации? |
|
||||
| Стили | Как писать CSS: PostCSS Modules, вложенность, медиа, токены? |
|
||||
| Изображения | _(не заполнен)_ |
|
||||
| SVG-спрайты | _(не заполнен)_ |
|
||||
| Видео | _(не заполнен)_ |
|
||||
| API | _(не заполнен)_ |
|
||||
| Stores | _(не заполнен)_ |
|
||||
| Хуки | _(не заполнен)_ |
|
||||
| Шрифты | _(не заполнен)_ |
|
||||
| Локализация | _(не заполнен)_ |
|
||||
## Добавление раздела
|
||||
|
||||
1. Создать `.md` в `src/base/` (общий) или `src/{framework}/` (специфичный).
|
||||
2. Добавить frontmatter: `title`, `scope`, `keywords`, `when`.
|
||||
3. Добавить путь в манифест `scripts/{framework}.build.js`.
|
||||
4. Обновить точку входа (`DEVELOP.md` и/или `REVIEW.md`).
|
||||
5. `npm run build:ai`.
|
||||
|
||||
## Добавление фреймворка
|
||||
|
||||
1. Создать `src/{framework}/` с `.md` файлами и точками входа.
|
||||
2. Создать `scripts/{framework}.build.js`.
|
||||
3. `npm run build:ai`.
|
||||
|
||||
@@ -1,78 +0,0 @@
|
||||
---
|
||||
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'
|
||||
```
|
||||
@@ -1,80 +0,0 @@
|
||||
---
|
||||
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).
|
||||
@@ -1,71 +0,0 @@
|
||||
---
|
||||
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,108 +0,0 @@
|
||||
---
|
||||
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`.
|
||||
@@ -1,55 +0,0 @@
|
||||
---
|
||||
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);
|
||||
}
|
||||
```
|
||||
@@ -1,98 +0,0 @@
|
||||
---
|
||||
title: Архитектура
|
||||
---
|
||||
|
||||
# SLM Design
|
||||
Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.
|
||||
|
||||
## Преимущества
|
||||
|
||||
### Вертикальная организация домена
|
||||
|
||||
Бизнес-домен не разбивается по техническим слоям — сценарии, сущности, типы и UI живут в одном модуле. Это сокращает время навигации и упрощает сопровождение: все изменения домена локализованы.
|
||||
|
||||
### Dependency Injection без фреймворков
|
||||
|
||||
Cross-domain зависимости в бизнес-слое реализуются через фабрики — модуль декларирует что ему нужно, а точка использования предоставляет зависимости. Домены изолированы без DI-контейнеров, провайдеров и шин событий.
|
||||
|
||||
### Разделение ответственности без перегрузки слоёв
|
||||
|
||||
Сервисы приложения (`infrastructure/`), UI-кит (`ui/`) и общие ресурсы (`shared/`) — три разных слоя с разной природой. Ни один слой не превращается в свалку разнородного кода.
|
||||
|
||||
### Горизонтальная инкапсуляция
|
||||
|
||||
Вложенные модули (`parts/`) и направление зависимостей позволяют нескольким разработчикам работать над одной областью приложения параллельно, не затрагивая код друг друга.
|
||||
|
||||
### Колокация по умолчанию
|
||||
|
||||
Код начинает жизнь рядом с местом использования и поднимается в общие слои только при реальной потребности. Глобальные слои не засоряются преждевременными абстракциями.
|
||||
|
||||
### Явное разделение каркаса и контента
|
||||
|
||||
Каркас группы маршрутов (`layouts/`) и контент конкретной страницы (`screens/`) — независимые слои с собственной ответственностью.
|
||||
|
||||
### Масштабирование через группировку
|
||||
|
||||
При росте проекта слои не теряют структуру — модули группируются по естественным признакам: бизнес-домены по субдоменам, страницы по разделам, UI-компоненты по уровню абстракции (примитивы и композиции).
|
||||
|
||||
## Происхождение
|
||||
|
||||
SLM Design вырос на основе:
|
||||
|
||||
- **Feature-Sliced Design** — слоистая структура, публичный API модуля, направление зависимостей
|
||||
- **Vertical Slice Architecture** — модуль как вертикальный срез, содержащий всё необходимое
|
||||
- **Screaming Architecture** — структура проекта «кричит» о назначении: открыл `business/auth` — видишь авторизацию
|
||||
- **Colocation Principle** — код живёт рядом с местом использования
|
||||
|
||||
## Пример структуры проекта
|
||||
|
||||
```text
|
||||
src/
|
||||
├── app/
|
||||
│
|
||||
├── layouts/
|
||||
│ ├── main/
|
||||
│ └── dashboard/
|
||||
│
|
||||
├── screens/
|
||||
│ ├── home/
|
||||
│ ├── products/
|
||||
│ ├── product-detail/
|
||||
│ └── about/
|
||||
│
|
||||
├── widgets/
|
||||
│ ├── page-heading/
|
||||
│ ├── hero-section/
|
||||
│ └── promo-banner/
|
||||
│
|
||||
├── business/
|
||||
│ ├── auth/
|
||||
│ ├── catalog/
|
||||
│ ├── orders/
|
||||
│ └── chat/
|
||||
│
|
||||
├── infrastructure/
|
||||
│ ├── theme/
|
||||
│ ├── i18n/
|
||||
│ ├── backend-api/
|
||||
│ └── logger/
|
||||
│
|
||||
├── ui/
|
||||
│ ├── button/
|
||||
│ ├── input/
|
||||
│ ├── modal/
|
||||
│ ├── toast/
|
||||
│ └── dropdown/
|
||||
│
|
||||
└── shared/
|
||||
├── lib/
|
||||
├── types/
|
||||
└── styles/
|
||||
```
|
||||
|
||||
## Принципы
|
||||
|
||||
- **Домен — единое целое.** Всё, что относится к домену, живёт в одном модуле.
|
||||
- **Колокация.** Код рождается рядом с местом использования и поднимается только при необходимости.
|
||||
- **Зависимости однонаправлены.** Импорты только сверху вниз, только через публичный API.
|
||||
- **Архитектура — каркас, не клетка.** Правила фиксируют направление зависимостей и структуру модуля, остальное определяет команда.
|
||||
@@ -1,252 +0,0 @@
|
||||
---
|
||||
title: Слои
|
||||
---
|
||||
|
||||
# Слои
|
||||
|
||||
Слои SLM: назначение, классификация, направление зависимостей, правила.
|
||||
|
||||
## Определение
|
||||
|
||||
**Слой — уровень организации кода внутри `src/`. Каждый слой отвечает за свою область (каркас страницы, бизнес-логика, UI-кит) и задаёт правила для кода внутри: направление импортов, именование, допустимые связи между модулями.**
|
||||
|
||||
## Группы слоёв
|
||||
|
||||
Слои делятся на три группы:
|
||||
|
||||
| Группа | Слои | Описание |
|
||||
|--------|------|----------|
|
||||
| Композиция | `app`, `layouts`, `screens`, `widgets` | Собирают интерфейс из готовых блоков: маршруты, каркасы, страницы |
|
||||
| Ядро | `business`, `infrastructure`, `ui` | Реализация продукта: бизнес-домены, техсервисы, UI-кит |
|
||||
| Фундамент | `shared` | Общие ресурсы: утилиты, хелперы, стили, конфиги |
|
||||
|
||||
## Направление зависимостей
|
||||
|
||||
Любой импорт между модулями — только через публичный API.
|
||||
|
||||
```
|
||||
app → [ layouts | screens ] → widgets → business → infrastructure → ui → shared
|
||||
```
|
||||
|
||||
- `layouts` и `screens` — параллельные слои, не импортируют друг друга
|
||||
- Модули одного слоя в группе «Композиция» изолированы друг от друга
|
||||
- Модули одного слоя `infrastructure` и `ui` могут импортировать друг друга через публичный API
|
||||
- Модули `business` — cross-domain зависимости по коду через фабрику, `import type` напрямую
|
||||
- Импорт типов (`import type`) в «Ядре» разрешён в обоих направлениях
|
||||
|
||||
|
||||
## Слой App
|
||||
|
||||
Точка входа приложения. Отвечает за запуск, роутинг и композицию маршрутов из layout и screen.
|
||||
|
||||
В отличие от остальных слоёв, `app/` не содержит модулей SLM. Здесь живут только инфраструктурные файлы, которые не могут быть никаким другим слоем: файлы фреймворка роутинга, точка запуска и код инициализации.
|
||||
|
||||
### Требования
|
||||
|
||||
- Не содержит модулей SLM — только файлы фреймворка, роутинг, инициализация
|
||||
- Содержит: файлы маршрутов, bootstrap, обработку ошибок верхнего уровня (404, error boundary), подключение глобальных стилей и ассетов
|
||||
- Провайдеры и гарды — только подключает готовые из нижних слоёв, не реализует
|
||||
- Не содержит бизнес-логику, UI-компоненты, хуки, сторы, сервисы
|
||||
- Никем не импортируется
|
||||
|
||||
## Слой Layouts
|
||||
|
||||
Каркас страницы: общие элементы, одинаковые для группы маршрутов (header, footer, sidebar).
|
||||
|
||||
```text
|
||||
src/layouts/
|
||||
├── main/
|
||||
├── dashboard/
|
||||
└── auth/
|
||||
```
|
||||
|
||||
### Требования
|
||||
|
||||
- Содержит только модули
|
||||
- Не содержит бизнес-логику
|
||||
- Контекстно-зависимые блоки принимает через пропсы от `app`, не импортирует напрямую
|
||||
|
||||
## Слой Screens
|
||||
|
||||
Контент конкретной страницы: собирает её из модулей нижних слоёв.
|
||||
|
||||
```text
|
||||
src/screens/
|
||||
├── home/
|
||||
├── products/
|
||||
├── product-detail/
|
||||
├── about/
|
||||
└── contacts/
|
||||
```
|
||||
|
||||
Когда количество страниц затрудняет навигацию — вводится группировка по разделам. Группа — папка для организации, не модуль (без `index.ts`).
|
||||
|
||||
```text
|
||||
src/screens/
|
||||
├── shop/
|
||||
│ ├── home/
|
||||
│ ├── products/
|
||||
│ ├── product-detail/
|
||||
│ └── cart/
|
||||
├── account/
|
||||
│ ├── profile/
|
||||
│ ├── settings/
|
||||
│ └── order-history/
|
||||
└── info/
|
||||
├── about/
|
||||
├── contacts/
|
||||
└── faq/
|
||||
```
|
||||
|
||||
### Требования
|
||||
|
||||
- Содержит только модули
|
||||
- Не содержит бизнес-логику
|
||||
- Локальные одноразовые секции живут внутри screen-модуля, не выносятся в `widgets`/`business`
|
||||
|
||||
## Слой Widgets
|
||||
|
||||
Составной блок интерфейса, который компонует модули ядра, но не принадлежит конкретному бизнес-домену. Widget появляется когда блок используется в нескольких screens или layouts.
|
||||
|
||||
Если блок принадлежит домену — он живёт в `business/{area}/`, даже если переиспользуется. Если блок нужен только в одном месте — это `screens/{name}/parts/` или `layouts/{name}/parts/`, а не widget.
|
||||
|
||||
```text
|
||||
src/widgets/
|
||||
├── page-heading/
|
||||
├── hero-section/
|
||||
├── onboarding-checklist/
|
||||
├── promo-banner/
|
||||
└── error-boundary/
|
||||
```
|
||||
|
||||
### Требования
|
||||
|
||||
- Не принадлежит конкретному бизнес-домену. Если блок доменный — он живёт в `business/`
|
||||
- Используется в нескольких screens или layouts
|
||||
|
||||
## Слой Business
|
||||
|
||||
Бизнес-домены приложения: auth, catalog, orders, checkout, chat. Каждый домен — отдельный модуль со своими типами, логикой, UI и сервисами.
|
||||
|
||||
Слой входит в группу «Ядро». Импортирует `infrastructure/`, `ui/`, `shared/`. Cross-domain зависимости по коду реализуются через фабрику. `import type` между доменами разрешён напрямую.
|
||||
|
||||
Business объединяет то, что в FSD разделено на `features` и `entities`: пользовательские сценарии и бизнес-сущности живут вместе, внутри одного домена. Внутри домена сегменты разделяют ответственность: `types/` — доменная модель, `hooks/` и `services/` — сценарии и логика, `mappers/` — трансформация данных, `parts/` — составные блоки.
|
||||
|
||||
```text
|
||||
src/business/
|
||||
├── auth/
|
||||
├── catalog/
|
||||
├── orders/
|
||||
├── checkout/
|
||||
└── chat/
|
||||
```
|
||||
|
||||
Когда количество доменов затрудняет навигацию — вводится группировка по субдоменам. Группа — папка для организации, не модуль (без `index.ts`).
|
||||
|
||||
```text
|
||||
src/business/
|
||||
├── commerce/
|
||||
│ ├── catalog/
|
||||
│ ├── cart/
|
||||
│ ├── orders/
|
||||
│ └── checkout/
|
||||
└── communication/
|
||||
├── chat/
|
||||
└── notifications/
|
||||
```
|
||||
|
||||
### Требования
|
||||
|
||||
- Один модуль = один бизнес-домен
|
||||
- Циклические зависимости между доменами запрещены
|
||||
- Импорт кода между доменами — через фабрику. `import type` — напрямую
|
||||
- Доменные типы (`User`, `Product`) живут здесь, не в `shared/`
|
||||
|
||||
## Слой Infrastructure
|
||||
|
||||
Техсервисы приложения: theme, i18n, API-адаптеры, logger, realtime. Каждый сервис — отдельный модуль.
|
||||
|
||||
Слой входит в группу «Ядро». Импортирует `infrastructure/`, `ui/`, `shared/`.
|
||||
|
||||
Отличие от `shared/`: infrastructure — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
|
||||
|
||||
```text
|
||||
src/infrastructure/
|
||||
├── theme/
|
||||
├── i18n/
|
||||
├── backend-api/
|
||||
├── maps-api/
|
||||
├── logger/
|
||||
├── feature-flags/
|
||||
└── realtime/
|
||||
```
|
||||
|
||||
### Требования
|
||||
|
||||
- Один модуль = один техсервис
|
||||
- Импортирует `infrastructure/`, `ui/`, `shared/`
|
||||
|
||||
## Слой UI
|
||||
|
||||
UI-кит без бизнес-логики: button, carousel, toast, modal.
|
||||
|
||||
Слой входит в группу «Ядро». Импортирует `ui/` и `shared/`.
|
||||
|
||||
Компоненты строятся друг на друге: `button` использует `icon`, `carousel` использует `button`.
|
||||
|
||||
```text
|
||||
src/ui/
|
||||
├── button/
|
||||
├── input/
|
||||
├── icon/
|
||||
├── carousel/
|
||||
├── modal/
|
||||
├── toast/
|
||||
├── dropdown/
|
||||
├── tabs/
|
||||
└── tooltip/
|
||||
```
|
||||
|
||||
Когда количество компонентов затрудняет навигацию — вводится группировка на примитивы и композиции. Примитивы (`button`, `icon`, `input`) не импортируют композиции. Композиции (`carousel`, `modal`, `dropdown`) строятся на примитивах.
|
||||
|
||||
```text
|
||||
src/ui/
|
||||
├── primitives/
|
||||
│ ├── button/
|
||||
│ ├── input/
|
||||
│ ├── icon/
|
||||
│ └── badge/
|
||||
└── composites/
|
||||
├── carousel/
|
||||
├── modal/
|
||||
├── dropdown/
|
||||
├── tabs/
|
||||
└── tooltip/
|
||||
```
|
||||
|
||||
### Требования
|
||||
|
||||
- Не содержит бизнес-логику
|
||||
- Импортирует только `ui/` и `shared/`
|
||||
|
||||
## Слой Shared
|
||||
|
||||
Общие ресурсы: утилиты, хелперы, стили, конфиги. Не знает о бизнес-домене.
|
||||
|
||||
Слой входит в группу «Фундамент» — ни о ком не знает, никого не импортирует.
|
||||
|
||||
Отличие от `infrastructure/`: infrastructure — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
|
||||
|
||||
Отличие от `ui/`: UI-компоненты (button, carousel, modal) живут в слое `ui/`, а не здесь.
|
||||
|
||||
```text
|
||||
src/shared/
|
||||
├── lib/
|
||||
├── types/
|
||||
├── styles/
|
||||
└── sprites/
|
||||
```
|
||||
|
||||
### Требования
|
||||
|
||||
- Не имеет runtime-состояния
|
||||
@@ -1,164 +0,0 @@
|
||||
---
|
||||
title: Модули
|
||||
---
|
||||
|
||||
# Модули
|
||||
|
||||
Модули SLM: состав, границы, взаимодействие с остальным кодом.
|
||||
|
||||
## Определение
|
||||
|
||||
**Модуль — универсальный строительный блок архитектуры. Живёт на слое и содержит всё необходимое для своей работы: компоненты, хуки, сторы, сервисы, типы, стили. Набор содержимого не фиксирован — включаются только нужные части.**
|
||||
|
||||
## Модуль vs компонент
|
||||
|
||||
**Компонент** — один `.tsx` файл. Не имеет своих сегментов, использует сегменты родительского модуля. Живёт в корне или `ui/` сегменте модуля.
|
||||
|
||||
**Модуль** — папка, которая может содержать корневой компонент, сегменты (`hooks/`, `types/`, `styles/`, `ui/`, `parts/` и т.д.) и публичный API (`index.ts`).
|
||||
|
||||
```text
|
||||
auth/
|
||||
├── ui/
|
||||
│ ├── auth-guard.tsx
|
||||
│ └── logout-button.tsx
|
||||
├── parts/
|
||||
│ ├── login-form/
|
||||
│ ├── registration-form/
|
||||
│ └── restore-form/
|
||||
├── hooks/
|
||||
├── stores/
|
||||
├── types/
|
||||
├── auth.tsx # корневой компонент (опционален)
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
## Структура
|
||||
|
||||
Модуль состоит из сегментов. Ни один сегмент не обязателен — модуль может состоять даже из одного `index.ts` с реэкспортом типов.
|
||||
|
||||
```text
|
||||
{module-name}/
|
||||
├── {module-name}.tsx # корневой компонент (опционален)
|
||||
├── ui/ # компоненты модуля (только .tsx)
|
||||
├── parts/ # вложенные модули (со своими сегментами)
|
||||
├── hooks/ # хуки
|
||||
├── stores/ # сторы состояния
|
||||
├── services/ # внешние источники данных
|
||||
├── mappers/ # трансформация данных между форматами
|
||||
├── types/ # типы
|
||||
├── styles/ # стили
|
||||
├── lib/ # утилиты модуля
|
||||
├── config/ # константы
|
||||
└── index.ts # публичный API
|
||||
```
|
||||
|
||||
Подробное описание каждого сегмента — в разделе [Сегменты](/docs/basics/architecture/reference/segments).
|
||||
|
||||
## Публичный API
|
||||
|
||||
Модуль экспортирует наружу только то, что нужно другим. Всё остальное — внутреннее.
|
||||
|
||||
```ts
|
||||
// business/auth/index.ts
|
||||
export type { User, Session } from './types/user.types'
|
||||
export { useAuth } from './hooks/use-auth.hook'
|
||||
export { AuthGuard } from './ui/auth-guard'
|
||||
```
|
||||
|
||||
Импорт в обход `index.ts` запрещён:
|
||||
|
||||
```ts
|
||||
// Плохо
|
||||
import { validateToken } from '@/business/auth/lib/tokens'
|
||||
|
||||
// Хорошо
|
||||
import { useAuth } from '@/business/auth'
|
||||
```
|
||||
|
||||
## Фабрика
|
||||
|
||||
Если модуль зависит от кода другого бизнес-домена — он экспортирует фабрику. Фабрика декларирует необходимые зависимости и возвращает API модуля. Точка использования (screen, widget, layout) предоставляет зависимости при вызове.
|
||||
|
||||
Модуль без cross-domain зависимостей экспортирует API напрямую. Типы всегда экспортируются напрямую — `import type` не является runtime-зависимостью.
|
||||
|
||||
### Модуль без зависимостей — прямой экспорт:
|
||||
|
||||
```ts
|
||||
// business/auth/index.ts
|
||||
export { useAuth } from './hooks/use-auth'
|
||||
export { useCurrentUser } from './hooks/use-current-user'
|
||||
export type { User, Session } from './types'
|
||||
```
|
||||
|
||||
### Модуль с зависимостями — фабрика:
|
||||
|
||||
```ts
|
||||
// business/chat/types/deps.ts
|
||||
import type { User } from '@/business/auth'
|
||||
|
||||
export interface ChatDeps {
|
||||
useCurrentUser: () => User | null
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
// business/chat/index.ts
|
||||
import type { ChatDeps } from './types/deps'
|
||||
|
||||
export function chatFactory(deps: ChatDeps) {
|
||||
return {
|
||||
useMessages: (roomId: string) => {
|
||||
const user = deps.useCurrentUser()
|
||||
// ...
|
||||
},
|
||||
useSendMessage: (roomId: string) => {
|
||||
const user = deps.useCurrentUser()
|
||||
return (text: string) => { /* ... */ }
|
||||
},
|
||||
useChatRooms: () => {
|
||||
const user = deps.useCurrentUser()
|
||||
// ...
|
||||
},
|
||||
ChatBadge: ({ count }: { count: number }) => { /* ... */ },
|
||||
}
|
||||
}
|
||||
|
||||
export type { Message, ChatRoom } from './types'
|
||||
export type { ChatDeps } from './types/deps'
|
||||
```
|
||||
|
||||
### Использование на странице:
|
||||
|
||||
```tsx
|
||||
// screens/support/support.tsx
|
||||
import { useCurrentUser } from '@/business/auth'
|
||||
import { chatFactory } from '@/business/chat'
|
||||
|
||||
const chat = chatFactory({ useCurrentUser })
|
||||
|
||||
export function SupportScreen() {
|
||||
const { useMessages, useSendMessage, ChatBadge } = chat
|
||||
const messages = useMessages('support')
|
||||
const sendMessage = useSendMessage('support')
|
||||
|
||||
return (
|
||||
<div>
|
||||
<ChatBadge count={messages.length} />
|
||||
{messages.map(m => <MessageBubble key={m.id} {...m} />)}
|
||||
<MessageInput onSend={sendMessage} />
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Жизненный цикл
|
||||
|
||||
Модуль рождается на самом низком уровне использования и поднимается выше только при реальной потребности.
|
||||
|
||||
- Нужен на одной странице → `screens/{name}/parts/`
|
||||
- Появился в 2+ местах → поднимается по природе:
|
||||
- абстрактный UI → `ui/`
|
||||
- блок с данными/логикой → `widgets/`
|
||||
- представление бизнес-домена → `business/{area}/parts/`
|
||||
|
||||
Подъём — обычный рефакторинг в рамках задачи, а не отдельная активность.
|
||||
@@ -1,153 +0,0 @@
|
||||
---
|
||||
title: Сегменты
|
||||
---
|
||||
|
||||
# Сегменты
|
||||
|
||||
Сегменты SLM: типы, назначение, что лежит внутри каждого.
|
||||
|
||||
## Определение
|
||||
|
||||
**Сегмент — папка внутри модуля, которая группирует файлы по назначению. Набор сегментов не фиксирован — модуль включает только те, которые ему нужны. Команда сама определяет какие сегменты используются в проекте — архитектура даёт рекомендацию.**
|
||||
|
||||
## Обзор
|
||||
|
||||
| Сегмент | Содержимое |
|
||||
|---------|------------|
|
||||
| `ui/` | Компоненты модуля — только `.tsx` файлы |
|
||||
| `parts/` | Вложенные модули со своими сегментами |
|
||||
| `hooks/` | React-хуки |
|
||||
| `stores/` | Сторы состояния |
|
||||
| `services/` | Работа с внешними источниками данных |
|
||||
| `mappers/` | Трансформация данных между форматами |
|
||||
| `types/` | TypeScript-типы и интерфейсы |
|
||||
| `styles/` | Стили |
|
||||
| `lib/` | Утилиты и хелперы модуля |
|
||||
| `config/` | Константы и конфигурация |
|
||||
|
||||
## Сегмент ui/
|
||||
|
||||
Компоненты, принадлежащие модулю. Содержит только `.tsx` файлы — без своих сегментов, стилей, типов, хуков. Использует сегменты родительского модуля.
|
||||
|
||||
```text
|
||||
auth/
|
||||
├── ui/
|
||||
│ ├── auth-provider.tsx
|
||||
│ ├── auth-guard.tsx
|
||||
│ └── logout-button.tsx
|
||||
├── types/
|
||||
├── hooks/
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
Если компоненту нужны собственные сегменты — это уже не `ui/`, а `parts/`.
|
||||
|
||||
## Сегмент parts/
|
||||
|
||||
Вложенные модули со своими сегментами. Каждый элемент `parts/` — полноценный модуль: папка с компонентом, хуками, стилями, типами и т.д.
|
||||
|
||||
```text
|
||||
home/
|
||||
├── parts/
|
||||
│ ├── hero-section/
|
||||
│ │ ├── hero-section.tsx
|
||||
│ │ ├── styles/
|
||||
│ │ └── parts/
|
||||
│ │ └── top-banner/
|
||||
│ │ └── top-banner.tsx
|
||||
│ └── features-section/
|
||||
│ ├── features-section.tsx
|
||||
│ └── hooks/
|
||||
├── home.screen.tsx
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
Отличие от `ui/`: элемент `parts/` — модуль со своими сегментами. Элемент `ui/` — компонент, один `.tsx` файл.
|
||||
|
||||
Вложенность `parts/` инкапсулирует область разработки горизонтально: каждый разработчик работает в своём `parts/`-модуле, не затрагивая чужие. Это снижает конфликты при параллельной разработке.
|
||||
|
||||
Если вложенный модуль обрастает своими `parts/` — это сигнал, что он достаточно самостоятельный для подъёма на уровень выше.
|
||||
|
||||
## Сегмент hooks/
|
||||
|
||||
React-хуки модуля. Инкапсулируют логику, состояние, подписки, побочные эффекты.
|
||||
|
||||
```text
|
||||
hooks/
|
||||
├── use-auth.hook.ts
|
||||
├── use-session.hook.ts
|
||||
└── use-permissions.hook.ts
|
||||
```
|
||||
|
||||
## Сегмент stores/
|
||||
|
||||
Сторы состояния модуля. Конкретная реализация зависит от выбранного стейт-менеджера (Zustand, MobX, Redux и т.д.).
|
||||
|
||||
```text
|
||||
stores/
|
||||
├── auth.store.ts
|
||||
└── session.store.ts
|
||||
```
|
||||
|
||||
## Сегмент services/
|
||||
|
||||
Работа с внешними источниками данных: API-вызовы, запросы, подписки.
|
||||
|
||||
```text
|
||||
services/
|
||||
├── auth.service.ts
|
||||
└── token.service.ts
|
||||
```
|
||||
|
||||
## Сегмент mappers/
|
||||
|
||||
Функции трансформации данных из одного формата в другой: DTO в доменный тип, доменный тип в DTO, доменный тип в ViewModel.
|
||||
|
||||
```text
|
||||
mappers/
|
||||
├── map-user.ts
|
||||
├── map-product.ts
|
||||
└── map-order-to-dto.ts
|
||||
```
|
||||
|
||||
## Сегмент types/
|
||||
|
||||
TypeScript-типы и интерфейсы модуля. Доменные типы, DTO, пропсы компонентов.
|
||||
|
||||
```text
|
||||
types/
|
||||
├── user.type.ts
|
||||
└── session.type.ts
|
||||
```
|
||||
|
||||
## Сегмент styles/
|
||||
|
||||
Стили модуля. Формат зависит от выбранного подхода (CSS Modules, SCSS, CSS-in-JS и т.д.).
|
||||
|
||||
```text
|
||||
styles/
|
||||
├── auth.module.css
|
||||
└── login-form.module.css
|
||||
```
|
||||
|
||||
## Сегмент lib/
|
||||
|
||||
Утилиты и хелперы, специфичные для модуля. Чистые функции без побочных эффектов.
|
||||
|
||||
```text
|
||||
lib/
|
||||
├── validate-email.ts
|
||||
└── format-phone.ts
|
||||
```
|
||||
|
||||
Отличие от `shared/lib/`: здесь лежат утилиты, нужные только этому модулю. Общие утилиты — в `shared/lib/`.
|
||||
|
||||
## Сегмент config/
|
||||
|
||||
Константы и конфигурация модуля: маршруты, лимиты, дефолтные значения.
|
||||
|
||||
```text
|
||||
config/
|
||||
├── routes.ts
|
||||
└── constants.ts
|
||||
```
|
||||
@@ -1,69 +0,0 @@
|
||||
# NextJS Style Guide
|
||||
|
||||
Соглашения по разработке Next.js проектов: архитектура и слои приложения, структура кода, организация модулей, стилизация, типизация и инфраструктура.
|
||||
|
||||
## Использование
|
||||
|
||||
**Для AI-агентов:**
|
||||
|
||||
- [llms.txt](/llms.txt) — Карта разделов, оглавление со ссылками на разделы.
|
||||
- [llms-full.txt](/llms-full.txt) — Вся документация одним файлом.
|
||||
|
||||
**Для проекта:**
|
||||
|
||||
- [nextjs-style-guide.zip](/nextjs-style-guide.zip) — Набор Markdown-файлов для распаковки в `./ai/nextjs-style-guide/` или другую папку проекта.
|
||||
|
||||
## Структура документации
|
||||
|
||||
### Workflow
|
||||
|
||||
**Что делать и в каком порядке** — пошаговые инструкции.
|
||||
|
||||
| Раздел | Отвечает на вопрос |
|
||||
|--------|-------------------|
|
||||
| Начало работы | Что нужно знать перед началом разработки? |
|
||||
| Создание проекта | Как начать новый проект? |
|
||||
| Генерация кода | Какие модули должны генерироваться из шаблонов? |
|
||||
| Добавление страницы | Как добавить новую страницу в проект? |
|
||||
| Добавление UI-модуля | Как создать компонент, бизнес-модуль, виджет или layout? |
|
||||
| Стилизация | Как стилизовать компоненты в проекте? |
|
||||
| Получение данных | Как получать данные с сервера? |
|
||||
| Управление состоянием | Как работать с состоянием? |
|
||||
| Локализация | Как добавлять переводы и подключать локализацию? |
|
||||
|
||||
### Базовые правила
|
||||
|
||||
**Каким должен быть код** — стандарты, не привязанные к конкретной технологии.
|
||||
|
||||
| Раздел | Отвечает на вопрос |
|
||||
|--------|-------------------|
|
||||
| Технологии и библиотеки | Какой стек используем? |
|
||||
| Архитектура | Как устроены слои SLM, зависимости, публичный API? |
|
||||
| Стиль кода | Как оформлять код: отступы, кавычки, импорты, early return? |
|
||||
| Именование | Как называть файлы, переменные, компоненты, хуки? |
|
||||
| Документирование | Как писать JSDoc: что документировать, а что нет? |
|
||||
| Типизация | Как типизировать: type vs interface, any/unknown? |
|
||||
|
||||
### Прикладные разделы
|
||||
|
||||
**Как это настроить и использовать** — конфигурация, структура и примеры кода для конкретных областей.
|
||||
|
||||
| Раздел | Отвечает на вопрос |
|
||||
|--------|-------------------|
|
||||
| Настройка VS Code | Как настроить редактор для проекта? |
|
||||
| Структура проекта | Как организованы папки и файлы по SLM? |
|
||||
| Компоненты | Как устроен компонент: файлы, пропсы, clsx? |
|
||||
| Page-level компоненты | Как описывать layout, page, loading, error, not-found? |
|
||||
| Шаблоны и генерация кода | Как работают шаблоны, синтаксис и инструменты генерации? |
|
||||
| Стили | Как писать CSS: PostCSS Modules, вложенность, медиа, токены? |
|
||||
| Изображения | _(не заполнен)_ |
|
||||
| SVG-спрайты | _(не заполнен)_ |
|
||||
| Видео | _(не заполнен)_ |
|
||||
| API | _(не заполнен)_ |
|
||||
| Stores | _(не заполнен)_ |
|
||||
| Хуки | _(не заполнен)_ |
|
||||
| Шрифты | _(не заполнен)_ |
|
||||
| Локализация | _(не заполнен)_ |
|
||||
|
||||
|
||||
|
||||
@@ -1,86 +0,0 @@
|
||||
---
|
||||
title: Workflow
|
||||
---
|
||||
|
||||
# Workflow
|
||||
|
||||
Порядок действий при разработке — от создания проекта до реализации фич.
|
||||
|
||||
## Создание проекта
|
||||
|
||||
Инициализация нового проекта из готового шаблона.
|
||||
|
||||
1. Создать проект из шаблона:
|
||||
```bash
|
||||
npx tiged git@gromlab.ru:templates/nextjs.git my-app
|
||||
cd my-app
|
||||
npm install
|
||||
```
|
||||
2. Проект готов к разработке — стек, структура SLM, конфигурация
|
||||
редактора и шаблоны генерации уже настроены.
|
||||
|
||||
## Генерация кода
|
||||
|
||||
Создание модулей из шаблонов `.templates/` вместо ручного создания файлов.
|
||||
|
||||
1. Определить тип модуля и соответствующий шаблон:
|
||||
|
||||
| Модуль | Слой | Шаблон |
|
||||
|------------|--------------|-------------|
|
||||
| Компонент | `ui/` | `component` |
|
||||
| Бизнес-модуль | `business/` | `module` |
|
||||
| Виджет | `widgets/` | `widget` |
|
||||
| Layout | `layouts/` | `layout` |
|
||||
| Экран | `screens/` | `screen` |
|
||||
| Стор | `stores/` | `store` |
|
||||
|
||||
2. Сгенерировать модуль из шаблона.
|
||||
3. Если подходящего шаблона нет — сначала создать шаблон, затем использовать.
|
||||
|
||||
Ручное создание файловой структуры модулей запрещено.
|
||||
|
||||
## Добавление страницы
|
||||
|
||||
Создание нового маршрута: экран + точка входа для роутинга.
|
||||
|
||||
1. Сгенерировать экран из шаблона `screen` в `src/screens/`.
|
||||
2. Заполнить экран логикой и стилями.
|
||||
3. Создать `page.tsx` в нужном маршруте `src/app/`.
|
||||
|
||||
`page.tsx` — тонкая обёртка: только `metadata` и рендер экрана.
|
||||
Логика, стили и хуки размещаются в экране, не в `page.tsx`.
|
||||
|
||||
## Добавление UI-модуля
|
||||
|
||||
Создание компонента, бизнес-модуля, виджета или layout.
|
||||
|
||||
1. Сгенерировать модуль из соответствующего шаблона в целевой слой.
|
||||
2. Заполнить модуль логикой и стилями.
|
||||
3. Дочерние компоненты — генерировать из шаблона `component` в папку `ui/`
|
||||
внутри родителя.
|
||||
|
||||
Дочерние компоненты не экспортируются через `index.ts` родителя.
|
||||
|
||||
## Стилизация
|
||||
|
||||
Выбор инструмента стилизации по приоритету.
|
||||
|
||||
1. Использовать Mantine-компоненты и их пропсы.
|
||||
2. Если Mantine не покрывает — использовать CSS-токены
|
||||
(`--color-*`, `--space-*`, `--radius-*`).
|
||||
3. Если нужна кастомная стилизация — PostCSS Modules.
|
||||
|
||||
Инлайн-стили (`style`), магические значения и глобальные стили
|
||||
вне `app/styles/` запрещены.
|
||||
|
||||
## Получение данных
|
||||
|
||||
*Раздел в разработке* — SWR, генерация API-клиентов, сокеты.
|
||||
|
||||
## Управление состоянием
|
||||
|
||||
*Раздел в разработке* — когда создавать стор, что хранить локально и глобально.
|
||||
|
||||
## Локализация
|
||||
|
||||
*Раздел в разработке* — переводы и i18next.
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
title: Генерация кода
|
||||
---
|
||||
|
||||
# Генерация кода
|
||||
|
||||
Как создавать модули в проекте с помощью шаблонов — какие модули покрыты генерацией и когда стоит создавать новые шаблоны.
|
||||
|
||||
## Какие модули генерируются из шаблонов
|
||||
|
||||
| Модуль | Слой | Шаблон |
|
||||
|---|---|---|
|
||||
| Компонент | `ui/` | `component` |
|
||||
| Бизнес-модуль | `business/` | `module` |
|
||||
| Виджет | `widgets/` | `widget` |
|
||||
| Layout | `layouts/` | `layout` |
|
||||
| Экран | `screens/` | `screen` |
|
||||
| Стор | `stores/` | `store` |
|
||||
|
||||
## Что нужно знать
|
||||
|
||||
В проекте принято создавать модули из шаблонов `.templates/`. Шаблоны задают единообразную файловую структуру и сокращают рутину — не нужно вручную создавать папки, файлы типов, стилей и экспорты.
|
||||
|
||||
Если для нужного модуля нет подходящего шаблона — стоит сначала создать шаблон, а затем использовать его.
|
||||
|
||||
## Когда создавать новый шаблон
|
||||
|
||||
- Повторяющаяся структура появляется больше одного раза.
|
||||
- Существующий шаблон не покрывает нужный тип модуля.
|
||||
|
||||
Инструменты и синтаксис шаблонов — [Шаблоны и генерация кода](/docs/applied/templates-generation).
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
title: Создание проекта
|
||||
---
|
||||
|
||||
# Создание проекта
|
||||
|
||||
Как начать новый проект, соответствующий стандартам этого руководства.
|
||||
|
||||
## Что нужно знать
|
||||
|
||||
Новый проект создаётся из готового шаблона. Шаблон содержит настроенный стек, структуру SLM, конфигурацию редактора и шаблоны генерации кода — проект готов к разработке сразу после установки зависимостей.
|
||||
|
||||
### Создание из шаблона
|
||||
|
||||
```bash
|
||||
npx tiged git@gromlab.ru:templates/nextjs.git my-app
|
||||
cd my-app
|
||||
npm install
|
||||
```
|
||||
|
||||
## Что входит в шаблон
|
||||
|
||||
- Next.js + TypeScript (App Router)
|
||||
- Mantine UI + PostCSS Modules
|
||||
- Biome (линтинг и форматирование)
|
||||
- Zustand, SWR
|
||||
- Структура SLM (`layouts/`, `screens/`, `widgets/`, `business/`, `infrastructure/`, `ui/`, `shared/`)
|
||||
- Шаблоны генерации (`.templates/`)
|
||||
- Конфигурация VS Code (`.vscode/`)
|
||||
- CSS-токены (цвета, отступы, радиусы, медиа)
|
||||
- Open Graph метаданные
|
||||
@@ -1,22 +0,0 @@
|
||||
---
|
||||
title: Добавление UI-модуля
|
||||
---
|
||||
|
||||
# Добавление UI-модуля
|
||||
|
||||
Как создать компонент, бизнес-модуль, виджет или layout в проекте.
|
||||
|
||||
## Что нужно знать
|
||||
|
||||
Все UI-модули создаются только из шаблонов `.templates/`. Ручное создание файловой структуры запрещено. Если подходящего шаблона нет — сначала создать шаблон в `.templates/`, затем использовать его.
|
||||
|
||||
## Порядок действий
|
||||
|
||||
1. [Сгенерировать](/docs/applied/templates-generation) модуль из соответствующего шаблона в целевой слой.
|
||||
2. Заполнить модуль логикой и стилями.
|
||||
|
||||
## Дочерние компоненты
|
||||
|
||||
Если модулю нужны внутренние подкомпоненты — [генерировать](/docs/applied/templates-generation) их из шаблона `component` в папку `ui/` внутри родительского модуля. Дочерние компоненты не экспортируются через `index.ts` родителя.
|
||||
|
||||
Правила написания компонентов — [Компоненты](/docs/applied/components).
|
||||
@@ -1,27 +0,0 @@
|
||||
---
|
||||
title: Добавление страницы
|
||||
---
|
||||
|
||||
# Добавление страницы
|
||||
|
||||
Как добавить новую страницу в проект по стандартам этого руководства.
|
||||
|
||||
## Что нужно знать
|
||||
|
||||
Страница в проекте — это два файла: экран в `src/screens/` (вся логика, стили, зависимости) и `page.tsx` в `src/app/` (точка входа для роутинга Next.js). Экран генерируется из шаблона, `page.tsx` создаётся вручную.
|
||||
|
||||
## Порядок действий
|
||||
|
||||
1. [Сгенерировать](/docs/applied/templates-generation) экран из шаблона `screen` в папку `src/screens/`.
|
||||
|
||||
2. Заполнить экран логикой и стилями.
|
||||
|
||||
3. Создать `page.tsx` в нужном маршруте `src/app/`. Файл страницы должен быть тонким — только `metadata` и рендер экрана. Никакой логики, стилей и хуков в `page.tsx` не размещается — всё это живёт в экране.
|
||||
|
||||
## Правила
|
||||
|
||||
- Ручное создание файловой структуры экрана запрещено — только [генерация](/docs/applied/templates-generation) из шаблона.
|
||||
- Логика, стили и зависимости размещаются в экране, не в `page.tsx`.
|
||||
- Каждая страница содержит `metadata` с `title` и `description`.
|
||||
|
||||
Примеры `page.tsx` и `metadata` — [Page-level компоненты](/docs/applied/page-level).
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
title: Получение данных
|
||||
---
|
||||
|
||||
# Получение данных
|
||||
|
||||
Как получать данные с сервера — SWR, генерация API-клиентов, сокеты.
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
title: Локализация
|
||||
---
|
||||
|
||||
# Локализация
|
||||
|
||||
Как добавлять переводы и подключать локализацию через i18next.
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
title: Управление состоянием
|
||||
---
|
||||
|
||||
# Управление состоянием
|
||||
|
||||
Как работать с состоянием — когда создавать стор, что хранить локально и глобально.
|
||||
@@ -1,23 +0,0 @@
|
||||
---
|
||||
title: Стилизация
|
||||
---
|
||||
|
||||
# Стилизация
|
||||
|
||||
Как стилизовать компоненты в проекте — приоритет инструментов и правила их применения.
|
||||
|
||||
## Приоритет стилизации
|
||||
|
||||
Основной UI-фреймворк проекта — **Mantine**. При стилизации компонентов придерживаться следующего приоритета:
|
||||
|
||||
1. **Mantine-компоненты и их пропсы** — в первую очередь использовать встроенные возможности Mantine (пропсы, `classNames`, `styles`).
|
||||
2. **Глобальные CSS-токены** (`--color-*`, `--space-*`, `--radius-*`) — для значений, которые не покрываются Mantine.
|
||||
3. **PostCSS Modules** — когда Mantine не покрывает задачу и нужна кастомная стилизация.
|
||||
|
||||
## Что запрещено
|
||||
|
||||
- **Инлайн-стили** — использование атрибута `style` в компонентах строго запрещено.
|
||||
- **Магические значения** — произвольные цвета, отступы и скругления запрещены, использовать токены.
|
||||
- **Глобальные стили** вне `app/styles/` запрещены.
|
||||
|
||||
Правила написания CSS, вложенность, медиа-запросы и токены — [Стили: использование](/docs/applied/styles/usage).
|
||||
368
docs/index.md
368
docs/index.md
@@ -1,368 +0,0 @@
|
||||
---
|
||||
layout: false
|
||||
---
|
||||
|
||||
<script setup>
|
||||
import { ref, onMounted } from 'vue'
|
||||
|
||||
const THEME_KEY = 'vitepress-theme-appearance'
|
||||
|
||||
// __BUILD_VERSION__ подставляется Vite-define из ENV `BUILD_VERSION`
|
||||
// (см. .vitepress/config.ts). В dev и build всегда определена.
|
||||
const buildVersion = __BUILD_VERSION__
|
||||
|
||||
const theme = ref('auto')
|
||||
|
||||
onMounted(() => {
|
||||
const savedTheme = localStorage.getItem(THEME_KEY)
|
||||
theme.value = savedTheme === 'dark' || savedTheme === 'light' ? savedTheme : 'auto'
|
||||
})
|
||||
|
||||
function setTheme(value) {
|
||||
theme.value = value
|
||||
if (value === 'auto') {
|
||||
localStorage.removeItem(THEME_KEY)
|
||||
} else {
|
||||
localStorage.setItem(THEME_KEY, value)
|
||||
}
|
||||
const isDark = value === 'dark' || (value === 'auto' && matchMedia('(prefers-color-scheme: dark)').matches)
|
||||
document.documentElement.classList.toggle('dark', isDark)
|
||||
}
|
||||
|
||||
/**
|
||||
* Клик по кнопке темы:
|
||||
* - по активной → переключение в auto;
|
||||
* - по неактивной → выбор этого варианта.
|
||||
*/
|
||||
function toggleTheme(value) {
|
||||
setTheme(theme.value === value ? 'auto' : value)
|
||||
}
|
||||
</script>
|
||||
|
||||
<div class="landing">
|
||||
<section class="landing__hero">
|
||||
<h1 class="landing__title">NextJS Style Guide</h1>
|
||||
<ClientOnly>
|
||||
<p class="landing__tagline">Соглашения по разработке Next.js проектов: архитектура и слои приложения, структура кода, организация модулей, стилизация, типизация и инфраструктура.</p>
|
||||
<div class="landing__controls">
|
||||
<a
|
||||
class="landing__repo"
|
||||
href="https://gromlab.ru/docs/nextjs-style-guide"
|
||||
target="_blank"
|
||||
rel="noopener"
|
||||
>
|
||||
<svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
|
||||
<path d="M12 .3a12 12 0 0 0-3.8 23.38c.6.12.83-.26.83-.57L9 21.07c-3.34.72-4.04-1.61-4.04-1.61-.55-1.39-1.34-1.76-1.34-1.76-1.08-.74.09-.73.09-.73 1.2.09 1.83 1.24 1.83 1.24 1.08 1.83 2.81 1.3 3.5 1 .1-.78.42-1.31.76-1.61-2.67-.3-5.47-1.33-5.47-5.93 0-1.31.47-2.38 1.24-3.22-.14-.3-.54-1.52.1-3.18 0 0 1-.32 3.3 1.23a11.5 11.5 0 0 1 6 0c2.28-1.55 3.29-1.23 3.29-1.23.64 1.66.24 2.88.12 3.18a4.65 4.65 0 0 1 1.23 3.22c0 4.61-2.8 5.63-5.48 5.92.42.36.81 1.1.81 2.22l-.01 3.29c0 .31.2.69.82.57A12 12 0 0 0 12 .3Z"/>
|
||||
</svg>
|
||||
<span>Репозиторий</span>
|
||||
</a>
|
||||
<div class="seg seg--icons" role="group" aria-label="Тема">
|
||||
<button
|
||||
type="button"
|
||||
class="seg__btn"
|
||||
:class="{ 'seg__btn--active': theme === 'light' }"
|
||||
:aria-pressed="theme === 'light'"
|
||||
title="Светлая"
|
||||
@click="toggleTheme('light')"
|
||||
>
|
||||
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M4.93 19.07l1.41-1.41M17.66 6.34l1.41-1.41"/></svg>
|
||||
</button>
|
||||
<button
|
||||
type="button"
|
||||
class="seg__btn"
|
||||
:class="{ 'seg__btn--active': theme === 'dark' }"
|
||||
:aria-pressed="theme === 'dark'"
|
||||
title="Тёмная"
|
||||
@click="toggleTheme('dark')"
|
||||
>
|
||||
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
</ClientOnly>
|
||||
</section>
|
||||
|
||||
<section class="landing__cards">
|
||||
<a class="landing__card" href="./docs/">
|
||||
<h3>Документация</h3>
|
||||
<p>Все разделы: процессы разработки, базовые правила, прикладные руководства.</p>
|
||||
<span class="landing__cta">Открыть →</span>
|
||||
</a>
|
||||
<div class="landing__card landing__card--multi">
|
||||
<h3>Ассистенту</h3>
|
||||
<p>Карта документации в формате llms.txt для AI-агентов.</p>
|
||||
<div class="landing__buttons">
|
||||
<a class="landing__button" href="./llms.txt" target="_blank" rel="noopener">llms.txt</a>
|
||||
<a class="landing__button" href="./llms-full.txt" target="_blank" rel="noopener">llms-full.txt</a>
|
||||
</div>
|
||||
</div>
|
||||
<a class="landing__card" href="./nextjs-style-guide.zip">
|
||||
<h3>Скачать правила</h3>
|
||||
<p>Архив всех Markdown-файлов одним ZIP.</p>
|
||||
<span class="landing__cta">Скачать →</span>
|
||||
</a>
|
||||
</section>
|
||||
|
||||
<p class="landing__version">v{{ buildVersion }}</p>
|
||||
</div>
|
||||
|
||||
<style scoped>
|
||||
.landing {
|
||||
min-height: 100vh;
|
||||
padding: 48px 32px;
|
||||
background: var(--vp-c-bg);
|
||||
color: var(--vp-c-text-1);
|
||||
font-family: var(--vp-font-family-base);
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
justify-content: center;
|
||||
gap: 64px;
|
||||
}
|
||||
|
||||
.landing__controls {
|
||||
display: flex;
|
||||
justify-content: center;
|
||||
align-items: center;
|
||||
gap: 12px;
|
||||
margin-top: 28px;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
|
||||
.landing__controls > * {
|
||||
height: 36px;
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
.landing__repo {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
padding: 0 14px;
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
border-radius: 999px;
|
||||
background: var(--vp-c-bg-soft);
|
||||
color: var(--vp-c-text-2);
|
||||
font-size: 13px;
|
||||
font-weight: 500;
|
||||
text-decoration: none;
|
||||
transition: color 0.15s, border-color 0.15s;
|
||||
}
|
||||
|
||||
.landing__repo:hover {
|
||||
color: var(--vp-c-text-1);
|
||||
border-color: var(--vp-c-brand-1);
|
||||
}
|
||||
|
||||
.landing__repo svg {
|
||||
flex-shrink: 0;
|
||||
}
|
||||
|
||||
.seg {
|
||||
display: inline-flex;
|
||||
align-items: stretch;
|
||||
padding: 4px;
|
||||
background: var(--vp-c-bg-soft);
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
border-radius: 999px;
|
||||
gap: 2px;
|
||||
}
|
||||
|
||||
.seg__btn {
|
||||
appearance: none;
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
gap: 6px;
|
||||
padding: 6px 14px;
|
||||
font-size: 13px;
|
||||
font-weight: 500;
|
||||
font-family: inherit;
|
||||
line-height: 1;
|
||||
color: var(--vp-c-text-2);
|
||||
background: transparent;
|
||||
border: none;
|
||||
border-radius: 999px;
|
||||
cursor: pointer;
|
||||
transition: color 0.15s, background-color 0.15s;
|
||||
}
|
||||
|
||||
.seg__btn:hover {
|
||||
color: var(--vp-c-text-1);
|
||||
}
|
||||
|
||||
.seg__btn--active {
|
||||
background: var(--vp-c-bg);
|
||||
color: var(--vp-c-text-1);
|
||||
box-shadow: 0 1px 2px rgba(0, 0, 0, 0.08);
|
||||
}
|
||||
|
||||
.seg--icons .seg__btn {
|
||||
padding: 6px 10px;
|
||||
}
|
||||
|
||||
.seg__btn svg {
|
||||
display: block;
|
||||
}
|
||||
|
||||
.landing__hero {
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
.landing__title {
|
||||
font-size: 56px;
|
||||
font-weight: 700;
|
||||
line-height: 1;
|
||||
margin: 0 0 16px;
|
||||
letter-spacing: -0.02em;
|
||||
background: linear-gradient(120deg, var(--vp-c-brand-1), var(--vp-c-brand-2));
|
||||
-webkit-background-clip: text;
|
||||
background-clip: text;
|
||||
color: transparent;
|
||||
}
|
||||
|
||||
.landing__tagline {
|
||||
font-size: 18px;
|
||||
line-height: 1.55;
|
||||
color: var(--vp-c-text-2);
|
||||
margin: 0 auto;
|
||||
max-width: 720px;
|
||||
}
|
||||
|
||||
.landing__cards {
|
||||
max-width: 1100px;
|
||||
width: 100%;
|
||||
margin: 0 auto;
|
||||
display: grid;
|
||||
grid-template-columns: repeat(3, 1fr);
|
||||
gap: 16px;
|
||||
}
|
||||
|
||||
.landing__card {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 8px;
|
||||
padding: 24px;
|
||||
border-radius: 12px;
|
||||
background: var(--vp-c-bg-soft);
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
text-decoration: none;
|
||||
color: inherit;
|
||||
transition: border-color 0.2s, transform 0.2s;
|
||||
}
|
||||
|
||||
.landing__card:hover {
|
||||
border-color: var(--vp-c-brand-1);
|
||||
transform: translateY(-2px);
|
||||
}
|
||||
|
||||
.landing__card h3 {
|
||||
margin: 0;
|
||||
font-size: 18px;
|
||||
font-weight: 600;
|
||||
color: var(--vp-c-text-1);
|
||||
}
|
||||
|
||||
.landing__card p {
|
||||
margin: 0;
|
||||
font-size: 14px;
|
||||
line-height: 1.5;
|
||||
color: var(--vp-c-text-2);
|
||||
}
|
||||
|
||||
.landing__cta {
|
||||
margin-top: auto;
|
||||
font-size: 14px;
|
||||
font-weight: 500;
|
||||
color: var(--vp-c-brand-1);
|
||||
}
|
||||
|
||||
.landing__buttons {
|
||||
margin-top: auto;
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 8px;
|
||||
}
|
||||
|
||||
.landing__button {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
padding: 6px 12px;
|
||||
font-size: 13px;
|
||||
font-weight: 500;
|
||||
font-family: var(--vp-font-family-mono, monospace);
|
||||
color: var(--vp-c-text-1);
|
||||
background: var(--vp-c-bg);
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
border-radius: 8px;
|
||||
text-decoration: none;
|
||||
transition: border-color 0.15s, color 0.15s;
|
||||
}
|
||||
|
||||
.landing__button:hover {
|
||||
border-color: var(--vp-c-brand-1);
|
||||
color: var(--vp-c-brand-1);
|
||||
}
|
||||
|
||||
.landing__version {
|
||||
text-align: center;
|
||||
margin: 24px 0 0;
|
||||
font-size: 12px;
|
||||
color: var(--vp-c-text-3);
|
||||
font-family: var(--vp-font-family-mono, monospace);
|
||||
}
|
||||
|
||||
@media (max-width: 768px) {
|
||||
.landing {
|
||||
padding: 48px 20px 56px;
|
||||
gap: 40px;
|
||||
justify-content: flex-start;
|
||||
}
|
||||
.landing__title {
|
||||
font-size: 36px;
|
||||
}
|
||||
.landing__tagline {
|
||||
font-size: 16px;
|
||||
}
|
||||
.landing__cards {
|
||||
grid-template-columns: 1fr;
|
||||
gap: 16px;
|
||||
}
|
||||
.landing__controls {
|
||||
gap: 8px;
|
||||
margin-top: 36px;
|
||||
}
|
||||
}
|
||||
|
||||
@media (max-width: 480px) {
|
||||
.landing {
|
||||
padding: 44px 16px 48px;
|
||||
gap: 36px;
|
||||
}
|
||||
.landing__title {
|
||||
font-size: 30px;
|
||||
}
|
||||
.landing__tagline {
|
||||
font-size: 15px;
|
||||
line-height: 1.5;
|
||||
}
|
||||
.landing__controls {
|
||||
margin-top: 32px;
|
||||
}
|
||||
/* Репозиторий — только иконка, без текста, чтобы все контролы влезли в строку */
|
||||
.landing__repo {
|
||||
width: 36px;
|
||||
padding: 0;
|
||||
justify-content: center;
|
||||
}
|
||||
.landing__repo span {
|
||||
display: none;
|
||||
}
|
||||
.seg__btn {
|
||||
padding: 6px 12px;
|
||||
font-size: 12px;
|
||||
}
|
||||
.landing__card {
|
||||
padding: 20px;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
508
generate-llms.ts
508
generate-llms.ts
@@ -1,508 +0,0 @@
|
||||
import path from 'node:path';
|
||||
import fs from 'node:fs';
|
||||
import os from 'node:os';
|
||||
import { execFileSync } from 'node:child_process';
|
||||
import config from './.vitepress/config';
|
||||
|
||||
/** Версия сборки. Передаётся CI через ENV; локально — `dev`. */
|
||||
const VERSION = process.env.BUILD_VERSION || 'dev';
|
||||
const BUILD_DATE = new Date().toISOString();
|
||||
|
||||
/** Корневая папка для генерируемой статики (попадает в build dist). */
|
||||
const PUBLIC_DIR = 'docs/public';
|
||||
|
||||
/** Префикс URL документации. Соответствует структуре `docs/docs/...`. */
|
||||
const DOC_PREFIX = '/docs/';
|
||||
|
||||
interface SidebarItem {
|
||||
text: string;
|
||||
link?: string;
|
||||
items?: SidebarItem[];
|
||||
collapsed?: boolean;
|
||||
}
|
||||
|
||||
interface Entry {
|
||||
/** Название группы верхнего уровня (sidebar[].text) */
|
||||
section: string;
|
||||
/** Префикс из вложенной группы (например "Архитектура") */
|
||||
prefix: string | null;
|
||||
/** Текст пункта в sidebar */
|
||||
text: string;
|
||||
/** Ссылка из sidebar */
|
||||
link: string;
|
||||
}
|
||||
|
||||
/** Разобрать YAML frontmatter (плоский, без вложенностей) */
|
||||
const parseFrontmatter = (
|
||||
content: string,
|
||||
): { data: Record<string, string>; body: string } => {
|
||||
const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
|
||||
if (!match) return { data: {}, body: content };
|
||||
|
||||
const data: Record<string, string> = {};
|
||||
for (const line of match[1].split('\n')) {
|
||||
const lineMatch = line.match(/^([^:]+):\s*(.*)$/);
|
||||
if (!lineMatch) continue;
|
||||
let value = lineMatch[2].trim();
|
||||
if (
|
||||
(value.startsWith('"') && value.endsWith('"')) ||
|
||||
(value.startsWith("'") && value.endsWith("'"))
|
||||
) {
|
||||
value = value.slice(1, -1);
|
||||
}
|
||||
data[lineMatch[1].trim()] = value;
|
||||
}
|
||||
return { data, body: match[2] };
|
||||
};
|
||||
|
||||
/** Первый абзац после h1 — однострочное описание для llms.txt */
|
||||
const firstParagraphAfterH1 = (body: string): string | null => {
|
||||
const lines = body.split('\n');
|
||||
const h1Idx = lines.findIndex((l) => /^#\s/.test(l));
|
||||
if (h1Idx === -1) return null;
|
||||
|
||||
let i = h1Idx + 1;
|
||||
while (i < lines.length && lines[i].trim() === '') i++;
|
||||
|
||||
const para: string[] = [];
|
||||
while (
|
||||
i < lines.length &&
|
||||
lines[i].trim() !== '' &&
|
||||
!lines[i].startsWith('#')
|
||||
) {
|
||||
para.push(lines[i].trim());
|
||||
i++;
|
||||
}
|
||||
return para.join(' ').trim() || null;
|
||||
};
|
||||
|
||||
/**
|
||||
* Преобразовать sidebar `link` (например `/docs/foo`) в относительный
|
||||
* путь файла внутри `docs/docs/`. Префикс `/docs/` отрезается.
|
||||
*/
|
||||
const linkToRel = (link: string): string => {
|
||||
let rel = link.startsWith(DOC_PREFIX)
|
||||
? link.slice(DOC_PREFIX.length)
|
||||
: link.replace(/^\//, '');
|
||||
if (rel === '' || rel.endsWith('/')) {
|
||||
rel += 'index.md';
|
||||
} else {
|
||||
rel += '.md';
|
||||
}
|
||||
return rel;
|
||||
};
|
||||
|
||||
const linkToFilePath = (link: string): string =>
|
||||
path.join('docs/docs', linkToRel(link));
|
||||
|
||||
/** Абсолютный URL `.md`-копии страницы на сайте. */
|
||||
const linkToSiteUrl = (link: string): string =>
|
||||
`${DOC_PREFIX}${linkToRel(link)}`;
|
||||
|
||||
/**
|
||||
* Развернуть sidebar в плоский список с сохранением группы и
|
||||
* опционального префикса вложенной группы.
|
||||
*/
|
||||
const flattenSidebar = (sidebar: SidebarItem[]): Entry[] => {
|
||||
const entries: Entry[] = [];
|
||||
|
||||
for (const top of sidebar) {
|
||||
const section = top.text;
|
||||
|
||||
if (top.link && !top.items) {
|
||||
entries.push({ section, 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,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return entries;
|
||||
};
|
||||
|
||||
const groupBySection = (entries: Entry[]): Map<string, Entry[]> => {
|
||||
const map = new Map<string, Entry[]>();
|
||||
for (const entry of entries) {
|
||||
const list = map.get(entry.section);
|
||||
if (list) list.push(entry);
|
||||
else map.set(entry.section, [entry]);
|
||||
}
|
||||
return map;
|
||||
};
|
||||
|
||||
interface SiteConfig {
|
||||
title: string;
|
||||
description: string;
|
||||
themeConfig: { sidebar: SidebarItem[] };
|
||||
llmsBlockquote?: string;
|
||||
llmsContext?: string;
|
||||
}
|
||||
|
||||
const cfg = config as unknown as SiteConfig;
|
||||
|
||||
const buildLlms = (): void => {
|
||||
const sidebar = cfg.themeConfig.sidebar;
|
||||
const blockquote = cfg.llmsBlockquote ?? cfg.description;
|
||||
const context = cfg.llmsContext;
|
||||
|
||||
const entries = flattenSidebar(sidebar);
|
||||
const grouped = groupBySection(entries);
|
||||
|
||||
const lines: string[] = [];
|
||||
lines.push(`# ${cfg.title}`);
|
||||
lines.push('');
|
||||
lines.push(`> ${blockquote}`);
|
||||
lines.push('');
|
||||
if (context) {
|
||||
lines.push(context);
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
for (const [section, items] of grouped) {
|
||||
lines.push(`## ${section}`);
|
||||
lines.push('');
|
||||
|
||||
for (const entry of items) {
|
||||
const filePath = linkToFilePath(entry.link);
|
||||
const url = linkToSiteUrl(entry.link);
|
||||
|
||||
let description: string | null = null;
|
||||
if (fs.existsSync(filePath)) {
|
||||
const raw = fs.readFileSync(filePath, 'utf8');
|
||||
const { data, body } = parseFrontmatter(raw);
|
||||
description = data.description || firstParagraphAfterH1(body);
|
||||
} else {
|
||||
console.warn(`файл не найден: ${filePath}`);
|
||||
}
|
||||
|
||||
const display = entry.prefix
|
||||
? `${entry.prefix}: ${entry.text}`
|
||||
: entry.text;
|
||||
const descPart = description ? `: ${description}` : '';
|
||||
lines.push(`- [${display}](${url})${descPart}`);
|
||||
}
|
||||
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
fs.mkdirSync(PUBLIC_DIR, { recursive: true });
|
||||
const outFile = path.join(PUBLIC_DIR, 'llms.txt');
|
||||
fs.writeFileSync(outFile, lines.join('\n'), 'utf8');
|
||||
console.log(`${outFile} создан`);
|
||||
};
|
||||
|
||||
/** Рекурсивно скопировать дерево, фильтруя по предикату. */
|
||||
const copyDirSync = (
|
||||
src: string,
|
||||
dest: string,
|
||||
filter: (name: string) => boolean = () => true,
|
||||
): number => {
|
||||
let count = 0;
|
||||
for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
|
||||
const srcPath = path.join(src, entry.name);
|
||||
const destPath = path.join(dest, entry.name);
|
||||
if (entry.isDirectory()) {
|
||||
fs.mkdirSync(destPath, { recursive: true });
|
||||
count += copyDirSync(srcPath, destPath, filter);
|
||||
} else if (entry.isFile() && filter(entry.name)) {
|
||||
fs.mkdirSync(dest, { recursive: true });
|
||||
fs.copyFileSync(srcPath, destPath);
|
||||
count++;
|
||||
}
|
||||
}
|
||||
return count;
|
||||
};
|
||||
|
||||
/**
|
||||
* Скопировать все `.md`-файлы документации в `docs/public/docs/`,
|
||||
* чтобы они попали в build `dist/` и были доступны по URL `/docs/path.md`.
|
||||
*/
|
||||
const copyMdFiles = (): void => {
|
||||
const srcDir = 'docs/docs';
|
||||
const destDir = path.join(PUBLIC_DIR, 'docs');
|
||||
if (!fs.existsSync(srcDir)) return;
|
||||
|
||||
const copied = copyDirSync(srcDir, destDir, (name) => name.endsWith('.md'));
|
||||
console.log(`скопировано ${copied} .md-файлов в ${destDir}`);
|
||||
};
|
||||
|
||||
/**
|
||||
* Преобразовать sidebar `link` в относительный путь файла внутри архива
|
||||
* (от корня папки `nextjs-style-guide/`).
|
||||
*/
|
||||
const linkToArchiveRel = (link: string): string => {
|
||||
let rel = link.startsWith(DOC_PREFIX)
|
||||
? link.slice(DOC_PREFIX.length)
|
||||
: link.replace(/^\//, '');
|
||||
if (rel === '' || rel.endsWith('/')) {
|
||||
rel += 'index.md';
|
||||
} else {
|
||||
rel += '.md';
|
||||
}
|
||||
return rel;
|
||||
};
|
||||
|
||||
/**
|
||||
* Заменить во всех `.md` архива ссылки `[text](/docs/foo)` на относительные
|
||||
* пути от расположения файла. Без этого внутренние ссылки в распакованной
|
||||
* папке не работают.
|
||||
*/
|
||||
const transformLinksInDir = (rootDir: string): void => {
|
||||
const linkRe = /\]\(\/docs\/([^)\s#]*)(#[^)]*)?\)/g;
|
||||
|
||||
const walk = (dir: string): void => {
|
||||
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
||||
const full = path.join(dir, entry.name);
|
||||
if (entry.isDirectory()) {
|
||||
walk(full);
|
||||
continue;
|
||||
}
|
||||
if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
|
||||
|
||||
const content = fs.readFileSync(full, 'utf8');
|
||||
const fileDir = path.dirname(full);
|
||||
|
||||
const updated = content.replace(linkRe, (_match, route, hash = '') => {
|
||||
const targetRel = linkToArchiveRel(`${DOC_PREFIX}${route}`);
|
||||
const targetAbs = path.join(rootDir, targetRel);
|
||||
let rel = path.relative(fileDir, targetAbs);
|
||||
if (!rel.startsWith('.')) rel = './' + rel;
|
||||
return `](${rel}${hash})`;
|
||||
});
|
||||
|
||||
if (updated !== content) {
|
||||
fs.writeFileSync(full, updated, 'utf8');
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
walk(rootDir);
|
||||
};
|
||||
|
||||
/**
|
||||
* Сгенерировать `README.md` — точка входа архива. Карта документации
|
||||
* с относительными ссылками, описаниями из frontmatter/первого абзаца
|
||||
* и метаинфо сборки.
|
||||
*/
|
||||
const buildArchiveReadme = (rootDir: string): void => {
|
||||
const sidebar = cfg.themeConfig.sidebar;
|
||||
const blockquote = cfg.llmsBlockquote ?? cfg.description ?? '';
|
||||
const context = cfg.llmsContext;
|
||||
|
||||
const entries = flattenSidebar(sidebar).filter(
|
||||
// «Главная» из sidebar — это страница раздела для веба, в архиве не нужна.
|
||||
(e) => e.section !== 'Главная',
|
||||
);
|
||||
const grouped = groupBySection(entries);
|
||||
|
||||
const lines: string[] = [];
|
||||
lines.push(`# ${cfg.title}`);
|
||||
lines.push('');
|
||||
if (blockquote) {
|
||||
lines.push(`> ${blockquote}`);
|
||||
lines.push('');
|
||||
}
|
||||
if (context) {
|
||||
lines.push(context);
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
lines.push('## Содержание');
|
||||
lines.push('');
|
||||
|
||||
for (const [section, items] of grouped) {
|
||||
lines.push(`### ${section}`);
|
||||
lines.push('');
|
||||
for (const entry of items) {
|
||||
const targetRel = './' + linkToArchiveRel(entry.link);
|
||||
const filePath = path.join(rootDir, linkToArchiveRel(entry.link));
|
||||
|
||||
let description: string | null = null;
|
||||
if (fs.existsSync(filePath)) {
|
||||
const raw = fs.readFileSync(filePath, 'utf8');
|
||||
const { data, body } = parseFrontmatter(raw);
|
||||
description = data.description || firstParagraphAfterH1(body);
|
||||
}
|
||||
|
||||
const display = entry.prefix
|
||||
? `${entry.prefix}: ${entry.text}`
|
||||
: entry.text;
|
||||
const descPart = description ? ` — ${description}` : '';
|
||||
lines.push(`- [${display}](${targetRel})${descPart}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
lines.push('---');
|
||||
lines.push('');
|
||||
lines.push(`Версия: ${VERSION} · Сборка: ${BUILD_DATE}`);
|
||||
lines.push('');
|
||||
|
||||
fs.writeFileSync(path.join(rootDir, 'README.md'), lines.join('\n'), 'utf8');
|
||||
};
|
||||
|
||||
/**
|
||||
* Собрать `nextjs-style-guide.zip`. Внутри — папка `nextjs-style-guide/`
|
||||
* с `.md`-файлами, README, `llms-full.txt` и `VERSION`. Внутренние ссылки
|
||||
* преобразуются в относительные.
|
||||
*/
|
||||
const buildZip = (): void => {
|
||||
const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'nsg-'));
|
||||
const stage = path.join(tmpRoot, 'nextjs-style-guide');
|
||||
fs.mkdirSync(stage, { recursive: true });
|
||||
|
||||
// 1. Копируем все .md в staging.
|
||||
copyDirSync('docs/docs', stage, (name) => name.endsWith('.md'));
|
||||
|
||||
// 2. Удаляем веб-index.md — в архиве его роль выполняет README.md.
|
||||
const indexPath = path.join(stage, 'index.md');
|
||||
if (fs.existsSync(indexPath)) fs.unlinkSync(indexPath);
|
||||
|
||||
// 3. Преобразуем абсолютные ссылки `/docs/...` в относительные.
|
||||
transformLinksInDir(stage);
|
||||
|
||||
// 4. Генерируем точку входа README.md.
|
||||
buildArchiveReadme(stage);
|
||||
|
||||
// 5. Кладём llms-full.txt — удобно для одноразового чтения LLM.
|
||||
const llmsFullSrc = path.join(PUBLIC_DIR, 'llms-full.txt');
|
||||
if (fs.existsSync(llmsFullSrc)) {
|
||||
fs.copyFileSync(llmsFullSrc, path.join(stage, 'llms-full.txt'));
|
||||
}
|
||||
|
||||
// 6. Метаинформация сборки.
|
||||
fs.writeFileSync(
|
||||
path.join(stage, 'VERSION'),
|
||||
`${VERSION}\n${BUILD_DATE}\n`,
|
||||
);
|
||||
|
||||
const outFile = path.resolve(PUBLIC_DIR, 'nextjs-style-guide.zip');
|
||||
fs.rmSync(outFile, { force: true });
|
||||
|
||||
execFileSync('zip', ['-rq', outFile, 'nextjs-style-guide'], {
|
||||
cwd: tmpRoot,
|
||||
});
|
||||
|
||||
fs.rmSync(tmpRoot, { recursive: true, force: true });
|
||||
console.log(`${outFile} создан (${VERSION})`);
|
||||
};
|
||||
|
||||
/** Удалить YAML frontmatter из исходника `.md`. */
|
||||
const stripFrontmatter = (content: string): string =>
|
||||
content.replace(/^---\n[\s\S]*?\n---\n*/, '');
|
||||
|
||||
/**
|
||||
* Сдвинуть уровень заголовков на 1 вниз (h1→h2, h2→h3, ...).
|
||||
* Игнорирует строки внутри блоков кода.
|
||||
*/
|
||||
const shiftHeadings = (content: string): string => {
|
||||
const lines = content.split('\n');
|
||||
let inCodeBlock = false;
|
||||
return lines
|
||||
.map((line) => {
|
||||
if (line.startsWith('```')) inCodeBlock = !inCodeBlock;
|
||||
if (inCodeBlock) return line;
|
||||
if (/^#{1,5}\s/.test(line)) return '#' + line;
|
||||
return line;
|
||||
})
|
||||
.join('\n');
|
||||
};
|
||||
|
||||
/**
|
||||
* Собрать `llms-full.txt` — все страницы в одном файле.
|
||||
* Порядок страниц повторяет порядок в sidebar.
|
||||
*/
|
||||
const buildLlmsFull = (): void => {
|
||||
const sidebar = cfg.themeConfig.sidebar;
|
||||
const entries = flattenSidebar(sidebar);
|
||||
const blockquote = cfg.llmsBlockquote ?? cfg.description ?? '';
|
||||
|
||||
const parts: string[] = [];
|
||||
parts.push(`# ${cfg.title}`);
|
||||
parts.push('');
|
||||
if (blockquote) parts.push(`> ${blockquote}`);
|
||||
if (cfg.llmsContext) {
|
||||
parts.push('');
|
||||
parts.push(cfg.llmsContext);
|
||||
}
|
||||
parts.push('');
|
||||
|
||||
for (const entry of entries) {
|
||||
const filePath = linkToFilePath(entry.link);
|
||||
if (!fs.existsSync(filePath)) continue;
|
||||
|
||||
const raw = fs.readFileSync(filePath, 'utf8');
|
||||
const content = shiftHeadings(stripFrontmatter(raw)).trim();
|
||||
if (!content) continue;
|
||||
|
||||
// Мета-якорь: путь страницы для ориентации LLM
|
||||
parts.push(`<!-- ${entry.link} -->`);
|
||||
parts.push('');
|
||||
parts.push(content);
|
||||
parts.push('');
|
||||
}
|
||||
|
||||
fs.mkdirSync(PUBLIC_DIR, { recursive: true });
|
||||
const outFile = path.join(PUBLIC_DIR, 'llms-full.txt');
|
||||
fs.writeFileSync(outFile, parts.join('\n'), 'utf8');
|
||||
console.log(`${outFile} создан`);
|
||||
};
|
||||
|
||||
/** Манифест сборки — для лендинга и внешних потребителей. */
|
||||
const writeManifest = (): void => {
|
||||
const manifest = {
|
||||
version: VERSION,
|
||||
buildDate: BUILD_DATE,
|
||||
llms: '/llms.txt',
|
||||
llmsFull: '/llms-full.txt',
|
||||
zip: '/nextjs-style-guide.zip',
|
||||
};
|
||||
fs.mkdirSync(PUBLIC_DIR, { recursive: true });
|
||||
fs.writeFileSync(
|
||||
path.join(PUBLIC_DIR, 'manifest.json'),
|
||||
JSON.stringify(manifest, null, 2),
|
||||
'utf8',
|
||||
);
|
||||
console.log(`${PUBLIC_DIR}/manifest.json создан`);
|
||||
};
|
||||
|
||||
/** Скопировать `index.md` документации в корневой README без frontmatter. */
|
||||
const buildReadme = (): void => {
|
||||
const indexPath = 'docs/docs/index.md';
|
||||
if (!fs.existsSync(indexPath)) {
|
||||
console.warn(`Пропуск README.md: ${indexPath} не найден`);
|
||||
return;
|
||||
}
|
||||
const raw = fs.readFileSync(indexPath, 'utf8');
|
||||
const { body } = parseFrontmatter(raw);
|
||||
fs.writeFileSync('README.md', body.trimStart(), 'utf8');
|
||||
console.log(`README.md обновлён из ${indexPath}`);
|
||||
};
|
||||
|
||||
buildLlms();
|
||||
buildLlmsFull();
|
||||
copyMdFiles();
|
||||
buildZip();
|
||||
writeManifest();
|
||||
buildReadme();
|
||||
166
notes
166
notes
@@ -1,153 +1,23 @@
|
||||
ФЛОУ
|
||||
- после создания компонента, заменить шаблонный коментарий документа на реальный.
|
||||
|
||||
|
||||
Проблема, неочевидность слоев (наследие FSD)
|
||||
|
||||
# TODO
|
||||
|
||||
Архитектурные слои проекта
|
||||
Каждый нижний слой не знает о существовании верхних. Импорты идут только сверху вниз.
|
||||
pages → layouts → screens → widgets → features → entities → shared
|
||||
---
|
||||
1. Pages (pages/)
|
||||
Точка входа маршрута. Только связывает layout и screen.
|
||||
Правила:
|
||||
- Никакой логики, стилей, разметки кроме композиции
|
||||
- Один page = один layout + один screen
|
||||
Пример:
|
||||
// pages/knv-new.js
|
||||
import { KnvScreen } from 'src/screens/knv'
|
||||
import { MainLayout } from 'src/layouts/main'
|
||||
const KnvNewPage = () => (
|
||||
<MainLayout>
|
||||
<KnvScreen />
|
||||
</MainLayout>
|
||||
)
|
||||
---
|
||||
2. Layouts (src/layouts/)
|
||||
Каркас страницы — общие элементы, которые одинаковы на всех страницах в рамках этого layout.
|
||||
Содержит в ui/: header, footer, sidebar — дочерние компоненты, которые привязаны к layout и не переиспользуются отдельно.
|
||||
Критерий: компонент одинаков на всех страницах, использующих этот layout? → layouts/{name}/ui/
|
||||
Пример:
|
||||
src/layouts/main/
|
||||
├── main.layout.tsx # <Header /> + children + <Footer />
|
||||
├── ui/
|
||||
│ ├── header/ # всегда одинаковый на всех страницах
|
||||
│ └── footer/ # всегда одинаковый на всех страницах
|
||||
---
|
||||
3. Screens (src/screens/)
|
||||
Контент конкретной страницы. Собирает свои секции и переиспользуемые widgets/features/entities.
|
||||
Содержит в ui/: блоки, которые существуют только на этой странице и не переиспользуются.
|
||||
Критерий: компонент используется только на одной странице? → screens/{name}/ui/
|
||||
Пример:
|
||||
src/screens/knv/
|
||||
├── knv.screen.tsx
|
||||
├── ui/
|
||||
│ ├── hero-section/ # hero только на главной КНВ
|
||||
│ ├── products-section/ # секция препаратов только на главной
|
||||
│ ├── diseases-section/ # секция заболеваний только на главной
|
||||
│ └── doctor-section/ # секция врачей только на главной
|
||||
Каждая секция внутри может использовать shared/ui компоненты:
|
||||
// screens/knv/ui/products-section/products-section.widget.tsx
|
||||
import { Carousel } from 'src/shared/ui/carousel'
|
||||
import { ProductCard } from './ui/product-card' // локальный, пока не переиспользуется
|
||||
Когда локальный компонент начинает использоваться на 2+ страницах — выносим в entities/ или shared/ui.
|
||||
---
|
||||
4. Widgets (src/widgets/)
|
||||
Составные блоки с данными/логикой, которые переиспользуются на 2+ страницах.
|
||||
Критерий: блок с бизнес-логикой + данными используется на нескольких страницах? → widgets/
|
||||
Пример: Слайдер «Популярные препараты» с загрузкой данных из API, который показывается и на главной, и на странице заболевания, и в каталоге:
|
||||
src/widgets/
|
||||
├── popular-products-slider/
|
||||
│ ├── popular-products-slider.widget.tsx # Carousel + ProductCard + useProducts()
|
||||
│ ├── hooks/
|
||||
│ │ └── use-products.hook.ts # запрос данных
|
||||
Не widget: секция «Подобрать врача» которая есть только на главной → screens/knv/ui/
|
||||
---
|
||||
5. Features (src/features/)
|
||||
Пользовательское действие или интерактивный сценарий. Содержит бизнес-логику взаимодействия.
|
||||
Критерий: это действие пользователя (отправить форму, авторизоваться, добавить в корзину)? → features/
|
||||
Примеры:
|
||||
src/features/
|
||||
├── auth/ # авторизация (форма + логика + стор)
|
||||
│ ├── auth.feature.tsx
|
||||
│ ├── hooks/
|
||||
│ │ └── use-auth.hook.ts
|
||||
│ └── stores/
|
||||
│ └── auth.store.ts
|
||||
│
|
||||
├── order-drug/ # заказ препарата (кнопка + модалка + API)
|
||||
│ ├── order-drug.feature.tsx
|
||||
│ └── hooks/
|
||||
│ └── use-order.hook.ts
|
||||
Не feature: отображение карточки препарата без взаимодействия → entities/ или shared/ui
|
||||
---
|
||||
6. Entities (src/entities/)
|
||||
Бизнес-сущность с её отображением и типами. Привязана к домену (препарат, заболевание, врач, пользователь).
|
||||
Критерий: это представление бизнес-объекта, которое переиспользуется в разных контекстах? → entities/
|
||||
Примеры:
|
||||
src/entities/
|
||||
├── product/ # Препарат
|
||||
│ ├── ui/
|
||||
│ │ └── product-card/ # карточка препарата (каталог, слайдеры, поиск)
|
||||
│ ├── types/
|
||||
│ │ └── product.type.ts # { id, name, mnn, indication }
|
||||
│ └── index.ts
|
||||
│
|
||||
├── disease/ # Заболевание
|
||||
│ ├── ui/
|
||||
│ │ └── disease-card/
|
||||
│ ├── types/
|
||||
│ │ └── disease.type.ts
|
||||
│ └── index.ts
|
||||
Отличие от shared/ui: entity-компонент знает о бизнес-домене (принимает Product, а не абстрактные пропсы). shared/ui Button не знает ничего о бизнесе.
|
||||
---
|
||||
7. Shared (src/shared/)
|
||||
Переиспользуемые компоненты, утилиты, стили без бизнес-логики.
|
||||
Критерий: компонент не знает о бизнес-домене, работает с абстрактными данными? → shared/
|
||||
src/shared/
|
||||
├── ui/ # UI-компоненты
|
||||
│ ├── carousel/ # принимает children, не знает о препаратах
|
||||
│ ├── container/
|
||||
│ ├── section/
|
||||
│ └── icon-svg/
|
||||
├── styles/ # CSS-переменные, media
|
||||
│ ├── variables.css
|
||||
│ └── media.css
|
||||
├── sprites/ # SVG-спрайты
|
||||
└── lib/ # утилиты, хелперы
|
||||
---
|
||||
Сводная таблица принятия решений
|
||||
Вопрос Да → Нет ↓
|
||||
Это точка входа маршрута? pages/ ↓
|
||||
Одинаков на всех страницах layout? layouts/{name}/ui/ ↓
|
||||
Используется только на одной странице? screens/{name}/ui/ ↓
|
||||
Составной блок с данными на 2+ страницах? widgets/ ↓
|
||||
Это действие пользователя с логикой? features/ ↓
|
||||
Привязан к бизнес-сущности? entities/ ↓
|
||||
Абстрактный UI без бизнес-логики? shared/ui/ —
|
||||
## Триггеры: классификация и расширение
|
||||
|
||||
Текущий список триггеров слабо проработан. Нужно:
|
||||
|
||||
И еще размышлений
|
||||
1. Классифицировать триггеры по группам:
|
||||
- Создание — новые модули, компоненты, страницы
|
||||
- Ресурсы — ассеты (иконки, шрифты, изображения, видео)
|
||||
- Данные — API, сторы, серверные данные, формы
|
||||
- Навигация — роутинг, middleware, редиректы
|
||||
- Модификация — рефакторинг, перенос, удаление
|
||||
- Инфраструктура — зависимости, переводы, настройка окружения
|
||||
|
||||
2. Добавить недостающие триггеры. Примеры пробелов:
|
||||
- Создание: утилита/хелпер, тип/интерфейс, контекст
|
||||
- Данные: создать форму, добавить валидацию
|
||||
- Навигация: динамический роут, middleware, редирект
|
||||
- Модификация: рефакторинг компонента, перенос модуля, удаление модуля
|
||||
- Обработка ошибок: error boundary, fallback UI, error.tsx, not-found.tsx, loading.tsx
|
||||
- Авторизация: защита страницы, проверка прав
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Что у нас по факту
|
||||
Мы взяли FSD и добавили:
|
||||
- Слой Layouts — каркас страницы
|
||||
- Слой Screens — контент страницы с локальными компонентами
|
||||
- Правило scope — компонент живёт максимально близко к месту использования, и поднимается на уровень выше только при переиспользовании
|
||||
Это не FSD в чистом виде. Но и не что-то принципиально новое.
|
||||
Существующие названия
|
||||
Feature-Sliced Design (FSD) — то от чего отталкиваемся, но расходимся в деталях.
|
||||
Screaming Architecture (Robert C. Martin) — структура проекта "кричит" о том, что он делает. Открываешь screens/knv/ui/ — видишь КНВ. Открываешь widgets/ — видишь глобальное. Это близко к нашему подходу.
|
||||
Colocation Principle — держи код рядом с тем, где он используется. Именно этот принцип отличает нас от FSD: page-specific компоненты лежат внутри screen, а не в глобальном widgets/.
|
||||
Как назвать
|
||||
Я бы не стал придумывать новое название. Это:
|
||||
> FSD с принципом колокации (FSD + Colocation)
|
||||
Или проще — адаптированный FSD. Суть отличия укладывается в одно правило:
|
||||
> Компонент живёт на самом низком уровне, где он используется. Поднимается выше только при переиспользовании на 2+ страницах.
|
||||
Если хочется краткое название для внутренней документации — можно SLD (Scoped Layer Design), подчёркивая что каждый компонент привязан к scope (shared → entity → feature → widget → screen → layout → page).
|
||||
3. Обновить секцию "Триггеры" в DEVELOP.md — перейти на новые группы.
|
||||
|
||||
532
package-lock.json
generated
532
package-lock.json
generated
@@ -1,14 +1,13 @@
|
||||
{
|
||||
"name": "nextjs-style-guide",
|
||||
"name": "frontend-style-guide",
|
||||
"version": "0.0.0",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "nextjs-style-guide",
|
||||
"name": "frontend-style-guide",
|
||||
"version": "0.0.0",
|
||||
"devDependencies": {
|
||||
"tsx": "^4.19.2",
|
||||
"vitepress": "^1.6.3"
|
||||
}
|
||||
},
|
||||
@@ -644,23 +643,6 @@
|
||||
"node": ">=12"
|
||||
}
|
||||
},
|
||||
"node_modules/@esbuild/netbsd-arm64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.7.tgz",
|
||||
"integrity": "sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==",
|
||||
"cpu": [
|
||||
"arm64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"netbsd"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/@esbuild/netbsd-x64": {
|
||||
"version": "0.21.5",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.21.5.tgz",
|
||||
@@ -678,23 +660,6 @@
|
||||
"node": ">=12"
|
||||
}
|
||||
},
|
||||
"node_modules/@esbuild/openbsd-arm64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.7.tgz",
|
||||
"integrity": "sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==",
|
||||
"cpu": [
|
||||
"arm64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"openbsd"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/@esbuild/openbsd-x64": {
|
||||
"version": "0.21.5",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.21.5.tgz",
|
||||
@@ -712,23 +677,6 @@
|
||||
"node": ">=12"
|
||||
}
|
||||
},
|
||||
"node_modules/@esbuild/openharmony-arm64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.7.tgz",
|
||||
"integrity": "sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==",
|
||||
"cpu": [
|
||||
"arm64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"openharmony"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/@esbuild/sunos-x64": {
|
||||
"version": "0.21.5",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.21.5.tgz",
|
||||
@@ -1711,19 +1659,6 @@
|
||||
"node": "^8.16.0 || ^10.6.0 || >=11.0.0"
|
||||
}
|
||||
},
|
||||
"node_modules/get-tsconfig": {
|
||||
"version": "4.14.0",
|
||||
"resolved": "https://registry.npmjs.org/get-tsconfig/-/get-tsconfig-4.14.0.tgz",
|
||||
"integrity": "sha512-yTb+8DXzDREzgvYmh6s9vHsSVCHeC0G3PI5bEXNBHtmshPnO+S5O7qgLEOn0I5QvMy6kpZN8K1NKGyilLb93wA==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"resolve-pkg-maps": "^1.0.0"
|
||||
},
|
||||
"funding": {
|
||||
"url": "https://github.com/privatenumber/get-tsconfig?sponsor=1"
|
||||
}
|
||||
},
|
||||
"node_modules/hast-util-to-html": {
|
||||
"version": "9.0.5",
|
||||
"resolved": "https://registry.npmjs.org/hast-util-to-html/-/hast-util-to-html-9.0.5.tgz",
|
||||
@@ -2153,16 +2088,6 @@
|
||||
"dev": true,
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/resolve-pkg-maps": {
|
||||
"version": "1.0.0",
|
||||
"resolved": "https://registry.npmjs.org/resolve-pkg-maps/-/resolve-pkg-maps-1.0.0.tgz",
|
||||
"integrity": "sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"funding": {
|
||||
"url": "https://github.com/privatenumber/resolve-pkg-maps?sponsor=1"
|
||||
}
|
||||
},
|
||||
"node_modules/rfdc": {
|
||||
"version": "1.4.1",
|
||||
"resolved": "https://registry.npmjs.org/rfdc/-/rfdc-1.4.1.tgz",
|
||||
@@ -2323,459 +2248,6 @@
|
||||
"url": "https://github.com/sponsors/wooorm"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx": {
|
||||
"version": "4.21.0",
|
||||
"resolved": "https://registry.npmjs.org/tsx/-/tsx-4.21.0.tgz",
|
||||
"integrity": "sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"esbuild": "~0.27.0",
|
||||
"get-tsconfig": "^4.7.5"
|
||||
},
|
||||
"bin": {
|
||||
"tsx": "dist/cli.mjs"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=18.0.0"
|
||||
},
|
||||
"optionalDependencies": {
|
||||
"fsevents": "~2.3.3"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/aix-ppc64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.7.tgz",
|
||||
"integrity": "sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==",
|
||||
"cpu": [
|
||||
"ppc64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"aix"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/android-arm": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.7.tgz",
|
||||
"integrity": "sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==",
|
||||
"cpu": [
|
||||
"arm"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"android"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/android-arm64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.7.tgz",
|
||||
"integrity": "sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==",
|
||||
"cpu": [
|
||||
"arm64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"android"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/android-x64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.7.tgz",
|
||||
"integrity": "sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==",
|
||||
"cpu": [
|
||||
"x64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"android"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/darwin-arm64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.7.tgz",
|
||||
"integrity": "sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==",
|
||||
"cpu": [
|
||||
"arm64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"darwin"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/darwin-x64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.7.tgz",
|
||||
"integrity": "sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==",
|
||||
"cpu": [
|
||||
"x64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"darwin"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/freebsd-arm64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.7.tgz",
|
||||
"integrity": "sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==",
|
||||
"cpu": [
|
||||
"arm64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"freebsd"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/freebsd-x64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.7.tgz",
|
||||
"integrity": "sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==",
|
||||
"cpu": [
|
||||
"x64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"freebsd"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/linux-arm": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.7.tgz",
|
||||
"integrity": "sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==",
|
||||
"cpu": [
|
||||
"arm"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"linux"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/linux-arm64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.7.tgz",
|
||||
"integrity": "sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==",
|
||||
"cpu": [
|
||||
"arm64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"linux"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/linux-ia32": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.7.tgz",
|
||||
"integrity": "sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==",
|
||||
"cpu": [
|
||||
"ia32"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"linux"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/linux-loong64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.7.tgz",
|
||||
"integrity": "sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==",
|
||||
"cpu": [
|
||||
"loong64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"linux"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/linux-mips64el": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.7.tgz",
|
||||
"integrity": "sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==",
|
||||
"cpu": [
|
||||
"mips64el"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"linux"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/linux-ppc64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.7.tgz",
|
||||
"integrity": "sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==",
|
||||
"cpu": [
|
||||
"ppc64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"linux"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/linux-riscv64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.7.tgz",
|
||||
"integrity": "sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==",
|
||||
"cpu": [
|
||||
"riscv64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"linux"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/linux-s390x": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.7.tgz",
|
||||
"integrity": "sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==",
|
||||
"cpu": [
|
||||
"s390x"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"linux"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/linux-x64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.7.tgz",
|
||||
"integrity": "sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==",
|
||||
"cpu": [
|
||||
"x64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"linux"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/netbsd-x64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.7.tgz",
|
||||
"integrity": "sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==",
|
||||
"cpu": [
|
||||
"x64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"netbsd"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/openbsd-x64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.7.tgz",
|
||||
"integrity": "sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==",
|
||||
"cpu": [
|
||||
"x64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"openbsd"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/sunos-x64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.7.tgz",
|
||||
"integrity": "sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==",
|
||||
"cpu": [
|
||||
"x64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"sunos"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/win32-arm64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.7.tgz",
|
||||
"integrity": "sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==",
|
||||
"cpu": [
|
||||
"arm64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"win32"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/win32-ia32": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.7.tgz",
|
||||
"integrity": "sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==",
|
||||
"cpu": [
|
||||
"ia32"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"win32"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/@esbuild/win32-x64": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.7.tgz",
|
||||
"integrity": "sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==",
|
||||
"cpu": [
|
||||
"x64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
"win32"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
},
|
||||
"node_modules/tsx/node_modules/esbuild": {
|
||||
"version": "0.27.7",
|
||||
"resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.7.tgz",
|
||||
"integrity": "sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==",
|
||||
"dev": true,
|
||||
"hasInstallScript": true,
|
||||
"license": "MIT",
|
||||
"bin": {
|
||||
"esbuild": "bin/esbuild"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
},
|
||||
"optionalDependencies": {
|
||||
"@esbuild/aix-ppc64": "0.27.7",
|
||||
"@esbuild/android-arm": "0.27.7",
|
||||
"@esbuild/android-arm64": "0.27.7",
|
||||
"@esbuild/android-x64": "0.27.7",
|
||||
"@esbuild/darwin-arm64": "0.27.7",
|
||||
"@esbuild/darwin-x64": "0.27.7",
|
||||
"@esbuild/freebsd-arm64": "0.27.7",
|
||||
"@esbuild/freebsd-x64": "0.27.7",
|
||||
"@esbuild/linux-arm": "0.27.7",
|
||||
"@esbuild/linux-arm64": "0.27.7",
|
||||
"@esbuild/linux-ia32": "0.27.7",
|
||||
"@esbuild/linux-loong64": "0.27.7",
|
||||
"@esbuild/linux-mips64el": "0.27.7",
|
||||
"@esbuild/linux-ppc64": "0.27.7",
|
||||
"@esbuild/linux-riscv64": "0.27.7",
|
||||
"@esbuild/linux-s390x": "0.27.7",
|
||||
"@esbuild/linux-x64": "0.27.7",
|
||||
"@esbuild/netbsd-arm64": "0.27.7",
|
||||
"@esbuild/netbsd-x64": "0.27.7",
|
||||
"@esbuild/openbsd-arm64": "0.27.7",
|
||||
"@esbuild/openbsd-x64": "0.27.7",
|
||||
"@esbuild/openharmony-arm64": "0.27.7",
|
||||
"@esbuild/sunos-x64": "0.27.7",
|
||||
"@esbuild/win32-arm64": "0.27.7",
|
||||
"@esbuild/win32-ia32": "0.27.7",
|
||||
"@esbuild/win32-x64": "0.27.7"
|
||||
}
|
||||
},
|
||||
"node_modules/unist-util-position": {
|
||||
"version": "5.0.0",
|
||||
"resolved": "https://registry.npmjs.org/unist-util-position/-/unist-util-position-5.0.0.tgz",
|
||||
|
||||
@@ -1,17 +1,16 @@
|
||||
{
|
||||
"name": "nextjs-style-guide",
|
||||
"name": "frontend-style-guide",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"version": "0.0.0",
|
||||
"scripts": {
|
||||
"llms": "tsx ./generate-llms.ts",
|
||||
"build:ai": "node ./scripts/build-ai.js",
|
||||
"dev": "vitepress dev .",
|
||||
"build": "vitepress build .",
|
||||
"serve": "vitepress serve ."
|
||||
},
|
||||
"dependencies": {},
|
||||
"devDependencies": {
|
||||
"tsx": "^4.19.2",
|
||||
"vitepress": "^1.6.3"
|
||||
}
|
||||
}
|
||||
|
||||
88
scripts/build-ai.js
Normal file
88
scripts/build-ai.js
Normal file
@@ -0,0 +1,88 @@
|
||||
import fs from "fs";
|
||||
import path from "path";
|
||||
import { pathToFileURL } from "url";
|
||||
|
||||
const SRC_DIR = "./src";
|
||||
const DIST_DIR = "./dist/ai";
|
||||
const SCRIPTS_DIR = "./scripts";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Сборка по манифесту
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
async function buildForFramework(framework) {
|
||||
const manifestPath = path.join(SCRIPTS_DIR, `${framework}.build.js`);
|
||||
|
||||
if (!fs.existsSync(manifestPath)) {
|
||||
console.error(`Манифест не найден: ${manifestPath}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const manifest = (await import(pathToFileURL(path.resolve(manifestPath)).href)).default;
|
||||
const outDir = path.join(DIST_DIR, framework);
|
||||
|
||||
// Очищаем выходную директорию
|
||||
if (fs.existsSync(outDir)) {
|
||||
fs.rmSync(outDir, { recursive: true, force: true });
|
||||
}
|
||||
|
||||
console.log(`\nСборка: ${manifest.name} (${framework})`);
|
||||
console.log(`Выход: ${outDir}\n`);
|
||||
|
||||
const errors = [];
|
||||
let count = 0;
|
||||
|
||||
for (const [destRelative, srcRelative] of Object.entries(manifest.files)) {
|
||||
const srcPath = path.join(SRC_DIR, srcRelative);
|
||||
const destPath = path.join(outDir, destRelative);
|
||||
|
||||
if (!fs.existsSync(srcPath)) {
|
||||
errors.push(` [!] Не найден: ${srcRelative}`);
|
||||
continue;
|
||||
}
|
||||
|
||||
fs.mkdirSync(path.dirname(destPath), { recursive: true });
|
||||
fs.copyFileSync(srcPath, destPath);
|
||||
console.log(` ${destRelative}`);
|
||||
count++;
|
||||
}
|
||||
|
||||
if (errors.length > 0) {
|
||||
console.log(`\nОшибки:`);
|
||||
errors.forEach((e) => console.log(e));
|
||||
}
|
||||
|
||||
console.log(`\nГотово: ${outDir} (${count} файлов)`);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Определяем что собирать
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
let frameworks = fs
|
||||
.readdirSync(SCRIPTS_DIR)
|
||||
.filter((f) => f.endsWith(".build.js"))
|
||||
.map((f) => f.replace(".build.js", ""));
|
||||
|
||||
if (frameworks.length === 0) {
|
||||
console.error("Не найдено ни одного манифеста *.build.js в scripts/");
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// --framework=nextjs
|
||||
const fwArg = process.argv.find((a) => a.startsWith("--framework="));
|
||||
if (fwArg) {
|
||||
const fw = fwArg.split("=")[1];
|
||||
if (frameworks.includes(fw)) {
|
||||
frameworks = [fw];
|
||||
} else {
|
||||
console.error(`Фреймворк "${fw}" не найден. Доступные: ${frameworks.join(", ")}`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
for (const fw of frameworks) {
|
||||
await buildForFramework(fw);
|
||||
}
|
||||
|
||||
console.log("\nВсе сборки завершены.");
|
||||
69
scripts/nextjs.build.js
Normal file
69
scripts/nextjs.build.js
Normal file
@@ -0,0 +1,69 @@
|
||||
/**
|
||||
* Манифест сборки стайлгайда для Next.js.
|
||||
*
|
||||
* Ключ — путь файла в dist/ai/nextjs/.
|
||||
* Значение — путь исходника относительно src/.
|
||||
*
|
||||
* Скрипт только копирует. Никакой генерации.
|
||||
*/
|
||||
export default {
|
||||
name: "Next.js",
|
||||
|
||||
files: {
|
||||
// ── Точки входа ─────────────────────────────────────────────
|
||||
"DEVELOP.md": "nextjs/DEVELOP.md",
|
||||
|
||||
// ── Базовые правила ─────────────────────────────────────────
|
||||
"basics/architecture.md": "base/basics/architecture.md",
|
||||
"basics/code-style.md": "base/basics/code-style.md",
|
||||
"basics/documentation.md": "base/basics/documentation.md",
|
||||
"basics/naming.md": "base/basics/naming.md",
|
||||
"basics/tech-stack.md": "base/basics/tech-stack.md",
|
||||
"basics/typing.md": "base/basics/typing.md",
|
||||
|
||||
// ── Прикладные разделы ──────────────────────────────────────
|
||||
"applied/components.md": "base/applied/components.md",
|
||||
"applied/styles.md": "base/applied/styles.md",
|
||||
"applied/templates-generation.md": "base/applied/templates-generation.md",
|
||||
"applied/hooks.md": "base/applied/hooks.md",
|
||||
"applied/stores.md": "base/applied/stores.md",
|
||||
"applied/api.md": "base/applied/api.md",
|
||||
"applied/fonts.md": "base/applied/fonts.md",
|
||||
"applied/localization.md": "base/applied/localization.md",
|
||||
"applied/images-sprites.md": "base/applied/images-sprites.md",
|
||||
"applied/svg-sprites.md": "base/applied/svg-sprites.md",
|
||||
"applied/video.md": "base/applied/video.md",
|
||||
"applied/vscode.md": "base/applied/vscode.md",
|
||||
"applied/page-level.md": "nextjs/applied/page-level.md",
|
||||
"applied/project-structure.md": "nextjs/applied/project-structure.md",
|
||||
|
||||
// ── Триггеры: разработка / создание ─────────────────────────
|
||||
"triggers/develop/create-component.md": "base/triggers/develop/create-component.md",
|
||||
"triggers/develop/create-feature.md": "base/triggers/develop/create-feature.md",
|
||||
"triggers/develop/create-widget.md": "base/triggers/develop/create-widget.md",
|
||||
"triggers/develop/create-entity.md": "base/triggers/develop/create-entity.md",
|
||||
"triggers/develop/create-hook.md": "base/triggers/develop/create-hook.md",
|
||||
"triggers/develop/create-store.md": "base/triggers/develop/create-store.md",
|
||||
"triggers/develop/create-page.md": "nextjs/triggers/develop/create-page.md",
|
||||
"triggers/develop/create-layout.md": "nextjs/triggers/develop/create-layout.md",
|
||||
"triggers/develop/create-project.md": "nextjs/triggers/develop/create-project.md",
|
||||
"triggers/develop/generate-module.md": "base/triggers/develop/generate-module.md",
|
||||
|
||||
// ── Триггеры: разработка / стилизация и ресурсы ─────────────
|
||||
"triggers/develop/style-component.md": "base/triggers/develop/style-component.md",
|
||||
"triggers/develop/add-icon.md": "base/triggers/develop/add-icon.md",
|
||||
"triggers/develop/add-image.md": "base/triggers/develop/add-image.md",
|
||||
"triggers/develop/add-video.md": "base/triggers/develop/add-video.md",
|
||||
"triggers/develop/add-font.md": "base/triggers/develop/add-font.md",
|
||||
|
||||
// ── Триггеры: разработка / данные и состояние ───────────────
|
||||
"triggers/develop/add-api-request.md": "base/triggers/develop/add-api-request.md",
|
||||
"triggers/develop/connect-store.md": "base/triggers/develop/connect-store.md",
|
||||
"triggers/develop/add-server-data.md": "nextjs/triggers/develop/add-server-data.md",
|
||||
|
||||
// ── Триггеры: разработка / инфраструктура ───────────────────
|
||||
"triggers/develop/add-localization.md": "base/triggers/develop/add-localization.md",
|
||||
"triggers/develop/add-dependency.md": "base/triggers/develop/add-dependency.md",
|
||||
"triggers/develop/setup-vscode.md": "base/triggers/develop/setup-vscode.md",
|
||||
},
|
||||
};
|
||||
5
src/base/applied/api.md
Normal file
5
src/base/applied/api.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
scope: applied
|
||||
keywords: [api, запрос, fetch, SWR, эндпоинт, REST, клиент]
|
||||
when: "Работа с API: запросы, клиенты, обработка ответов"
|
||||
---
|
||||
@@ -1,12 +1,14 @@
|
||||
---
|
||||
title: Компоненты
|
||||
scope: applied
|
||||
keywords: [компонент, props, jsx, ui, clsx, cl, React, FC]
|
||||
when: "Создание или редактирование React-компонентов: структура, пропсы, стили"
|
||||
---
|
||||
|
||||
# Компоненты
|
||||
|
||||
Правила написания React-компонентов: файловая структура модуля, типизация пропсов, документирование и реализация. Раздел охватывает компоненты всех слоёв — от `shared/ui` до `screens`.
|
||||
|
||||
Архитектурные слои и их назначение описаны в разделе [Архитектура](/docs/basics/architecture/).
|
||||
Архитектурные слои и их назначение описаны в разделе [Архитектура](/basics/architecture).
|
||||
|
||||
|
||||
## Правила организации
|
||||
@@ -43,7 +45,7 @@ container/
|
||||
- **`type` вместо `interface`** — гибче для пропсов: поддерживает union, intersection, mapped types. Declaration merging пропсам не нужно.
|
||||
- **Без `FC`** — неявно добавляет `children`, усложняет дженерики, не даёт преимуществ перед аннотацией параметра.
|
||||
- **Типы в `types/`, а не в `.tsx`** — предотвращает циклические зависимости (компонент импортирует хук, хук импортирует тип из компонента) и разделяет ответственность: `.tsx` для рендера, `.type.ts` для данных.
|
||||
- **Без возвращаемого типа** — TypeScript выводит из JSX. Осознанное исключение из [базового правила](/docs/basics/typing).
|
||||
- **Без возвращаемого типа** — TypeScript выводит из JSX. Осознанное исключение из [базового правила](/basics/typing).
|
||||
|
||||
## Реализация
|
||||
|
||||
@@ -110,3 +112,7 @@ export const Container = (props: ContainerProps) => {
|
||||
```ts
|
||||
export { Container } from './container'
|
||||
```
|
||||
|
||||
## Дочерние компоненты
|
||||
|
||||
Если модулю нужны внутренние подкомпоненты — генерировать их из шаблона `component` в папку `ui/` внутри родительского модуля. Дочерние компоненты не экспортируются через `index.ts` родителя.
|
||||
5
src/base/applied/fonts.md
Normal file
5
src/base/applied/fonts.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
scope: applied
|
||||
keywords: [шрифт, font, next/font, подключение шрифта, woff]
|
||||
when: "Подключение и настройка шрифтов"
|
||||
---
|
||||
5
src/base/applied/hooks.md
Normal file
5
src/base/applied/hooks.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
scope: applied
|
||||
keywords: [хук, hook, use, кастомный хук, useState, useEffect]
|
||||
when: "Создание или использование кастомных хуков"
|
||||
---
|
||||
5
src/base/applied/images-sprites.md
Normal file
5
src/base/applied/images-sprites.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
scope: applied
|
||||
keywords: [изображение, картинка, image, next/image, public, оптимизация]
|
||||
when: "Работа с изображениями: подключение, оптимизация"
|
||||
---
|
||||
5
src/base/applied/localization.md
Normal file
5
src/base/applied/localization.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
scope: applied
|
||||
keywords: [i18n, локализация, перевод, язык, i18next, namespace]
|
||||
when: "Локализация: добавление переводов, работа с i18next"
|
||||
---
|
||||
5
src/base/applied/stores.md
Normal file
5
src/base/applied/stores.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
scope: applied
|
||||
keywords: [стор, store, zustand, состояние, глобальное состояние]
|
||||
when: "Работа с глобальным состоянием: создание стора, подписка"
|
||||
---
|
||||
@@ -1,10 +1,12 @@
|
||||
---
|
||||
title: Использование
|
||||
title: Стили
|
||||
scope: applied
|
||||
keywords: [css, postcss, модули, css modules, токены, медиа-запросы, вложенность, класс]
|
||||
when: "Стилизация: CSS Modules, PostCSS, переменные, медиа-запросы"
|
||||
---
|
||||
# Стили
|
||||
|
||||
# Использование
|
||||
|
||||
Правила написания CSS: PostCSS Modules, форматирование, переменные. Установка и настройка процессора — [PostCSS](/docs/applied/styles/postcss).
|
||||
Раздел описывает правила написания CSS: PostCSS Modules, вложенность, медиа-запросы, переменные, форматирование.
|
||||
|
||||
## Общие правила
|
||||
|
||||
@@ -267,3 +269,17 @@ title: Использование
|
||||
|
||||
- Желательно не писать комментарии в CSS.
|
||||
- Исключение — нетривиальные хаки и обходные решения, к которым стоит оставить пояснение.
|
||||
|
||||
## Приоритет стилизации
|
||||
|
||||
Основной UI-фреймворк проекта — **Mantine**. При стилизации компонентов придерживаться следующего приоритета:
|
||||
|
||||
1. **Mantine-компоненты и их пропсы** — в первую очередь использовать встроенные возможности Mantine (пропсы, `classNames`, `styles`).
|
||||
2. **Глобальные CSS-токены** (`--color-*`, `--space-*`, `--radius-*`) — для значений, которые не покрываются Mantine.
|
||||
3. **PostCSS Modules** — когда Mantine не покрывает задачу и нужна кастомная стилизация.
|
||||
|
||||
## Что запрещено
|
||||
|
||||
- **Инлайн-стили** — использование атрибута `style` в компонентах строго запрещено.
|
||||
- **Магические значения** — произвольные цвета, отступы и скругления запрещены, использовать токены.
|
||||
- **Глобальные стили** вне `app/styles/` запрещены.
|
||||
7
src/base/applied/svg-sprites.md
Normal file
7
src/base/applied/svg-sprites.md
Normal file
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: SVG-спрайты
|
||||
scope: applied
|
||||
keywords: [svg, спрайт, иконка, icon, sprite]
|
||||
when: "Работа с SVG-иконками и спрайтами"
|
||||
---
|
||||
# SVG-спрайты
|
||||
@@ -1,7 +1,9 @@
|
||||
---
|
||||
title: Шаблоны и генерация кода
|
||||
scope: applied
|
||||
keywords: [шаблон, генерация, template, scaffold, plop, hygen, .templates]
|
||||
when: "Генерация кода из шаблонов, создание новых шаблонов"
|
||||
---
|
||||
|
||||
<!-- @formatter:off -->
|
||||
::: v-pre
|
||||
|
||||
@@ -146,10 +148,28 @@ npx @gromlab/create <шаблон> <имя> <путь>
|
||||
| Команда | Что создаёт |
|
||||
|---|---|
|
||||
| `npx @gromlab/create component button src/shared/ui` | Компонент |
|
||||
| `npx @gromlab/create module auth src/business` | Бизнес-модуль |
|
||||
| `npx @gromlab/create feature auth src/features` | Фичу |
|
||||
| `npx @gromlab/create widget header src/widgets` | Виджет |
|
||||
| `npx @gromlab/create entity user src/entities` | Сущность |
|
||||
| `npx @gromlab/create layout admin src/layouts` | Layout |
|
||||
| `npx @gromlab/create store auth src/business/auth/stores` | Стор |
|
||||
| `npx @gromlab/create store auth src/shared/model` | Стор |
|
||||
|
||||
:::
|
||||
|
||||
## Какие модули генерируются из шаблонов
|
||||
|
||||
| Модуль | Слой | Шаблон |
|
||||
|---|---|---|
|
||||
| Компонент | `shared/ui/` | `component` |
|
||||
| Фича | `features/` | `feature` |
|
||||
| Виджет | `widgets/` | `widget` |
|
||||
| Сущность | `entities/` | `entity` |
|
||||
| Layout | `layouts/` | `layout` |
|
||||
| Экран | `screens/` | `screen` |
|
||||
| Стор | `model/` | `store` |
|
||||
|
||||
## Когда создавать новый шаблон
|
||||
|
||||
- Повторяющаяся структура появляется больше одного раза.
|
||||
- Существующий шаблон не покрывает нужный тип модуля.
|
||||
|
||||
5
src/base/applied/video.md
Normal file
5
src/base/applied/video.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
scope: applied
|
||||
keywords: [видео, video, плеер, mp4]
|
||||
when: "Встраивание и работа с видео"
|
||||
---
|
||||
@@ -1,7 +1,9 @@
|
||||
---
|
||||
title: Настройка VS Code
|
||||
scope: applied
|
||||
keywords: [vscode, редактор, расширение, настройка, extension, .vscode]
|
||||
when: "Настройка VS Code: расширения, settings.json, сниппеты"
|
||||
---
|
||||
|
||||
# Настройка VS Code
|
||||
|
||||
Каждый проект содержит папку `.vscode/` с конфигурацией редактора. Это гарантирует, что все участники команды работают с одинаковыми настройками форматирования, линтинга и расширениями.
|
||||
665
src/base/basics/architecture.md
Normal file
665
src/base/basics/architecture.md
Normal file
@@ -0,0 +1,665 @@
|
||||
---
|
||||
title: Архитектура
|
||||
scope: basics
|
||||
keywords: [SLM Design, слой, модуль, сегмент, архитектура, FSD, scoped layered module]
|
||||
when: "Организация кода: слои, модули, зависимости между модулями"
|
||||
---
|
||||
|
||||
<!-- /index -->
|
||||
# SLM Design
|
||||
Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.
|
||||
|
||||
## Преимущества
|
||||
|
||||
### Вертикальная организация домена
|
||||
|
||||
Бизнес-домен не разбивается по техническим слоям — сценарии, сущности, типы и UI живут в одном модуле. Это сокращает время навигации и упрощает сопровождение: все изменения домена локализованы.
|
||||
|
||||
### Dependency Injection без фреймворков
|
||||
|
||||
Cross-domain зависимости в бизнес-слое реализуются через фабрики — модуль декларирует что ему нужно, а точка использования предоставляет зависимости. Домены изолированы без DI-контейнеров, провайдеров и шин событий.
|
||||
|
||||
### Разделение ответственности без перегрузки слоёв
|
||||
|
||||
Сервисы приложения (`infrastructure/`), UI-кит (`ui/`) и общие ресурсы (`shared/`) — три разных слоя с разной природой. Ни один слой не превращается в свалку разнородного кода.
|
||||
|
||||
### Горизонтальная инкапсуляция
|
||||
|
||||
Вложенные модули (`parts/`) и направление зависимостей позволяют нескольким разработчикам работать над одной областью приложения параллельно, не затрагивая код друг друга.
|
||||
|
||||
### Колокация по умолчанию
|
||||
|
||||
Код начинает жизнь рядом с местом использования и поднимается в общие слои только при реальной потребности. Глобальные слои не засоряются преждевременными абстракциями.
|
||||
|
||||
### Явное разделение каркаса и контента
|
||||
|
||||
Каркас группы маршрутов (`layouts/`) и контент конкретной страницы (`screens/`) — независимые слои с собственной ответственностью.
|
||||
|
||||
### Масштабирование через группировку
|
||||
|
||||
При росте проекта слои не теряют структуру — модули группируются по естественным признакам: бизнес-домены по субдоменам, страницы по разделам, UI-компоненты по уровню абстракции (примитивы и композиции).
|
||||
|
||||
## Происхождение
|
||||
|
||||
SLM Design вырос на основе:
|
||||
|
||||
- **Feature-Sliced Design** — слоистая структура, публичный API модуля, направление зависимостей
|
||||
- **Vertical Slice Architecture** — модуль как вертикальный срез, содержащий всё необходимое
|
||||
- **Screaming Architecture** — структура проекта «кричит» о назначении: открыл `business/auth` — видишь авторизацию
|
||||
- **Colocation Principle** — код живёт рядом с местом использования
|
||||
|
||||
## Пример структуры проекта
|
||||
|
||||
```text
|
||||
src/
|
||||
├── app/
|
||||
│
|
||||
├── layouts/
|
||||
│ ├── main/
|
||||
│ └── dashboard/
|
||||
│
|
||||
├── screens/
|
||||
│ ├── home/
|
||||
│ ├── products/
|
||||
│ ├── product-detail/
|
||||
│ └── about/
|
||||
│
|
||||
├── widgets/
|
||||
│ ├── page-heading/
|
||||
│ ├── hero-section/
|
||||
│ └── promo-banner/
|
||||
│
|
||||
├── business/
|
||||
│ ├── auth/
|
||||
│ ├── catalog/
|
||||
│ ├── orders/
|
||||
│ └── chat/
|
||||
│
|
||||
├── infrastructure/
|
||||
│ ├── theme/
|
||||
│ ├── i18n/
|
||||
│ ├── backend-api/
|
||||
│ └── logger/
|
||||
│
|
||||
├── ui/
|
||||
│ ├── button/
|
||||
│ ├── input/
|
||||
│ ├── modal/
|
||||
│ ├── toast/
|
||||
│ └── dropdown/
|
||||
│
|
||||
└── shared/
|
||||
├── lib/
|
||||
├── types/
|
||||
└── styles/
|
||||
```
|
||||
|
||||
## Принципы
|
||||
|
||||
- **Домен — единое целое.** Всё, что относится к домену, живёт в одном модуле.
|
||||
- **Колокация.** Код рождается рядом с местом использования и поднимается только при необходимости.
|
||||
- **Зависимости однонаправлены.** Импорты только сверху вниз, только через публичный API.
|
||||
- **Архитектура — каркас, не клетка.** Правила фиксируют направление зависимостей и структуру модуля, остальное определяет команда.
|
||||
|
||||
<!-- /reference/layers -->
|
||||
## Слои
|
||||
|
||||
Раздел описывает слои SLM: что такое слой, какие бывают, как между ними направлены зависимости и какие правила действуют на каждом.
|
||||
|
||||
### Определение
|
||||
|
||||
**Слой — уровень организации кода внутри `src/`. Каждый слой отвечает за свою область (каркас страницы, бизнес-логика, UI-кит) и задаёт правила для кода внутри: направление импортов, именование, допустимые связи между модулями.**
|
||||
|
||||
### Группы слоёв
|
||||
|
||||
Слои делятся на три группы:
|
||||
|
||||
| Группа | Слои | Описание |
|
||||
|--------|------|----------|
|
||||
| Композиция | `app`, `layouts`, `screens`, `widgets` | Собирают интерфейс из готовых блоков: маршруты, каркасы, страницы |
|
||||
| Ядро | `business`, `infrastructure`, `ui` | Реализация продукта: бизнес-домены, техсервисы, UI-кит |
|
||||
| Фундамент | `shared` | Общие ресурсы: утилиты, хелперы, стили, конфиги |
|
||||
|
||||
### Направление зависимостей
|
||||
|
||||
Любой импорт между модулями — только через публичный API.
|
||||
|
||||
```
|
||||
app → [ layouts | screens ] → widgets → business → infrastructure → ui → shared
|
||||
```
|
||||
|
||||
- `layouts` и `screens` — параллельные слои, не импортируют друг друга
|
||||
- Модули одного слоя в группе «Композиция» изолированы друг от друга
|
||||
- Модули одного слоя `infrastructure` и `ui` могут импортировать друг друга через публичный API
|
||||
- Модули `business` — cross-domain зависимости по коду через фабрику, `import type` напрямую
|
||||
- Импорт типов (`import type`) в «Ядре» разрешён в обоих направлениях
|
||||
|
||||
|
||||
### Слой App
|
||||
|
||||
Точка входа приложения. Отвечает за запуск, роутинг и композицию маршрутов из layout и screen.
|
||||
|
||||
В отличие от остальных слоёв, `app/` не содержит модулей SLM. Здесь живут только инфраструктурные файлы, которые не могут быть никаким другим слоем: файлы фреймворка роутинга, точка запуска и код инициализации.
|
||||
|
||||
#### Требования
|
||||
|
||||
- Не содержит модулей SLM — только файлы фреймворка, роутинг, инициализация
|
||||
- Содержит: файлы маршрутов, bootstrap, обработку ошибок верхнего уровня (404, error boundary), подключение глобальных стилей и ассетов
|
||||
- Провайдеры и гарды — только подключает готовые из нижних слоёв, не реализует
|
||||
- Не содержит бизнес-логику, UI-компоненты, хуки, сторы, сервисы
|
||||
- Никем не импортируется
|
||||
|
||||
### Слой Layouts
|
||||
|
||||
Каркас страницы: общие элементы, одинаковые для группы маршрутов (header, footer, sidebar).
|
||||
|
||||
```text
|
||||
src/layouts/
|
||||
├── main/
|
||||
├── dashboard/
|
||||
└── auth/
|
||||
```
|
||||
|
||||
#### Требования
|
||||
|
||||
- Содержит только модули
|
||||
- Не содержит бизнес-логику
|
||||
- Контекстно-зависимые блоки принимает через пропсы от `app`, не импортирует напрямую
|
||||
|
||||
### Слой Screens
|
||||
|
||||
Контент конкретной страницы: собирает её из модулей нижних слоёв.
|
||||
|
||||
```text
|
||||
src/screens/
|
||||
├── home/
|
||||
├── products/
|
||||
├── product-detail/
|
||||
├── about/
|
||||
└── contacts/
|
||||
```
|
||||
|
||||
Когда количество страниц затрудняет навигацию — вводится группировка по разделам. Группа — папка для организации, не модуль (без `index.ts`).
|
||||
|
||||
```text
|
||||
src/screens/
|
||||
├── shop/
|
||||
│ ├── home/
|
||||
│ ├── products/
|
||||
│ ├── product-detail/
|
||||
│ └── cart/
|
||||
├── account/
|
||||
│ ├── profile/
|
||||
│ ├── settings/
|
||||
│ └── order-history/
|
||||
└── info/
|
||||
├── about/
|
||||
├── contacts/
|
||||
└── faq/
|
||||
```
|
||||
|
||||
#### Требования
|
||||
|
||||
- Содержит только модули
|
||||
- Не содержит бизнес-логику
|
||||
- Локальные одноразовые секции живут внутри screen-модуля, не выносятся в `widgets`/`business`
|
||||
|
||||
### Слой Widgets
|
||||
|
||||
Составной блок интерфейса, который компонует модули ядра, но не принадлежит конкретному бизнес-домену. Widget появляется когда блок используется в нескольких screens или layouts.
|
||||
|
||||
Если блок принадлежит домену — он живёт в `business/{area}/`, даже если переиспользуется. Если блок нужен только в одном месте — это `screens/{name}/parts/` или `layouts/{name}/parts/`, а не widget.
|
||||
|
||||
```text
|
||||
src/widgets/
|
||||
├── page-heading/
|
||||
├── hero-section/
|
||||
├── onboarding-checklist/
|
||||
├── promo-banner/
|
||||
└── error-boundary/
|
||||
```
|
||||
|
||||
#### Требования
|
||||
|
||||
- Не принадлежит конкретному бизнес-домену. Если блок доменный — он живёт в `business/`
|
||||
- Используется в нескольких screens или layouts
|
||||
|
||||
### Слой Business
|
||||
|
||||
Бизнес-домены приложения: auth, catalog, orders, checkout, chat. Каждый домен — отдельный модуль со своими типами, логикой, UI и сервисами.
|
||||
|
||||
Слой входит в группу «Ядро». Импортирует `infrastructure/`, `ui/`, `shared/`. Cross-domain зависимости по коду реализуются через фабрику. `import type` между доменами разрешён напрямую.
|
||||
|
||||
Business объединяет то, что в FSD разделено на `features` и `entities`: пользовательские сценарии и бизнес-сущности живут вместе, внутри одного домена. Внутри домена сегменты разделяют ответственность: `types/` — доменная модель, `hooks/` и `services/` — сценарии и логика, `mappers/` — трансформация данных, `parts/` — составные блоки.
|
||||
|
||||
```text
|
||||
src/business/
|
||||
├── auth/
|
||||
├── catalog/
|
||||
├── orders/
|
||||
├── checkout/
|
||||
└── chat/
|
||||
```
|
||||
|
||||
Когда количество доменов затрудняет навигацию — вводится группировка по субдоменам. Группа — папка для организации, не модуль (без `index.ts`).
|
||||
|
||||
```text
|
||||
src/business/
|
||||
├── commerce/
|
||||
│ ├── catalog/
|
||||
│ ├── cart/
|
||||
│ ├── orders/
|
||||
│ └── checkout/
|
||||
└── communication/
|
||||
├── chat/
|
||||
└── notifications/
|
||||
```
|
||||
|
||||
#### Требования
|
||||
|
||||
- Один модуль = один бизнес-домен
|
||||
- Циклические зависимости между доменами запрещены
|
||||
- Импорт кода между доменами — через фабрику. `import type` — напрямую
|
||||
- Доменные типы (`User`, `Product`) живут здесь, не в `shared/`
|
||||
|
||||
### Слой Infrastructure
|
||||
|
||||
Техсервисы приложения: theme, i18n, API-адаптеры, logger, realtime. Каждый сервис — отдельный модуль.
|
||||
|
||||
Слой входит в группу «Ядро». Импортирует `infrastructure/`, `ui/`, `shared/`.
|
||||
|
||||
Отличие от `shared/`: infrastructure — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
|
||||
|
||||
```text
|
||||
src/infrastructure/
|
||||
├── theme/
|
||||
├── i18n/
|
||||
├── backend-api/
|
||||
├── maps-api/
|
||||
├── logger/
|
||||
├── feature-flags/
|
||||
└── realtime/
|
||||
```
|
||||
|
||||
#### Требования
|
||||
|
||||
- Один модуль = один техсервис
|
||||
- Импортирует `infrastructure/`, `ui/`, `shared/`
|
||||
|
||||
### Слой UI
|
||||
|
||||
UI-кит без бизнес-логики: button, carousel, toast, modal.
|
||||
|
||||
Слой входит в группу «Ядро». Импортирует `ui/` и `shared/`.
|
||||
|
||||
Компоненты строятся друг на друге: `button` использует `icon`, `carousel` использует `button`.
|
||||
|
||||
```text
|
||||
src/ui/
|
||||
├── button/
|
||||
├── input/
|
||||
├── icon/
|
||||
├── carousel/
|
||||
├── modal/
|
||||
├── toast/
|
||||
├── dropdown/
|
||||
├── tabs/
|
||||
└── tooltip/
|
||||
```
|
||||
|
||||
Когда количество компонентов затрудняет навигацию — вводится группировка на примитивы и композиции. Примитивы (`button`, `icon`, `input`) не импортируют композиции. Композиции (`carousel`, `modal`, `dropdown`) строятся на примитивах.
|
||||
|
||||
```text
|
||||
src/ui/
|
||||
├── primitives/
|
||||
│ ├── button/
|
||||
│ ├── input/
|
||||
│ ├── icon/
|
||||
│ └── badge/
|
||||
└── composites/
|
||||
├── carousel/
|
||||
├── modal/
|
||||
├── dropdown/
|
||||
├── tabs/
|
||||
└── tooltip/
|
||||
```
|
||||
|
||||
#### Требования
|
||||
|
||||
- Не содержит бизнес-логику
|
||||
- Импортирует только `ui/` и `shared/`
|
||||
|
||||
### Слой Shared
|
||||
|
||||
Общие ресурсы: утилиты, хелперы, стили, конфиги. Не знает о бизнес-домене.
|
||||
|
||||
Слой входит в группу «Фундамент» — ни о ком не знает, никого не импортирует.
|
||||
|
||||
Отличие от `infrastructure/`: infrastructure — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
|
||||
|
||||
Отличие от `ui/`: UI-компоненты (button, carousel, modal) живут в слое `ui/`, а не здесь.
|
||||
|
||||
```text
|
||||
src/shared/
|
||||
├── lib/
|
||||
├── types/
|
||||
├── styles/
|
||||
└── sprites/
|
||||
```
|
||||
|
||||
#### Требования
|
||||
|
||||
- Не имеет runtime-состояния
|
||||
|
||||
<!-- /reference/modules -->
|
||||
## Модули
|
||||
|
||||
Раздел описывает модули SLM: что такое модуль, из чего он состоит и как взаимодействует с остальным кодом.
|
||||
|
||||
### Определение
|
||||
|
||||
**Модуль — универсальный строительный блок архитектуры. Живёт на слое и содержит всё необходимое для своей работы: компоненты, хуки, сторы, сервисы, типы, стили. Набор содержимого не фиксирован — включаются только нужные части.**
|
||||
|
||||
### Модуль vs компонент
|
||||
|
||||
**Компонент** — один `.tsx` файл. Не имеет своих сегментов, использует сегменты родительского модуля. Живёт в корне или `ui/` сегменте модуля.
|
||||
|
||||
**Модуль** — папка, которая может содержать корневой компонент, сегменты (`hooks/`, `types/`, `styles/`, `ui/`, `parts/` и т.д.) и публичный API (`index.ts`).
|
||||
|
||||
```text
|
||||
auth/
|
||||
├── ui/
|
||||
│ ├── auth-guard.tsx
|
||||
│ └── logout-button.tsx
|
||||
├── parts/
|
||||
│ ├── login-form/
|
||||
│ ├── registration-form/
|
||||
│ └── restore-form/
|
||||
├── hooks/
|
||||
├── stores/
|
||||
├── types/
|
||||
├── auth.tsx # корневой компонент (опционален)
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
### Структура
|
||||
|
||||
Модуль состоит из сегментов. Ни один сегмент не обязателен — модуль может состоять даже из одного `index.ts` с реэкспортом типов.
|
||||
|
||||
```text
|
||||
{module-name}/
|
||||
├── {module-name}.tsx # корневой компонент (опционален)
|
||||
├── ui/ # компоненты модуля (только .tsx)
|
||||
├── parts/ # вложенные модули (со своими сегментами)
|
||||
├── hooks/ # хуки
|
||||
├── stores/ # сторы состояния
|
||||
├── services/ # внешние источники данных
|
||||
├── mappers/ # трансформация данных между форматами
|
||||
├── types/ # типы
|
||||
├── styles/ # стили
|
||||
├── lib/ # утилиты модуля
|
||||
├── config/ # константы
|
||||
└── index.ts # публичный API
|
||||
```
|
||||
|
||||
Подробное описание каждого сегмента — в разделе [Сегменты](/reference/segments).
|
||||
|
||||
### Публичный API
|
||||
|
||||
Модуль экспортирует наружу только то, что нужно другим. Всё остальное — внутреннее.
|
||||
|
||||
```ts
|
||||
// business/auth/index.ts
|
||||
export type { User, Session } from './types/user.types'
|
||||
export { useAuth } from './hooks/use-auth.hook'
|
||||
export { AuthGuard } from './ui/auth-guard'
|
||||
```
|
||||
|
||||
Импорт в обход `index.ts` запрещён:
|
||||
|
||||
```ts
|
||||
// Плохо
|
||||
import { validateToken } from '@/business/auth/lib/tokens'
|
||||
|
||||
// Хорошо
|
||||
import { useAuth } from '@/business/auth'
|
||||
```
|
||||
|
||||
### Фабрика
|
||||
|
||||
Если модуль зависит от кода другого бизнес-домена — он экспортирует фабрику. Фабрика декларирует необходимые зависимости и возвращает API модуля. Точка использования (screen, widget, layout) предоставляет зависимости при вызове.
|
||||
|
||||
Модуль без cross-domain зависимостей экспортирует API напрямую. Типы всегда экспортируются напрямую — `import type` не является runtime-зависимостью.
|
||||
|
||||
#### Модуль без зависимостей — прямой экспорт:
|
||||
|
||||
```ts
|
||||
// business/auth/index.ts
|
||||
export { useAuth } from './hooks/use-auth'
|
||||
export { useCurrentUser } from './hooks/use-current-user'
|
||||
export type { User, Session } from './types'
|
||||
```
|
||||
|
||||
#### Модуль с зависимостями — фабрика:
|
||||
|
||||
```ts
|
||||
// business/chat/types/deps.ts
|
||||
import type { User } from '@/business/auth'
|
||||
|
||||
export interface ChatDeps {
|
||||
useCurrentUser: () => User | null
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
// business/chat/index.ts
|
||||
import type { ChatDeps } from './types/deps'
|
||||
|
||||
export function chatFactory(deps: ChatDeps) {
|
||||
return {
|
||||
useMessages: (roomId: string) => {
|
||||
const user = deps.useCurrentUser()
|
||||
// ...
|
||||
},
|
||||
useSendMessage: (roomId: string) => {
|
||||
const user = deps.useCurrentUser()
|
||||
return (text: string) => { /* ... */ }
|
||||
},
|
||||
useChatRooms: () => {
|
||||
const user = deps.useCurrentUser()
|
||||
// ...
|
||||
},
|
||||
ChatBadge: ({ count }: { count: number }) => { /* ... */ },
|
||||
}
|
||||
}
|
||||
|
||||
export type { Message, ChatRoom } from './types'
|
||||
export type { ChatDeps } from './types/deps'
|
||||
```
|
||||
|
||||
#### Использование на странице:
|
||||
|
||||
```tsx
|
||||
// screens/support/support.tsx
|
||||
import { useCurrentUser } from '@/business/auth'
|
||||
import { chatFactory } from '@/business/chat'
|
||||
|
||||
const chat = chatFactory({ useCurrentUser })
|
||||
|
||||
export function SupportScreen() {
|
||||
const { useMessages, useSendMessage, ChatBadge } = chat
|
||||
const messages = useMessages('support')
|
||||
const sendMessage = useSendMessage('support')
|
||||
|
||||
return (
|
||||
<div>
|
||||
<ChatBadge count={messages.length} />
|
||||
{messages.map(m => <MessageBubble key={m.id} {...m} />)}
|
||||
<MessageInput onSend={sendMessage} />
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Жизненный цикл
|
||||
|
||||
Модуль рождается на самом низком уровне использования и поднимается выше только при реальной потребности.
|
||||
|
||||
- Нужен на одной странице → `screens/{name}/parts/`
|
||||
- Появился в 2+ местах → поднимается по природе:
|
||||
- абстрактный UI → `ui/`
|
||||
- блок с данными/логикой → `widgets/`
|
||||
- представление бизнес-домена → `business/{area}/parts/`
|
||||
|
||||
Подъём — обычный рефакторинг в рамках задачи, а не отдельная активность.
|
||||
|
||||
<!-- /reference/segments -->
|
||||
## Сегменты
|
||||
|
||||
Раздел описывает сегменты SLM: что такое сегмент, какие бывают и что в каждом из них лежит.
|
||||
|
||||
### Определение
|
||||
|
||||
**Сегмент — папка внутри модуля, которая группирует файлы по назначению. Набор сегментов не фиксирован — модуль включает только те, которые ему нужны. Команда сама определяет какие сегменты используются в проекте — архитектура даёт рекомендацию.**
|
||||
|
||||
### Обзор
|
||||
|
||||
| Сегмент | Содержимое |
|
||||
|---------|------------|
|
||||
| `ui/` | Компоненты модуля — только `.tsx` файлы |
|
||||
| `parts/` | Вложенные модули со своими сегментами |
|
||||
| `hooks/` | React-хуки |
|
||||
| `stores/` | Сторы состояния |
|
||||
| `services/` | Работа с внешними источниками данных |
|
||||
| `mappers/` | Трансформация данных между форматами |
|
||||
| `types/` | TypeScript-типы и интерфейсы |
|
||||
| `styles/` | Стили |
|
||||
| `lib/` | Утилиты и хелперы модуля |
|
||||
| `config/` | Константы и конфигурация |
|
||||
|
||||
### Сегмент ui/
|
||||
|
||||
Компоненты, принадлежащие модулю. Содержит только `.tsx` файлы — без своих сегментов, стилей, типов, хуков. Использует сегменты родительского модуля.
|
||||
|
||||
```text
|
||||
auth/
|
||||
├── ui/
|
||||
│ ├── auth-provider.tsx
|
||||
│ ├── auth-guard.tsx
|
||||
│ └── logout-button.tsx
|
||||
├── types/
|
||||
├── hooks/
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
Если компоненту нужны собственные сегменты — это уже не `ui/`, а `parts/`.
|
||||
|
||||
### Сегмент parts/
|
||||
|
||||
Вложенные модули со своими сегментами. Каждый элемент `parts/` — полноценный модуль: папка с компонентом, хуками, стилями, типами и т.д.
|
||||
|
||||
```text
|
||||
home/
|
||||
├── parts/
|
||||
│ ├── hero-section/
|
||||
│ │ ├── hero-section.tsx
|
||||
│ │ ├── styles/
|
||||
│ │ └── parts/
|
||||
│ │ └── top-banner/
|
||||
│ │ └── top-banner.tsx
|
||||
│ └── features-section/
|
||||
│ ├── features-section.tsx
|
||||
│ └── hooks/
|
||||
├── home.screen.tsx
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
Отличие от `ui/`: элемент `parts/` — модуль со своими сегментами. Элемент `ui/` — компонент, один `.tsx` файл.
|
||||
|
||||
Вложенность `parts/` инкапсулирует область разработки горизонтально: каждый разработчик работает в своём `parts/`-модуле, не затрагивая чужие. Это снижает конфликты при параллельной разработке.
|
||||
|
||||
Если вложенный модуль обрастает своими `parts/` — это сигнал, что он достаточно самостоятельный для подъёма на уровень выше.
|
||||
|
||||
### Сегмент hooks/
|
||||
|
||||
React-хуки модуля. Инкапсулируют логику, состояние, подписки, побочные эффекты.
|
||||
|
||||
```text
|
||||
hooks/
|
||||
├── use-auth.hook.ts
|
||||
├── use-session.hook.ts
|
||||
└── use-permissions.hook.ts
|
||||
```
|
||||
|
||||
### Сегмент stores/
|
||||
|
||||
Сторы состояния модуля. Конкретная реализация зависит от выбранного стейт-менеджера (Zustand, MobX, Redux и т.д.).
|
||||
|
||||
```text
|
||||
stores/
|
||||
├── auth.store.ts
|
||||
└── session.store.ts
|
||||
```
|
||||
|
||||
### Сегмент services/
|
||||
|
||||
Работа с внешними источниками данных: API-вызовы, запросы, подписки.
|
||||
|
||||
```text
|
||||
services/
|
||||
├── auth.service.ts
|
||||
└── token.service.ts
|
||||
```
|
||||
|
||||
### Сегмент mappers/
|
||||
|
||||
Функции трансформации данных из одного формата в другой: DTO в доменный тип, доменный тип в DTO, доменный тип в ViewModel.
|
||||
|
||||
```text
|
||||
mappers/
|
||||
├── map-user.ts
|
||||
├── map-product.ts
|
||||
└── map-order-to-dto.ts
|
||||
```
|
||||
|
||||
### Сегмент types/
|
||||
|
||||
TypeScript-типы и интерфейсы модуля. Доменные типы, DTO, пропсы компонентов.
|
||||
|
||||
```text
|
||||
types/
|
||||
├── user.type.ts
|
||||
└── session.type.ts
|
||||
```
|
||||
|
||||
### Сегмент styles/
|
||||
|
||||
Стили модуля. Формат зависит от выбранного подхода (CSS Modules, SCSS, CSS-in-JS и т.д.).
|
||||
|
||||
```text
|
||||
styles/
|
||||
├── auth.module.css
|
||||
└── login-form.module.css
|
||||
```
|
||||
|
||||
### Сегмент lib/
|
||||
|
||||
Утилиты и хелперы, специфичные для модуля. Чистые функции без побочных эффектов.
|
||||
|
||||
```text
|
||||
lib/
|
||||
├── validate-email.ts
|
||||
└── format-phone.ts
|
||||
```
|
||||
|
||||
Отличие от `shared/lib/`: здесь лежат утилиты, нужные только этому модулю. Общие утилиты — в `shared/lib/`.
|
||||
|
||||
### Сегмент config/
|
||||
|
||||
Константы и конфигурация модуля: маршруты, лимиты, дефолтные значения.
|
||||
|
||||
```text
|
||||
config/
|
||||
├── routes.ts
|
||||
└── constants.ts
|
||||
```
|
||||
@@ -1,10 +1,12 @@
|
||||
---
|
||||
title: Стиль кода
|
||||
scope: basics
|
||||
keywords: [форматирование, импорт, отступ, кавычки, early return, точка с запятой, линтер]
|
||||
when: "Написание или ревью любого кода: форматирование, импорты, структура файла"
|
||||
---
|
||||
|
||||
# Стиль кода
|
||||
|
||||
Единые правила оформления кода: форматирование, импорты, читаемость.
|
||||
Раздел описывает единые правила оформления кода: отступы, переносы, кавычки, порядок импортов и базовую читаемость.
|
||||
|
||||
## Отступы
|
||||
|
||||
@@ -1,10 +1,13 @@
|
||||
---
|
||||
title: Документирование
|
||||
scope: basics
|
||||
keywords: [JSDoc, комментарий, документирование, описание функции, описание компонента]
|
||||
when: "Документирование кода: JSDoc для функций, компонентов, типов"
|
||||
---
|
||||
|
||||
# Документирование
|
||||
|
||||
Правила документирования кода: что и когда документировать через JSDoc.
|
||||
Этот раздел описывает правила документирования кода: когда и как писать
|
||||
комментарии к компонентам, функциям, типам и интерфейсам.
|
||||
|
||||
## Общие правила
|
||||
|
||||
@@ -1,22 +1,24 @@
|
||||
---
|
||||
title: Начало работы
|
||||
scope: workflow
|
||||
keywords: [начало, onboarding, настройка, установка, первый запуск]
|
||||
when: "Первый запуск проекта, знакомство со стеком"
|
||||
---
|
||||
|
||||
# Начало работы
|
||||
|
||||
Что нужно знать перед началом разработки в проекте.
|
||||
|
||||
## Стек проекта
|
||||
|
||||
**Next.js** (App Router), **Mantine**, **Zustand**, **SLM Design**.
|
||||
**Next.js** (App Router), **Mantine**, **Zustand**, **FSD**.
|
||||
|
||||
Подробнее — [Технологии и библиотеки](/docs/basics/tech-stack).
|
||||
Подробнее — [Технологии и библиотеки](/basics/tech-stack).
|
||||
|
||||
## Ключевые особенности
|
||||
|
||||
- **Генерация вместо ручного создания** — компоненты, бизнес-модули, виджеты, сторы и другие модули не создаются вручную. Файловая структура генерируется из шаблонов `.templates/`. Ручное создание файловой структуры модулей запрещено.
|
||||
- **Генерация вместо ручного создания** — компоненты, фичи, виджеты, сторы и другие модули не создаются вручную. Файловая структура генерируется из шаблонов `.templates/`. Ручное создание файловой структуры модулей запрещено.
|
||||
- **Biome вместо ESLint + Prettier** — один инструмент для линтинга и форматирования. Автофикс и сортировка импортов происходят автоматически при сохранении файла.
|
||||
|
||||
## Настройка окружения
|
||||
|
||||
Открыть проект в VS Code и установить рекомендуемые расширения — редактор предложит это автоматически. Подробнее — [Настройка VS Code](/docs/applied/vscode).
|
||||
Открыть проект в VS Code и установить рекомендуемые расширения — редактор предложит это автоматически. Подробнее — [Настройка VS Code](/applied/vscode).
|
||||
@@ -1,10 +1,12 @@
|
||||
---
|
||||
title: Именование
|
||||
scope: basics
|
||||
keywords: [camelCase, kebab-case, PascalCase, имя файла, имя переменной, имя компонента, имя хука]
|
||||
when: "Создание файлов, переменных, компонентов, хуков — выбор имени"
|
||||
---
|
||||
|
||||
# Именование
|
||||
|
||||
Соглашения об именовании в коде: что и как называть.
|
||||
Этот раздел описывает соглашения об именовании в проекте. Единые правила делают код предсказуемым и упрощают навигацию по проекту.
|
||||
|
||||
## Базовые правила
|
||||
|
||||
@@ -53,7 +55,7 @@ title: Именование
|
||||
|
||||
**Хорошо**
|
||||
```text
|
||||
business/
|
||||
features/
|
||||
└── auth-by-email/
|
||||
├── ui/
|
||||
│ └── login-form.tsx
|
||||
@@ -62,14 +64,14 @@ business/
|
||||
├── stores/
|
||||
│ └── auth.store.ts
|
||||
├── types/
|
||||
│ └── auth.type.ts
|
||||
├── auth-by-email.tsx
|
||||
│ └── auth.interface.ts
|
||||
├── auth-by-email.feature.tsx
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```text
|
||||
business/
|
||||
features/
|
||||
└── authByEmail/
|
||||
├── LoginForm.tsx
|
||||
├── useAuth.ts
|
||||
@@ -1,10 +1,12 @@
|
||||
---
|
||||
title: Технологии и библиотеки
|
||||
scope: basics
|
||||
keywords: [стек, React, TypeScript, Next.js, Mantine, библиотека, зависимость]
|
||||
when: "Выбор библиотеки или технологии, проверка допустимости зависимости"
|
||||
---
|
||||
|
||||
# Технологии и библиотеки
|
||||
|
||||
Базовый стек проекта по областям: UI, архитектура, данные, состояние, локализация, тестирование, стили, генерация кода.
|
||||
Этот раздел описывает базовый стек технологий и библиотек, принятый в проекте.
|
||||
|
||||
## Что используем
|
||||
|
||||
@@ -13,7 +15,7 @@ title: Технологии и библиотеки
|
||||
- `Next.js` — для продуктовых сайтов.
|
||||
|
||||
### Архитектура
|
||||
- `SLM Design` — собственная модульная архитектура проекта. Подробнее в разделе [Архитектура](/docs/basics/architecture/).
|
||||
- `FSD (Feature-Sliced Design)` — структура проекта и границы модулей. Используется кастомизированная версия — подробнее в разделе [Архитектура](/basics/architecture).
|
||||
|
||||
### UI компоненты
|
||||
- `Mantine UI` — базовые UI-компоненты.
|
||||
@@ -1,10 +1,12 @@
|
||||
---
|
||||
title: Типизация
|
||||
scope: basics
|
||||
keywords: [type, interface, generic, any, unknown, enum, типизация, пропсы]
|
||||
when: "Типизация кода: выбор type vs interface, работа с generic, запрет any"
|
||||
---
|
||||
|
||||
# Типизация
|
||||
|
||||
Правила типизации в TypeScript: общие принципы и работа с динамическими типами.
|
||||
Этот раздел описывает правила типизации: как типизировать компоненты, функции и работу с `any`/`unknown`.
|
||||
|
||||
## Общие правила
|
||||
|
||||
35
src/base/triggers/develop/add-api-request.md
Normal file
35
src/base/triggers/develop/add-api-request.md
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: Добавить API-запрос
|
||||
---
|
||||
|
||||
# Добавить API-запрос
|
||||
|
||||
Инструкция по добавлению запроса к серверу: создание клиента, хука, обработка ответа.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- applied/api.md — правила API-слоя: клиенты, эндпоинты, обработка ошибок
|
||||
- basics/typing.md — типизация запросов и ответов
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Определи подход:
|
||||
- Клиентские данные → SWR / хук
|
||||
- Серверные данные → серверный компонент (RSC)
|
||||
|
||||
2. Опиши типы запроса и ответа.
|
||||
|
||||
3. Создай или расширь API-клиент (→ applied/api.md).
|
||||
|
||||
4. Создай хук для использования в компоненте (→ triggers/develop/create-hook.md).
|
||||
|
||||
## Смежные триггеры
|
||||
|
||||
- triggers/develop/create-hook.md — хук для запроса
|
||||
- triggers/develop/create-component.md — компонент, использующий данные
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Типы запроса и ответа описаны
|
||||
- [ ] Хук для использования в компоненте создан
|
||||
- [ ] Обработка ошибок реализована
|
||||
24
src/base/triggers/develop/add-dependency.md
Normal file
24
src/base/triggers/develop/add-dependency.md
Normal file
@@ -0,0 +1,24 @@
|
||||
---
|
||||
title: Добавить зависимость
|
||||
---
|
||||
|
||||
# Добавить зависимость
|
||||
|
||||
Инструкция по добавлению новой npm-зависимости в проект. Проверь допустимость перед установкой.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- basics/tech-stack.md — разрешённый стек, допустимые библиотеки
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Проверь, что библиотека не дублирует уже используемую (→ basics/tech-stack.md).
|
||||
|
||||
2. Проверь, что библиотека входит в разрешённый список или обоснуй необходимость.
|
||||
|
||||
3. Установи как `dependency` или `devDependency` в зависимости от назначения.
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Библиотека не дублирует уже используемую
|
||||
- [ ] Библиотека входит в разрешённый список (→ basics/tech-stack.md)
|
||||
28
src/base/triggers/develop/add-font.md
Normal file
28
src/base/triggers/develop/add-font.md
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: Подключить шрифт
|
||||
---
|
||||
|
||||
# Подключить шрифт
|
||||
|
||||
Инструкция по подключению и настройке шрифта в проекте.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- applied/fonts.md — правила подключения шрифтов: форматы, загрузка, CSS-переменные
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Подготовь файлы шрифта (woff2).
|
||||
|
||||
2. Подключи шрифт по правилам (→ applied/fonts.md).
|
||||
|
||||
3. Зарегистрируй CSS-переменную для шрифта.
|
||||
|
||||
## Смежные триггеры
|
||||
|
||||
- triggers/develop/style-component.md — использование шрифта в стилях
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Файл шрифта в формате woff2
|
||||
- [ ] CSS-переменная для шрифта зарегистрирована
|
||||
29
src/base/triggers/develop/add-icon.md
Normal file
29
src/base/triggers/develop/add-icon.md
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: Добавить иконку
|
||||
---
|
||||
|
||||
# Добавить иконку
|
||||
|
||||
Инструкция по добавлению SVG-иконки в проект через спрайт-систему.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- applied/svg-sprites.md — правила SVG-спрайтов: структура, именование, использование
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Подготовь SVG-файл: убери лишние атрибуты, оптимизируй.
|
||||
|
||||
2. Добавь SVG в спрайт по правилам (→ applied/svg-sprites.md).
|
||||
|
||||
3. Используй иконку в компоненте через компонент-обёртку.
|
||||
|
||||
## Смежные триггеры
|
||||
|
||||
- triggers/develop/create-component.md — если нужен компонент-обёртка для иконки
|
||||
- triggers/develop/style-component.md — стилизация иконки (размер, цвет)
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] SVG оптимизирован — убраны лишние атрибуты
|
||||
- [ ] Иконка добавлена в спрайт по правилам (→ applied/svg-sprites.md)
|
||||
30
src/base/triggers/develop/add-image.md
Normal file
30
src/base/triggers/develop/add-image.md
Normal file
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: Добавить изображение
|
||||
---
|
||||
|
||||
# Добавить изображение
|
||||
|
||||
Инструкция по добавлению и использованию растровых изображений в проекте.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- applied/images-sprites.md — правила работы с изображениями: оптимизация, форматы, подключение
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Определи тип изображения:
|
||||
- Статическое (логотип, декор) → `public/`
|
||||
- Динамическое (контентное) → URL из API
|
||||
|
||||
2. Оптимизируй изображение (формат, размер, сжатие).
|
||||
|
||||
3. Подключи в компоненте по правилам (→ applied/images-sprites.md).
|
||||
|
||||
## Смежные триггеры
|
||||
|
||||
- triggers/develop/create-component.md — если нужен компонент-обёртка для изображения
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Изображение оптимизировано (формат, размер, сжатие)
|
||||
- [ ] Подключено по правилам (→ applied/images-sprites.md)
|
||||
28
src/base/triggers/develop/add-localization.md
Normal file
28
src/base/triggers/develop/add-localization.md
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: Добавить перевод
|
||||
---
|
||||
|
||||
# Добавить перевод
|
||||
|
||||
Инструкция по добавлению локализации: создание ключей перевода и подключение в компоненте.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- applied/localization.md — правила локализации: namespace, ключи, форматирование
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Определи namespace для переводов (→ applied/localization.md).
|
||||
|
||||
2. Добавь ключи перевода в файлы локализации.
|
||||
|
||||
3. Подключи переводы в компоненте (→ applied/localization.md).
|
||||
|
||||
## Смежные триггеры
|
||||
|
||||
- triggers/develop/create-component.md — если компонент ещё не создан
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Ключи перевода добавлены в файлы локализации
|
||||
- [ ] Namespace определён (→ applied/localization.md)
|
||||
27
src/base/triggers/develop/add-video.md
Normal file
27
src/base/triggers/develop/add-video.md
Normal file
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: Добавить видео
|
||||
---
|
||||
|
||||
# Добавить видео
|
||||
|
||||
Инструкция по встраиванию видео в проект.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- applied/video.md — правила работы с видео: форматы, плеер, оптимизация
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Определи тип видео:
|
||||
- Локальное → `public/`
|
||||
- Внешнее (YouTube, Vimeo) → embed
|
||||
|
||||
2. Подключи видео по правилам (→ applied/video.md).
|
||||
|
||||
## Смежные триггеры
|
||||
|
||||
- triggers/develop/create-component.md — если нужен компонент-обёртка для видео
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Видео подключено по правилам (→ applied/video.md)
|
||||
31
src/base/triggers/develop/connect-store.md
Normal file
31
src/base/triggers/develop/connect-store.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Подключить стор к компоненту
|
||||
---
|
||||
|
||||
# Подключить стор к компоненту
|
||||
|
||||
Инструкция по подключению стора к React-компоненту.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- applied/stores.md — правила сторов: подписка, селекторы
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Определи нужен ли стор:
|
||||
- Локальное состояние → `useState` / `useReducer`
|
||||
- Глобальное состояние → стор
|
||||
|
||||
2. Если стор не существует — создай его (→ triggers/develop/create-store.md).
|
||||
|
||||
3. Подключи стор в компоненте через селектор (→ applied/stores.md).
|
||||
|
||||
## Смежные триггеры
|
||||
|
||||
- triggers/develop/create-store.md — создание нового стора
|
||||
- triggers/develop/create-hook.md — хук-обёртка над стором
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Используется селектор, а не подписка на весь стор
|
||||
- [ ] Выбор локальное/глобальное состояние обоснован
|
||||
38
src/base/triggers/develop/create-component.md
Normal file
38
src/base/triggers/develop/create-component.md
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Создать компонент
|
||||
---
|
||||
|
||||
# Создать компонент
|
||||
|
||||
Инструкция по созданию React-компонента в проекте. Определи слой, сгенерируй из шаблона, реализуй по правилам.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- applied/components.md — правила компонентов: структура файлов, пропсы, документирование
|
||||
- basics/naming.md — именование файла и экспортов
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Определи слой компонента по его назначению (→ basics/architecture.md):
|
||||
- `shared/ui/` — переиспользуемый UI без бизнес-логики
|
||||
- `features/` — фича с бизнес-логикой
|
||||
- `widgets/` — композиция фичей и сущностей
|
||||
- `entities/` — бизнес-сущность с UI
|
||||
|
||||
2. Сгенерируй модуль из шаблона (→ triggers/develop/generate-module.md).
|
||||
|
||||
3. Реализуй компонент по правилам (→ applied/components.md).
|
||||
|
||||
4. Если нужны стили — см. triggers/develop/style-component.md.
|
||||
|
||||
## Смежные триггеры
|
||||
|
||||
- triggers/develop/style-component.md — стилизация компонента
|
||||
- triggers/develop/add-icon.md — добавление иконки в компонент
|
||||
- triggers/develop/generate-module.md — генерация из шаблона
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Компонент создан из шаблона, не вручную
|
||||
- [ ] Файл и экспорт именованы по конвенции (→ basics/naming.md)
|
||||
- [ ] Пропсы типизированы (→ basics/typing.md)
|
||||
34
src/base/triggers/develop/create-entity.md
Normal file
34
src/base/triggers/develop/create-entity.md
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Создать сущность
|
||||
---
|
||||
|
||||
# Создать сущность
|
||||
|
||||
Инструкция по созданию модуля на слое `entities/`. Сущность — бизнес-объект с UI-представлением и моделью данных.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- basics/architecture.md — слои и зависимости
|
||||
- applied/components.md — правила компонентов
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Сгенерируй модуль из шаблона `entity` (→ triggers/develop/generate-module.md).
|
||||
|
||||
2. Определи модель данных — типы в `model/`.
|
||||
|
||||
3. Реализуй UI-компонент сущности.
|
||||
|
||||
4. Настрой публичный API — экспорт через `index.ts`.
|
||||
|
||||
## Смежные триггеры
|
||||
|
||||
- triggers/develop/create-component.md — UI-компонент сущности
|
||||
- triggers/develop/create-store.md — стор для сущности
|
||||
- triggers/develop/generate-module.md — генерация из шаблона
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Сущность создана из шаблона `entity`
|
||||
- [ ] Модель данных определена — типы в `model/`
|
||||
- [ ] Публичный API настроен — экспорт через `index.ts`
|
||||
37
src/base/triggers/develop/create-feature.md
Normal file
37
src/base/triggers/develop/create-feature.md
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: Создать фичу
|
||||
---
|
||||
|
||||
# Создать фичу
|
||||
|
||||
Инструкция по созданию модуля на слое `features/`. Фича — самодостаточный блок с бизнес-логикой и UI.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- basics/architecture.md — слои и зависимости
|
||||
- applied/components.md — правила компонентов
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Сгенерируй модуль из шаблона `feature` (→ triggers/develop/generate-module.md).
|
||||
|
||||
2. Реализуй компонент фичи (→ applied/components.md).
|
||||
|
||||
3. Если нужен стор — создай в `model/` (→ triggers/develop/create-store.md).
|
||||
|
||||
4. Если нужны хуки — создай в `model/` (→ triggers/develop/create-hook.md).
|
||||
|
||||
5. Настрой публичный API — экспорт через `index.ts`.
|
||||
|
||||
## Смежные триггеры
|
||||
|
||||
- triggers/develop/create-component.md — компонент внутри фичи
|
||||
- triggers/develop/create-store.md — стор для фичи
|
||||
- triggers/develop/create-hook.md — хук для фичи
|
||||
- triggers/develop/generate-module.md — генерация из шаблона
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Фича создана из шаблона `feature`
|
||||
- [ ] Публичный API настроен — экспорт через `index.ts`
|
||||
- [ ] Нет зависимостей от других фичей (→ basics/architecture.md)
|
||||
36
src/base/triggers/develop/create-hook.md
Normal file
36
src/base/triggers/develop/create-hook.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Создать хук
|
||||
---
|
||||
|
||||
# Создать хук
|
||||
|
||||
Инструкция по созданию кастомного React-хука. Определи где он живёт, реализуй по правилам.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- applied/hooks.md — правила хуков
|
||||
- basics/naming.md — именование (префикс `use`)
|
||||
- basics/typing.md — типизация параметров и возврата
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Определи область хука:
|
||||
- Утилитарный (не привязан к бизнес-логике) → `shared/hooks/`
|
||||
- Привязан к фиче/сущности → `model/` внутри модуля
|
||||
|
||||
2. Создай файл с именем `use-{name}.ts`.
|
||||
|
||||
3. Реализуй хук по правилам (→ applied/hooks.md).
|
||||
|
||||
4. Экспортируй через публичный API модуля.
|
||||
|
||||
## Смежные триггеры
|
||||
|
||||
- triggers/develop/create-component.md — если хук используется в новом компоненте
|
||||
- triggers/develop/connect-store.md — если хук подключает стор
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Имя начинается с `use` (→ basics/naming.md)
|
||||
- [ ] Параметры и возвращаемое значение типизированы
|
||||
- [ ] Хук экспортирован через публичный API модуля
|
||||
36
src/base/triggers/develop/create-store.md
Normal file
36
src/base/triggers/develop/create-store.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Создать стор
|
||||
---
|
||||
|
||||
# Создать стор
|
||||
|
||||
Инструкция по созданию стора для управления состоянием. Определи область, сгенерируй из шаблона.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- applied/stores.md — правила сторов
|
||||
- basics/naming.md — именование
|
||||
- basics/typing.md — типизация состояния и экшенов
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Определи область стора:
|
||||
- Глобальный → `shared/model/`
|
||||
- Привязан к фиче/сущности → `model/` внутри модуля
|
||||
|
||||
2. Сгенерируй из шаблона `store` (→ triggers/develop/generate-module.md).
|
||||
|
||||
3. Реализуй стор по правилам (→ applied/stores.md).
|
||||
|
||||
4. Экспортируй через публичный API модуля.
|
||||
|
||||
## Смежные триггеры
|
||||
|
||||
- triggers/develop/connect-store.md — подключение стора к компоненту
|
||||
- triggers/develop/generate-module.md — генерация из шаблона
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Стор создан из шаблона `store`
|
||||
- [ ] Состояние и экшены типизированы
|
||||
- [ ] Стор экспортирован через публичный API модуля
|
||||
32
src/base/triggers/develop/create-widget.md
Normal file
32
src/base/triggers/develop/create-widget.md
Normal file
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: Создать виджет
|
||||
---
|
||||
|
||||
# Создать виджет
|
||||
|
||||
Инструкция по созданию модуля на слое `widgets/`. Виджет — композиция фичей и сущностей.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- basics/architecture.md — слои и зависимости
|
||||
- applied/components.md — правила компонентов
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Сгенерируй модуль из шаблона `widget` (→ triggers/develop/generate-module.md).
|
||||
|
||||
2. Скомпонуй виджет из существующих фичей и сущностей.
|
||||
|
||||
3. Настрой публичный API — экспорт через `index.ts`.
|
||||
|
||||
## Смежные триггеры
|
||||
|
||||
- triggers/develop/create-feature.md — если нужна новая фича для виджета
|
||||
- triggers/develop/create-component.md — UI-компоненты внутри виджета
|
||||
- triggers/develop/generate-module.md — генерация из шаблона
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Виджет создан из шаблона `widget`
|
||||
- [ ] Композиция из существующих фичей/сущностей, не дублирует логику
|
||||
- [ ] Публичный API настроен — экспорт через `index.ts`
|
||||
37
src/base/triggers/develop/generate-module.md
Normal file
37
src/base/triggers/develop/generate-module.md
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: Сгенерировать модуль из шаблона
|
||||
---
|
||||
|
||||
# Сгенерировать модуль из шаблона
|
||||
|
||||
Инструкция по генерации модуля из шаблонов `.templates/`. Ручное создание файловой структуры запрещено.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- applied/templates-generation.md — шаблоны, синтаксис, инструменты генерации
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Определи тип модуля и шаблон (→ applied/templates-generation.md):
|
||||
- Компонент → `component`
|
||||
- Фича → `feature`
|
||||
- Виджет → `widget`
|
||||
- Сущность → `entity`
|
||||
- Layout → `layout`
|
||||
- Экран → `screen`
|
||||
- Стор → `store`
|
||||
|
||||
2. Запусти генерацию (→ applied/templates-generation.md).
|
||||
|
||||
3. Если подходящего шаблона нет — сначала создай шаблон, затем генерируй.
|
||||
|
||||
## Смежные триггеры
|
||||
|
||||
- triggers/develop/create-component.md — после генерации компонента
|
||||
- triggers/develop/create-feature.md — после генерации фичи
|
||||
- triggers/develop/create-store.md — после генерации стора
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Модуль создан из шаблона, не вручную
|
||||
- [ ] Выбран правильный шаблон для типа модуля (→ applied/templates-generation.md)
|
||||
24
src/base/triggers/develop/setup-vscode.md
Normal file
24
src/base/triggers/develop/setup-vscode.md
Normal file
@@ -0,0 +1,24 @@
|
||||
---
|
||||
title: Настроить VS Code
|
||||
---
|
||||
|
||||
# Настроить VS Code
|
||||
|
||||
Инструкция по настройке VS Code для работы с проектом.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- applied/vscode.md — настройки, расширения, сниппеты
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Установи рекомендованные расширения (→ applied/vscode.md).
|
||||
|
||||
2. Проверь настройки `.vscode/settings.json`.
|
||||
|
||||
3. Настрой сниппеты при необходимости.
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Рекомендованные расширения установлены
|
||||
- [ ] Настройки `.vscode/settings.json` проверены
|
||||
35
src/base/triggers/develop/style-component.md
Normal file
35
src/base/triggers/develop/style-component.md
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: Стилизовать компонент
|
||||
---
|
||||
|
||||
# Стилизовать компонент
|
||||
|
||||
Инструкция по выбору подхода к стилизации и написанию стилей для компонента.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- applied/styles.md — правила CSS: PostCSS Modules, токены, медиа-запросы
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Определи подход (→ applied/styles.md):
|
||||
- Mantine-компонент → используй пропсы Mantine, не пиши CSS
|
||||
- CSS-токены достаточно → используй токены
|
||||
- Нужна кастомная стилизация → PostCSS Modules
|
||||
|
||||
2. Создай файл стилей `{component-name}.module.css` рядом с компонентом.
|
||||
|
||||
3. Напиши стили по правилам (→ applied/styles.md).
|
||||
|
||||
4. Подключи стили в компоненте через `cl()`.
|
||||
|
||||
## Смежные триггеры
|
||||
|
||||
- triggers/develop/create-component.md — если компонент ещё не создан
|
||||
- triggers/develop/add-icon.md — если нужна иконка в компоненте
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Приоритет стилизации соблюдён: Mantine → токены → PostCSS Modules
|
||||
- [ ] Нет инлайн-стилей и магических значений
|
||||
- [ ] Файл стилей именован `{component-name}.module.css`
|
||||
96
src/nextjs/DEVELOP.md
Normal file
96
src/nextjs/DEVELOP.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# Стайлгайд — Разработка
|
||||
|
||||
Правила и стандарты разработки на Next.js и TypeScript.
|
||||
|
||||
## Как работать
|
||||
|
||||
1. **Изучи обязательные правила** (таблица ниже) — они действуют при любой задаче.
|
||||
2. Найди задачу в таблицах триггеров → открой триггер.
|
||||
3. Триггер укажет какие прикладные разделы прочитать и какие шаги выполнить.
|
||||
4. Перед каждой подзадачей возвращайся к триггерам — проверяй, нет ли готового.
|
||||
5. Если триггера нет — ищи прикладной раздел по области задачи.
|
||||
|
||||
---
|
||||
|
||||
## Обязательные правила
|
||||
|
||||
Прочитай эти разделы **до начала работы**. Соблюдай при написании любого кода.
|
||||
|
||||
| Раздел | Файл | Что внутри |
|
||||
|--------|------|------------|
|
||||
| Структура проекта | applied/project-structure.md | Организация папок и файлов |
|
||||
| Архитектура | basics/architecture.md | SLM Design: слои, модули, сегменты |
|
||||
| Стиль кода | basics/code-style.md | Форматирование, импорты, отступы |
|
||||
| Именование | basics/naming.md | Имена файлов, переменных, событий |
|
||||
| Типизация | basics/typing.md | type vs interface, generic, any/unknown |
|
||||
| Документирование | basics/documentation.md | JSDoc для функций, компонентов, типов |
|
||||
| Технологии | basics/tech-stack.md | Допустимые библиотеки и зависимости |
|
||||
|
||||
---
|
||||
|
||||
## Прикладные разделы
|
||||
|
||||
Справочник по областям. Читай тот раздел, который относится к текущей задаче.
|
||||
|
||||
| Область | Файл | Когда читать |
|
||||
|---------|------|--------------|
|
||||
| Компоненты | applied/components.md | Создание или редактирование React-компонентов |
|
||||
| Стили | applied/styles.md | CSS Modules, PostCSS, переменные, медиа-запросы |
|
||||
| Файлы роутинга | applied/page-level.md | page.tsx, layout.tsx, error.tsx, not-found.tsx |
|
||||
| Шаблоны и генерация | applied/templates-generation.md | Генерация кода из шаблонов |
|
||||
| Настройка VS Code | applied/vscode.md | Расширения, settings.json, сниппеты |
|
||||
| SVG-спрайты | applied/svg-sprites.md | Работа с SVG-иконками и спрайтами |
|
||||
| Хуки | applied/hooks.md | Создание и использование кастомных хуков *(в разработке)* |
|
||||
| Сторы | applied/stores.md | Глобальное состояние, Zustand *(в разработке)* |
|
||||
| API | applied/api.md | Запросы, клиенты, обработка ответов *(в разработке)* |
|
||||
| Локализация | applied/localization.md | i18next, переводы *(в разработке)* |
|
||||
| Изображения | applied/images-sprites.md | Подключение и оптимизация изображений *(в разработке)* |
|
||||
| Шрифты | applied/fonts.md | Подключение и настройка шрифтов *(в разработке)* |
|
||||
| Видео | applied/video.md | Встраивание видео *(в разработке)* |
|
||||
|
||||
---
|
||||
|
||||
## Триггеры
|
||||
|
||||
Пошаговые инструкции. Найди задачу → открой триггер → выполняй по шагам.
|
||||
|
||||
### Создание
|
||||
|
||||
| Задача | Триггер | Описание |
|
||||
|--------|---------|----------|
|
||||
| Создать компонент | triggers/develop/create-component.md | Переиспользуемый UI-элемент без бизнес-логики |
|
||||
| Создать фичу | triggers/develop/create-feature.md | Самодостаточный блок с бизнес-логикой и UI |
|
||||
| Создать виджет | triggers/develop/create-widget.md | Композиция нескольких фичей и сущностей |
|
||||
| Создать сущность | triggers/develop/create-entity.md | Бизнес-объект с моделью данных и UI-представлением |
|
||||
| Создать хук | triggers/develop/create-hook.md | Кастомный React-хук с переиспользуемой логикой |
|
||||
| Создать стор | triggers/develop/create-store.md | Глобальное или модульное состояние через Zustand |
|
||||
| Создать страницу | triggers/develop/create-page.md | Новый route в Next.js — экран + page.tsx |
|
||||
| Создать layout | triggers/develop/create-layout.md | Общая обёртка layout.tsx для группы страниц |
|
||||
| Создать проект | triggers/develop/create-project.md | Инициализация нового проекта из шаблона |
|
||||
| Сгенерировать модуль | triggers/develop/generate-module.md | Создание модуля из шаблонов `.templates/` |
|
||||
|
||||
### Стилизация и ресурсы
|
||||
|
||||
| Задача | Триггер | Описание |
|
||||
|--------|---------|----------|
|
||||
| Стилизовать компонент | triggers/develop/style-component.md | Выбор подхода и написание CSS для компонента |
|
||||
| Добавить иконку | triggers/develop/add-icon.md | SVG-иконка через спрайт-систему |
|
||||
| Добавить изображение | triggers/develop/add-image.md | Растровое изображение (png, jpg, webp) |
|
||||
| Добавить видео | triggers/develop/add-video.md | Встраивание видео на страницу |
|
||||
| Подключить шрифт | triggers/develop/add-font.md | Подключение нового шрифта в проект |
|
||||
|
||||
### Данные и состояние
|
||||
|
||||
| Задача | Триггер | Описание |
|
||||
|--------|---------|----------|
|
||||
| Добавить API-запрос | triggers/develop/add-api-request.md | Клиентский запрос данных через SWR |
|
||||
| Подключить стор | triggers/develop/connect-store.md | Подключение существующего стора к компоненту |
|
||||
| Серверные данные (RSC) | triggers/develop/add-server-data.md | Получение данных в серверных компонентах |
|
||||
|
||||
### Инфраструктура
|
||||
|
||||
| Задача | Триггер | Описание |
|
||||
|--------|---------|----------|
|
||||
| Добавить перевод | triggers/develop/add-localization.md | Ключи перевода и подключение i18next |
|
||||
| Добавить зависимость | triggers/develop/add-dependency.md | Подключение новой npm-библиотеки |
|
||||
| Настроить VS Code | triggers/develop/setup-vscode.md | Расширения, настройки редактора, сниппеты |
|
||||
43
src/nextjs/REVIEW.md
Normal file
43
src/nextjs/REVIEW.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# Стайлгайд — Ревью
|
||||
|
||||
Правила проверки кода на Next.js и TypeScript. Читай перед ревью PR.
|
||||
|
||||
## Как пользоваться
|
||||
|
||||
1. Определи какие области затронуты в PR.
|
||||
2. Открой соответствующие разделы из таблиц ниже.
|
||||
3. Проверь код на соответствие правилам.
|
||||
|
||||
## Что проверять всегда
|
||||
|
||||
Базовые правила — применимы к любому коду в PR.
|
||||
|
||||
| Что проверить | Раздел |
|
||||
|---------------|--------|
|
||||
| Форматирование, импорты, early return | basics/code-style.md |
|
||||
| Имена файлов, переменных, компонентов | basics/naming.md |
|
||||
| Нет any, правильный type/interface | basics/typing.md |
|
||||
| JSDoc на публичных функциях | basics/documentation.md |
|
||||
| Правильный слой, нет запрещённых зависимостей | basics/architecture.md |
|
||||
| Нет неразрешённых библиотек | basics/tech-stack.md |
|
||||
|
||||
## Что проверять по области
|
||||
|
||||
Открой раздел, если PR затрагивает соответствующую область.
|
||||
|
||||
| Область | Раздел |
|
||||
|---------|--------|
|
||||
| React-компоненты | applied/components.md |
|
||||
| CSS / стили | applied/styles.md |
|
||||
| Шаблоны генерации | applied/templates-generation.md |
|
||||
| Хуки | applied/hooks.md |
|
||||
| Сторы | applied/stores.md |
|
||||
| API-слой | applied/api.md |
|
||||
| Шрифты | applied/fonts.md |
|
||||
| Переводы | applied/localization.md |
|
||||
| Изображения | applied/images-sprites.md |
|
||||
| SVG-иконки | applied/svg-sprites.md |
|
||||
| Видео | applied/video.md |
|
||||
| Настройки VS Code | applied/vscode.md |
|
||||
| page.tsx, layout.tsx | applied/page-level.md |
|
||||
| Структура папок | applied/project-structure.md |
|
||||
@@ -1,11 +1,17 @@
|
||||
---
|
||||
title: Файлы роутинга
|
||||
scope: applied
|
||||
keywords: [page.tsx, layout.tsx, error.tsx, not-found.tsx, loading.tsx, App Router, metadata]
|
||||
when: "Работа с файлами роутинга Next.js App Router: page, layout, error, not-found"
|
||||
---
|
||||
|
||||
# Файлы роутинга
|
||||
|
||||
Правила для специальных файлов App Router (`page.tsx`, `layout.tsx`, `error.tsx`, `not-found.tsx` и др.) — чем наш подход отличается от дефолтного.
|
||||
|
||||
## Что нужно знать
|
||||
|
||||
Страница в проекте — это два файла: экран в `src/screens/` (вся логика, стили, зависимости) и `page.tsx` в `src/app/` (точка входа для роутинга Next.js). Экран генерируется из шаблона, `page.tsx` создаётся вручную.
|
||||
|
||||
## Организация
|
||||
|
||||
- `page.tsx` — тонкий файл: только `metadata` и рендер экрана. Логика, стили и зависимости живут в экране, не в `page.tsx`.
|
||||
@@ -1,10 +1,12 @@
|
||||
---
|
||||
title: Структура проекта
|
||||
scope: applied
|
||||
keywords: [структура проекта, папки, src/app, src/shared, FSD, Next.js структура]
|
||||
when: "Организация папок и файлов в Next.js проекте"
|
||||
---
|
||||
|
||||
# Структура проекта
|
||||
|
||||
Файловая организация Next.js-проекта по архитектуре SLM.
|
||||
Раздел описывает расположение файлов и папок в проекте Next.js (App Router).
|
||||
|
||||
## Корень репозитория
|
||||
|
||||
@@ -41,20 +43,19 @@ public/
|
||||
```text
|
||||
src/
|
||||
├── app/ # Роутинг Next.js, провайдеры, глобальные стили
|
||||
├── layouts/ # Каркасы страниц (header, footer, sidebar)
|
||||
├── screens/ # Контент конкретной страницы
|
||||
├── widgets/ # Составные блоки интерфейса, не привязанные к домену
|
||||
├── business/ # Бизнес-домены (auth, catalog, orders)
|
||||
├── infrastructure/ # Техсервисы (theme, i18n, API-адаптеры)
|
||||
├── ui/ # UI-кит без бизнес-логики
|
||||
└── shared/ # Общие ресурсы (утилиты, типы, стили)
|
||||
├── screens/ # Собраные страницы (UI)
|
||||
├── layouts/ # Шаблоны
|
||||
├── widgets/ # Крупные самостоятельные блоки интерфейса
|
||||
├── features/ # Пользовательские сценарии
|
||||
├── entities/ # Бизнес-сущности
|
||||
└── shared/ # Переиспользуемый код (UI, утилиты, типы и др.)
|
||||
```
|
||||
|
||||
Принципы организации слоёв описаны в разделе [Архитектура](../basics/architecture/).
|
||||
Принципы организации слоёв описаны в разделе [Архитектура](../basics/architecture).
|
||||
|
||||
### Папка `app/`
|
||||
|
||||
Точка входа приложения: инициализация (провайдеры, глобальные стили) и файловый роутинг Next.js (`layout.tsx`, `page.tsx`, route-сегменты).
|
||||
Совмещает два слоя: инициализацию приложения по FSD (провайдеры, глобальные стили) и файловый роутинг Next.js (`layout.tsx`, `page.tsx`, route-сегменты).
|
||||
|
||||
```text
|
||||
src/app/
|
||||
@@ -74,7 +75,8 @@ src/app/
|
||||
├── screen/ # Шаблон экрана
|
||||
├── layout/ # Шаблон layout
|
||||
├── widget/ # Шаблон виджета
|
||||
├── module/ # Шаблон бизнес-модуля
|
||||
├── feature/ # Шаблон фичи
|
||||
├── entity/ # Шаблон сущности
|
||||
└── store/ # Шаблон стора
|
||||
```
|
||||
|
||||
33
src/nextjs/triggers/develop/add-server-data.md
Normal file
33
src/nextjs/triggers/develop/add-server-data.md
Normal file
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: Добавить серверные данные
|
||||
---
|
||||
|
||||
# Добавить серверные данные
|
||||
|
||||
Инструкция по получению данных в серверных компонентах (RSC) Next.js.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- applied/page-level.md — серверные компоненты в App Router
|
||||
- applied/api.md — API-клиенты
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Определи где получать данные:
|
||||
- В `page.tsx` / `layout.tsx` → серверный fetch
|
||||
- В клиентском компоненте → SWR (→ triggers/develop/add-api-request.md)
|
||||
|
||||
2. Создай или расширь серверный API-клиент.
|
||||
|
||||
3. Получи данные в серверном компоненте и передай через пропсы.
|
||||
|
||||
## Смежные триггеры
|
||||
|
||||
- triggers/develop/add-api-request.md — клиентские запросы (SWR)
|
||||
- triggers/develop/create-page.md — серверный fetch в page.tsx
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Определён тип: серверный fetch или клиентский SWR
|
||||
- [ ] Типы запроса и ответа описаны
|
||||
- [ ] Данные передаются через пропсы, не через глобальное состояние
|
||||
34
src/nextjs/triggers/develop/create-layout.md
Normal file
34
src/nextjs/triggers/develop/create-layout.md
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Создать layout
|
||||
---
|
||||
|
||||
# Создать layout
|
||||
|
||||
Инструкция по созданию layout.tsx в Next.js App Router.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- applied/page-level.md — правила layout.tsx: провайдеры, metadata, вёрстка
|
||||
- applied/project-structure.md — структура `src/app/`
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Определи уровень layout:
|
||||
- Корневой (`src/app/layout.tsx`) — провайдеры, глобальные стили, metadata
|
||||
- Вложенный (`src/app/{route}/layout.tsx`) — layout для группы страниц
|
||||
|
||||
2. Создай `layout.tsx` в нужном маршруте.
|
||||
|
||||
3. Вёрстку layout-обёрток вынеси в слой `layouts/` (→ applied/page-level.md).
|
||||
|
||||
4. Layout содержит только провайдеры и вызов layout-компонента — не вёрстку.
|
||||
|
||||
## Смежные триггеры
|
||||
|
||||
- triggers/develop/create-page.md — страницы внутри layout
|
||||
- triggers/develop/create-component.md — layout-компонент в `layouts/`
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Вёрстка вынесена в layout-компонент в `layouts/`
|
||||
- [ ] layout.tsx содержит только провайдеры и вызов layout-компонента
|
||||
36
src/nextjs/triggers/develop/create-page.md
Normal file
36
src/nextjs/triggers/develop/create-page.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Создать страницу
|
||||
---
|
||||
|
||||
# Создать страницу
|
||||
|
||||
Инструкция по добавлению нового route в Next.js проект. Страница — это экран + page.tsx.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- applied/page-level.md — правила файлов роутинга: page.tsx, layout.tsx, metadata
|
||||
- applied/project-structure.md — где располагаются файлы
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Сгенерируй экран из шаблона `screen` в `src/screens/` (→ triggers/develop/generate-module.md).
|
||||
|
||||
2. Заполни экран логикой и стилями.
|
||||
|
||||
3. Создай `page.tsx` в нужном маршруте `src/app/`.
|
||||
- page.tsx тонкий: только `metadata` и рендер экрана
|
||||
- Никакой логики, стилей и хуков в page.tsx
|
||||
|
||||
4. Добавь `metadata` с `title` (→ applied/page-level.md).
|
||||
|
||||
## Смежные триггеры
|
||||
|
||||
- triggers/develop/generate-module.md — генерация экрана из шаблона
|
||||
- triggers/develop/create-layout.md — если нужен новый layout для маршрута
|
||||
- triggers/develop/create-component.md — компоненты внутри экрана
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Экран создан из шаблона `screen` в `src/screens/`
|
||||
- [ ] page.tsx тонкий — только metadata и рендер экрана
|
||||
- [ ] metadata содержит title и description
|
||||
52
src/nextjs/triggers/develop/create-project.md
Normal file
52
src/nextjs/triggers/develop/create-project.md
Normal file
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: Создать проект
|
||||
scope: applied
|
||||
keywords: [создать проект, новый проект, tiged, шаблон проекта, init]
|
||||
when: "Создание нового Next.js проекта из шаблона"
|
||||
---
|
||||
|
||||
# Создать проект
|
||||
|
||||
Инструкция по созданию нового Next.js проекта из готового шаблона. Проект готов к разработке сразу после установки зависимостей.
|
||||
|
||||
## Прочитай перед началом
|
||||
|
||||
- basics/getting-started.md — знакомство со стеком и особенностями проекта
|
||||
- applied/project-structure.md — структура папок и файлов
|
||||
|
||||
## Шаги
|
||||
|
||||
1. Создай проект из шаблона:
|
||||
|
||||
```bash
|
||||
npx tiged git@gromlab.ru:templates/nextjs.git my-app
|
||||
cd my-app
|
||||
npm install
|
||||
```
|
||||
|
||||
2. Ознакомься со структурой проекта (→ applied/project-structure.md).
|
||||
|
||||
3. Настрой VS Code (→ triggers/develop/setup-vscode.md).
|
||||
|
||||
## Что входит в шаблон
|
||||
|
||||
- Next.js + TypeScript (App Router)
|
||||
- Mantine UI + PostCSS Modules
|
||||
- Biome (линтинг и форматирование)
|
||||
- Zustand, SWR
|
||||
- Структура FSD (`screens/`, `widgets/`, `features/`, `entities/`, `shared/`)
|
||||
- Шаблоны генерации (`.templates/`)
|
||||
- Конфигурация VS Code (`.vscode/`)
|
||||
- CSS-токены (цвета, отступы, радиусы, медиа)
|
||||
- Open Graph метаданные
|
||||
|
||||
## Смежные триггеры
|
||||
|
||||
- triggers/develop/setup-vscode.md — настройка редактора
|
||||
- triggers/develop/create-page.md — добавление первой страницы
|
||||
|
||||
## Проверь себя
|
||||
|
||||
- [ ] Проект создан из шаблона через `npx tiged`
|
||||
- [ ] Зависимости установлены
|
||||
- [ ] VS Code настроен (→ triggers/develop/setup-vscode.md)
|
||||
Reference in New Issue
Block a user